spey.backends.default_pdf.EffectiveSigma#

class spey.backends.default_pdf.EffectiveSigma(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, correlation_matrix: ndarray, absolute_uncertainty_envelops: List[Tuple[float, float]], modifiers: List[Dict[str, Any]] | None = None, n_signal_parameters: int = 0, signal_parameter_bounds: List[Tuple[float | None, float | None]] | None = None)[source]#

Simplified likelihood with asymmetric (effective-sigma) background uncertainties (default.effective_sigma).

This backend handles asymmetric background uncertainties through the variable-Gaussian (effective-\(\sigma\)) approach of [arXiv:physics/0406120] Sec. 3.6, eqs. 18–19. Given per-bin upper and lower absolute uncertainties \(\sigma^+_i\) and \(\sigma^-_i\), an effective width is defined that depends on the nuisance-parameter value:

\[\sigma^{\rm eff}_i(\theta_i) = \sqrt{\sigma^+_i \sigma^-_i + (\sigma^+_i - \sigma^-_i)(\theta_i - n^b_i)},\]

clipped from below at \(10^{-10}\) for numerical stability. The full likelihood is

\[\mathcal{L}(\mu, \boldsymbol{\theta}) = \prod_{i=1}^{N} \mathrm{Poiss}\!\left(n^{\rm obs}_i \,\Big|\, \mu\, n^s_i \cdot f(\boldsymbol{\theta}_{\rm sig}) + n^b_i + \theta_i\, \sigma^{\rm eff}_i(\theta_i)\right) \cdot \mathcal{N}(\boldsymbol{\theta} \mid \mathbf{0},\, \rho),\]

where \(\rho\) is a user-supplied correlation matrix.

Note

The positivity constraint

\[n^b_i + \theta_i\, \sigma^{\rm eff}_i(\theta_i) \geq 0\]

is enforced via a NonlinearConstraint during optimisation.

When \(\sigma^+_i = \sigma^-_i \equiv \sigma_i\) the effective sigma reduces to the constant \(\sigma_i\), recovering the symmetric CorrelatedBackground result.

Parameters:

signal_yields (np.ndarray | Callable[[np.ndarray], np.ndarray]) – Per-bin signal yields \(\{n^s_i\}\), or a callable that accepts the extra signal parameters pars[1 : 1 + n_signal_parameters] and returns the per-bin yields as a np.ndarray.
background_yields (np.ndarray) – Per-bin expected background yields \(\{n^b_i\}\).
data (np.ndarray) – Per-bin observed counts \(\{n^{\rm obs}_i\}\).
correlation_matrix (np.ndarray) – \(N \times N\) inter-bin correlation matrix \(\rho\).
absolute_uncertainty_envelops (List[Tuple[float, float]]) – Per-bin pairs \((\sigma^+_i, \sigma^-_i)\) of upper and lower absolute background uncertainties. Both values are taken as absolute (sign is ignored).
modifiers (List[Dict[str, Any]], default None) –
Optional list of signal-uncertainty modifier configuration dictionaries. Each dictionary must contain:
- "type" (str, required): morphing mode, either
  - "normalization" — one shared nuisance parameter for all bins (e.g. PDF uncertainties, luminosity);
  - "shape" — one independent nuisance parameter per bin (e.g. scale uncertainties, theory prediction statistics).
- "uncertainties" (List[float] | List[Tuple[float, float]], required): absolute uncertainty values per bin. Use a flat list[float] for symmetric uncertainties, or a list[(up, down)] for asymmetric ones.
- "name" (str, optional): label used for parameter naming; defaults to "mod0", "mod1", …
Not supported when signal_yields is a callable.

Example:
```
modifiers = [
    {"type": "normalization", "name": "pdf",
     "uncertainties": [0.6, 1.0]},
    {"type": "shape", "name": "scale",
     "uncertainties": [(0.3, 0.4), (0.5, 0.6)]},
]
```
n_signal_parameters (int, default 0) – Number of additional free parameters accepted by a callable signal_yields. Has no effect when signal_yields is a plain array. See DefaultPDFBase for the parameter-vector layout.
signal_parameter_bounds (List[Tuple[Optional[float], Optional[float]]] | None) – Optimiser bounds for each extra signal parameter. Each entry is a (lower, upper) pair; use None for an unbounded side. When None, every extra signal parameter receives (None, None). Must have exactly n_signal_parameters entries when provided.

References

Barlow, R., Asymmetric Errors, [arXiv:physics/0406120] Sec. 3.6, eqs. 18–19.

__init__(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, correlation_matrix: ndarray, absolute_uncertainty_envelops: List[Tuple[float, float]], modifiers: List[Dict[str, Any]] | None = None, n_signal_parameters: int = 0, signal_parameter_bounds: List[Tuple[float | None, float | None]] | None = None)[source]#

Methods

`__init__`(signal_yields, background_yields, ...)
`asimov_negative_loglikelihood`([poi_test, ...])	Compute the profiled negative log-likelihood at fixed \(\mu\) on Asimov data.
`combine`(other, **kwargs)	Combine this statistical model with another backend instance.
`config`([allow_negative_signal, poi_upper_bound])	Model configuration.
`expected_data`(pars[, include_auxiliary])	Compute the expected data vector at the given parameter point.
`get_hessian_logpdf_func`([expected, data])	Return a callable that evaluates the Hessian of \(\ln\mathcal{L}(\mu, \boldsymbol{\theta})\).
`get_logpdf_func`([expected, data])	Return a callable that evaluates \(\ln\mathcal{L}(\mu, \boldsymbol{\theta})\).
`get_objective_function`([expected, data, do_grad])	Return the objective function \(-\ln\mathcal{L}(\mu, \boldsymbol{\theta})\) used by the optimiser.
`get_sampler`(pars)	Return a callable that draws pseudo-data from the statistical model.
`minimize_asimov_negative_loglikelihood`([...])	Find the global minimum of the negative log-likelihood on Asimov data (free fit).
`minimize_negative_loglikelihood`([expected, ...])	Find the global minimum of the negative log-likelihood (free fit).
`negative_loglikelihood`([poi_test, expected])	Compute the profiled negative log-likelihood at a fixed \(\mu\).

Attributes

`constraints`	Constraints to be used during optimisation process
`signal_uncertainty_configuration`
`arXiv`	arXiv reference for the backend
`author`	Author of the backend
`constraint_model`	Constraint model distribution \(\mathcal{C}(\boldsymbol{\theta})\).
`doi`	Citable DOI for the backend
`is_alive`	Returns True if at least one bin has non-zero signal yield.
`main_model`	Main model distribution — the Poisson term of the likelihood.
`name`	Name of the backend
`spey_requires`	Spey version required for the backend
`version`	Version of the backend

spey.backends.default_pdf.EffectiveSigma

Contents

spey.backends.default_pdf.EffectiveSigma#