spey.backends.default_pdf.CorrelatedBackground#

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

Multi-bin simplified likelihood with correlated background uncertainties (default.correlated_background).

This backend implements the simplified likelihood of [arXiv:1809.05548]. Inter-bin background correlations are encoded in a user-supplied covariance matrix \(\Sigma\), which is decomposed into per-bin standard deviations \(\sigma_i = \sqrt{\Sigma_{ii}}\) and a correlation matrix \(\rho\). The full likelihood is

\[\mathcal{L}_{\rm SL}(\mu, \boldsymbol{\theta}) = \underbrace{ \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 + \sigma_i \theta_i \right) }_{\text{main model}} \cdot \underbrace{ \mathcal{N}(\boldsymbol{\theta} \mid \mathbf{0},\, \rho) }_{\text{constraint model}},\]

where \(\rho_{ij} = \Sigma_{ij} / (\sigma_i \sigma_j)\) is the correlation matrix. The constraint \(n^b_i + \sigma_i \theta_i \geq 0\) is enforced during optimisation.

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\}\).
covariance_matrix (np.ndarray) – \(N \times N\) background covariance matrix \(\Sigma\). Diagonal entries are squared absolute uncertainties \(\sigma_i^2\).
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.

Note

All array inputs must share the same first dimension \(N\). The covariance_matrix must be a square \(N \times N\) matrix.

Example:

>>> import spey
>>> stat_wrapper = spey.get_backend('default.correlated_background')
>>> signal_yields = [12.0, 11.0]
>>> background_yields = [50.0, 52.0]
>>> data = [51, 48]
>>> covariance_matrix = [[3., 0.5], [0.6, 7.]]
>>> statistical_model = stat_wrapper(
...     signal_yields, background_yields, data, covariance_matrix
... )
>>> print(statistical_model.exclusion_confidence_level())

__init__(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, covariance_matrix: ndarray, 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`
`author`	Author of the backend
`constraint_model`	Constraint model distribution \(\mathcal{C}(\boldsymbol{\theta})\).
`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.CorrelatedBackground

Contents

spey.backends.default_pdf.CorrelatedBackground#