spey.backends.default_pdf.ThirdMomentExpansion#

class spey.backends.default_pdf.ThirdMomentExpansion(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, covariance_matrix: ndarray, third_moment: 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]#

Simplified likelihood with third-moment expansion to account for skewed background distributions (default.third_moment_expansion).

This backend extends CorrelatedBackground by incorporating the third central moment (skewness) of the background distribution, following [arXiv:1809.05548] Sec. 2. Given the first three moments,

\(m^{(1)}_i\) — expected background yield (mean),
\(m^{(2)}_{ij}\) — covariance matrix,
\(m^{(3)}_i\) — diagonal elements of the third-moment tensor (skewness),

the \(\lambda\) function receives a quadratic correction and the correlation matrix is reparametrised. Define per-bin coefficients:

\[\begin{split}C_i &= -\mathrm{sign}(m^{(3)}_i)\,\sqrt{2\, m^{(2)}_{ii}} \cos\!\left(\frac{4\pi}{3} + \frac{1}{3}\arctan\!\sqrt{\frac{8\,(m^{(2)}_{ii})^3}{(m^{(3)}_i)^2} - 1} \right) \\[4pt] B_i &= \sqrt{m^{(2)}_{ii} - 2C_i^2} \\[4pt] A_i &= m^{(1)}_i - C_i.\end{split}\]

The inter-bin correlation matrix is then modified to

\[\rho_{ij} = \frac{1}{4C_i C_j} \left(\sqrt{(B_i B_j)^2 + 8 C_i C_j m^{(2)}_{ij}} - B_i B_j\right),\]

and the expected-count function becomes

\[\lambda_i(\mu, \theta_i) = \mu\, n^s_i \cdot f(\boldsymbol{\theta}_{\rm sig}) + A_i + B_i \theta_i + C_i \theta_i^2,\]

with the constraint model

\[\mathcal{C}(\boldsymbol{\theta}) = \mathcal{N}(\boldsymbol{\theta} \mid \mathbf{0},\, \rho^{-1}).\]

The quadratic \(C_i \theta_i^2\) term captures the asymmetry of the background distribution; when \(m^{(3)}_i = 0\) the expansion reduces to the standard simplified likelihood.

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 \(\{m^{(1)}_i\}\).
data (np.ndarray) – Per-bin observed counts.
covariance_matrix (np.ndarray) – \(N \times N\) covariance matrix \(\{m^{(2)}_{ij}\}\).
third_moment (np.ndarray) – Per-bin diagonal third-moment values \(\{m^{(3)}_i\}\). Must have length \(N\).
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\), and covariance_matrix must be \(N \times N\).

References

[arXiv:1809.05548], Sec. 2.

__init__(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, covariance_matrix: ndarray, third_moment: 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`
`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.ThirdMomentExpansion

Contents

spey.backends.default_pdf.ThirdMomentExpansion#