MultiplicativeRandomJitter#

class MultiplicativeRandomJitter(sigma=0.05, clip=0.05, keys=('energy',), p=0.5)[source]#

Bases: object

Multiply one or more keys by clipped Gaussian noise around 1.

With probability p, scales each listed key in place by 1 + noise, where noise is Gaussian (std sigma) clamped to [-clip, clip] and has the same shape as the target. Intended for scalar per-point features such as energy/charge where multiplicative fluctuation is the physical noise model. Requires each listed key to be present (raises ValueError otherwise). Registered as MultiplicativeRandomJitter – use this string as the type in a transform=[...] config list.

Parameters:

  • sigma (float) – standard deviation of the multiplicative noise term. Defaults to 0.05.

  • clip (float) – magnitude the noise is clamped to (must be > 0). Defaults to 0.05.

  • keys (str | Sequence[str]) – keys to scale. A bare string is wrapped into a single-element tuple. Defaults to ("energy",).

  • p (float) – probability of applying the jitter. Defaults to 0.5.

Example

>>> import numpy as np
>>> from pimm.datasets.transform import MultiplicativeRandomJitter
>>> np.random.seed(0)
>>> data = {"energy": np.array([[100.], [100.], [100.]], dtype="f4")}
>>> # scales each value by 1 + noise, noise in [-0.05, 0.05]
>>> out = MultiplicativeRandomJitter(sigma=0.05, clip=0.05,
...                                  keys=("energy",), p=1.0)(data)
>>> bool(np.all(out["energy"] >= 95.0)) and bool(np.all(out["energy"] <= 105.0))
True
>>> bool(np.any(out["energy"] != 100.0))  # values fluctuated around 100
True