Modifier

class BooleanMask(*args: Any, **kwargs: Any)

Bases: ModifierBase

Applies a modifier only to bins selected by a boolean mask.

Parameters:

• mask – Boolean array indicating which bins receive the modifier.

• modifier – Modifier that provides the offsets and scales.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> hist = jnp.array([5, 20, 30])
>>> syst = evm.NormalParameter(value=0.1)
>>> norm = syst.scale_log_asymmetric(up=1.1, down=0.9)
>>> mask = jnp.array([True, False, True])
>>> modifier = evm.modifier.BooleanMask(mask, norm)
>>> modifier(hist)
Array([ 5.049494, 20.      , 30.296963], dtype=float32)

class Compose(*args: Any, **kwargs: Any)

Bases: ModifierBase

Combines multiple modifiers and applies them in parallel.

Modifiers are grouped by their NNX graph structure and vectorized using XLA. The combined effect multiplies all scale factors together and adds all offsets to the input histogram. This corresponds to the standard HistFactory-style combination of independent systematic effects.

Note: This is parallel composition, not sequential chaining. For pure scale modifiers the two are equivalent, but when offsets are involved the order-independent parallel combination is used.

Parameters:

*modifiers – Modifiers to compose. They are flattened if nested Compose instances are provided.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> mu = evm.Parameter(value=1.1)
>>> syst = evm.NormalParameter(value=0.1)
>>> hist = jnp.array([10, 20, 30])
>>> composition = evm.modifier.Compose(
...     mu.scale(offset=0, slope=1),
...     syst.scale_log_asymmetric(up=1.1, down=0.9),
... )
>>> composition(hist)
Array([11.155, 22.237, 33.318], dtype=float32)

class Modifier(*args: Any, **kwargs: Any)

Bases: ModifierBase

Pairs a parameter with an effect to build a modifier.

Parameters:

• parameter – Parameter instance that provides the nuisance strength.

• effect – Effect describing how the histogram is altered.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> modifier = evm.Modifier(
...     value=1.1,
...     effect=evm.effect.Linear(offset=0.0, slope=1.0),
... )
>>> modifier(jnp.array([10, 20, 30]))
Array([11., 22., 33.], dtype=float32)

class ModifierBase(*args: Any, **kwargs: Any)

Bases: Module

Base class for modules that modify histogram templates.

Subclasses implement offset_and_scale() and automatically gain a callable interface as well as support for composition via the matrix multiplication operator.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> modifier = evm.Parameter(1.0).scale()
>>> modifier(jnp.array([10.0, 20.0]))
Array([10., 20.], dtype=float32)

class Transform(*args: Any, **kwargs: Any)

Bases: ModifierBase

Applies a transformation to both offset and scale of a modifier.

Parameters:

• transform_fn – Callable applied to each leaf of the offset and scale.

• modifier – Modifier supplying the original offset and scale values.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> hist = jnp.array([5, 20, 30])
>>> syst = evm.NormalParameter(value=0.1)
>>> norm = syst.scale_log_asymmetric(up=1.1, down=0.9)
>>> transformed_norm = evm.modifier.Transform(jnp.sqrt, norm)
>>> transformed_norm(hist)
Array([ 5.024686, 20.098743, 30.148115], dtype=float32)

class TransformOffset(*args: Any, **kwargs: Any)

Bases: ModifierBase

Transforms only the offset component of another modifier.

Parameters:

• transform_fn – Callable applied to the offset leaves.

• modifier – Modifier providing the original offset values.

class TransformScale(*args: Any, **kwargs: Any)

Bases: ModifierBase

Transforms only the multiplicative scale component of another modifier.

Parameters:

• transform_fn – Callable applied to the scale leaves.

• modifier – Modifier providing the original scale values.

class Where(*args: Any, **kwargs: Any)

Bases: ModifierBase

Chooses between two modifiers based on a boolean condition.

Parameters:

• condition – Boolean array indicating where to apply modifier_true.

• modifier_true – Modifier evaluated where condition is True.

• modifier_false – Modifier evaluated where condition is False.

Examples

>>> import jax.numpy as jnp
>>> import evermore as evm
>>> hist = jnp.array([5, 20, 30])
>>> syst = evm.NormalParameter(value=0.1)
>>> norm = syst.scale_log_asymmetric(up=jnp.array([1.1]), down=jnp.array([0.9]))
>>> shape = syst.morphing(
...     up_template=jnp.array([7, 22, 31]),
...     down_template=jnp.array([4, 16, 27]),
... )
>>> modifier = evm.modifier.Where(hist < 10, norm, shape)
>>> modifier(hist)
Array([ 5.049494, 20.281374, 30.181376], dtype=float32)