Default Backends

Default Backends#

Backends shipped with spey.

The spey.backends subpackage hosts the built-in statistical-model backends and the differentiable distribution helpers they are built on:

  • spey.backends.distributions — autograd-compatible Poisson, Normal, MultivariateNormal distributions plus the MainModel / ConstraintModel wrappers.

  • spey.backends.default_pdf — the four registered default backends (default.uncorrelated_background, default.correlated_background, default.third_moment_expansion, default.effective_sigma) plus the three simple variants (default.poisson, default.normal, default.multivariate_normal) and the signal-uncertainty synthesizer used by the morphing-aware variants.

Third-party backends register themselves via the spey.backend.plugins entry point; see spey.register_backend() and the plugin tutorial.

Default PDF Backends#

This module implements four built-in statistical model backends that cover the most common simplified-likelihood constructions used in particle-physics analyses. All four share a common base class (DefaultPDFBase) and therefore the same gradient-enabled evaluation infrastructure (via autograd).

Overview of the likelihood structure#

Every backend decomposes the likelihood into a main model and a constraint model:

\[\mathcal{L}(\mu, \boldsymbol{\theta}) = \underbrace{\prod_{i=1}^{N} \mathrm{Poiss}\!\left(n_i^{\rm obs} \,\big|\, \lambda_i(\mu, \boldsymbol{\theta})\right)}_{\text{main model}} \cdot \underbrace{\mathcal{C}(\boldsymbol{\theta})}_{\text{constraint model}}\]

where \(\mu\) is the signal-strength parameter of interest, \(\boldsymbol{\theta}\) is the vector of nuisance parameters (one per bin), \(n_i^{\rm obs}\) are the observed counts, and \(\lambda_i\) is the expected count in bin \(i\).

The four backends differ only in how \(\lambda_i\) and \(\mathcal{C}\) are parametrised.

Available Backends#

default.uncorrelated_background — UncorrelatedBackground

Independent per-bin Gaussian constraints; bins are treated as uncorrelated.

\[\begin{split}\lambda_i(\mu, \theta_i) &= \mu\, n^s_i + n^b_i + \theta_i \sigma_i \\[4pt] \mathcal{C}(\boldsymbol{\theta}) &= \prod_{i=1}^{N} \mathcal{N}(\theta_i \mid 0, 1)\end{split}\]

where \(\sigma_i\) is the absolute background uncertainty in bin \(i\). The constraint \(n^b_i + \theta_i \sigma_i \geq 0\) is enforced during optimisation.

UncorrelatedBackground(signal_yields, ...[, ...])

Single- or multi-bin simplified likelihood with uncorrelated background uncertainties (default.uncorrelated_background).
default.correlated_background — CorrelatedBackground

Simplified likelihood [arXiv:1809.05548] with a multivariate normal constraint that captures inter-bin background correlations.

\[\begin{split}\lambda_i(\mu, \theta_i) &= \mu\, n^s_i + n^b_i + \sigma_i \theta_i \\[4pt] \mathcal{C}(\boldsymbol{\theta}) &= \mathcal{N}(\boldsymbol{\theta} \mid \mathbf{0}, \rho)\end{split}\]

where \(\sigma_i = \sqrt{\Sigma_{ii}}\) are the per-bin background uncertainties and \(\rho\) is the correlation matrix derived from the user-supplied covariance matrix \(\Sigma\).

CorrelatedBackground(signal_yields, ...[, ...])

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

Extends the simplified likelihood by including third-moment (skewness) information to better describe asymmetric uncertainties [arXiv:1809.05548]. The \(\lambda\) function receives a quadratic correction:

\[\lambda_i(\mu, \theta_i) = \mu\, n^s_i + A_i + B_i \theta_i + C_i \theta_i^2\]

with \(A_i\), \(B_i\), \(C_i\) derived from the first three moments of the background distribution, and \(\rho\) is modified accordingly. See ThirdMomentExpansion for the full expressions.

ThirdMomentExpansion(signal_yields, ...[, ...])

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

Variable-Gaussian (effective-\(\sigma\)) approach inspired by [arXiv:physics/0406120] Sec. 3.6. Asymmetric uncertainties \((\sigma^+_i, \sigma^-_i)\) are absorbed into a \(\theta\)-dependent effective width:

\[\begin{split}\sigma^{\rm eff}_i(\theta_i) &= \sqrt{\sigma^+_i \sigma^-_i + (\sigma^+_i - \sigma^-_i)(\theta_i - n^b_i)} \\[4pt] \lambda_i(\mu, \theta_i) &= \mu\, n^s_i + n^b_i + \theta_i\, \sigma^{\rm eff}_i(\theta_i)\end{split}\]

The constraint model is a multivariate normal with a user-supplied correlation matrix.

EffectiveSigma(signal_yields, ...[, ...])

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

Parameter layout#

All backends use the same parameter-vector convention:

pars = [μ, θ₁, θ₂, …, θ_N, (signal-uncertainty pars)]

  • Index 0: signal strength \(\mu\) (the parameter of interest, POI).

  • Indices 1…N: per-bin nuisance parameters \(\theta_i\).

  • Remaining indices: optional parameters introduced by signal-uncertainty modifiers.

References

DefaultPDFBase(signal_yields, ...[, ...])

Abstract base class shared by all default PDF backends.

Third-Moment Expansion Tools#

This module provides the mathematical machinery for the third-moment expansion of the simplified likelihood, following [arXiv:1809.05548] Sec. 2.

Motivation#

The standard simplified likelihood models background uncertainties as a multivariate normal distribution centred at zero with covariance \(\Sigma\). This is exact only when the background fluctuations are themselves Gaussian. When significant asymmetry (skewness) is present — as is common for small background yields or log-normal-shaped systematic uncertainties — the Gaussian approximation can over- or under-cover.

The third-moment expansion extends the simplified likelihood by incorporating the diagonal elements of the third central moment tensor \(m^{(3)}_i\), which characterise the skewness of the background distribution in each bin.

Mathematical background#

Given the first three moments of the background:

  • \(m^{(1)}_i\) — expected value (mean),

  • \(m^{(2)}_{ij}\) — covariance matrix (\(\Sigma_{ij}\)),

  • \(m^{(3)}_i\) — diagonal third central moments (skewness per bin),

one defines per-bin coefficients via eqs. 2.9–2.11 of [arXiv:1809.05548]:

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

These coefficients enter the quadratic \(\lambda\) function (eq. 2.6 of [arXiv:1809.05548]):

\[\lambda_i(\mu, \theta_i) = \mu\, n^s_i + A_i + B_i\,\theta_i + C_i\,\theta_i^2,\]

and a modified inter-bin correlation matrix (eq. 2.12 of [arXiv:1809.05548]):

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

Validity condition: the expansion requires \(8\,\Sigma_{ii}^3 \geq (m^{(3)}_i)^2\) for each bin. Bins that violate this condition are treated with \(C_i = 0\) (reverting to the standard simplified likelihood for that bin).

When \(m^{(3)}_i = 0\) for all bins the expansion reduces identically to the standard simplified likelihood (CorrelatedBackground).

third_moment_expansion(expectation_value, ...)

Compute the \(A\), \(B\), \(C\) coefficients and optional modified correlation matrix for the third-moment expansion of the simplified likelihood.

Computing third moments from asymmetric uncertainties#

When only asymmetric uncertainty envelopes \((\sigma^+_i, \sigma^-_i)\) are available, the third moment can be estimated analytically by modelling the background as a bifurcated Gaussian — a piecewise normal distribution that uses \(\sigma^-_i\) for \(\theta < 0\) and \(\sigma^+_i\) for \(\theta \geq 0\):

\[\begin{split}p(\theta) = \frac{2}{\sigma^+_i + \sigma^-_i} \begin{cases} \mathcal{N}(\theta \mid 0, \sigma^-_i), & \theta < 0, \\ \mathcal{N}(\theta \mid 0, \sigma^+_i), & \theta \geq 0. \end{cases}\end{split}\]

The third central moment of this distribution is

\[m^{(3)}_i = \frac{2}{\sigma^+_i + \sigma^-_i} \left[\sigma^-_i \int_{-\infty}^{0} \theta^3\, \mathcal{N}(\theta\mid 0,\sigma^-_i)\,d\theta + \sigma^+_i \int_{0}^{\infty} \theta^3\, \mathcal{N}(\theta\mid 0,\sigma^+_i)\,d\theta\right],\]

which is computed numerically by compute_third_moments(). See [arXiv:2602.18611] for a usecase.

compute_third_moments(...[, ...])

Estimate the diagonal third central moments \(\{m^{(3)}_i\}\) from asymmetric uncertainty envelopes using a bifurcated Gaussian model.

References

  • CMS Collaboration, Simplified likelihood for the re-interpretation of public CMS results, [arXiv:1809.05548], Sec. 2.

  • CMS Collaboration, Combined measurements and interpretations of Higgs boson production and decay in proton-proton collisions at \(\sqrt{s} = 13\) TeV, [arXiv:2602.18611]

Theoretical Uncertainties#

This module implements the log-normal morphing scheme used to propagate signal systematic uncertainties through the simplified-likelihood backends.

Motivation#

Simplified likelihood backends parametrise background uncertainties through nuisance parameters \(\boldsymbol{\theta}\) that enter the Poisson mean \(\lambda_i\). Signal yields, however, are often treated as fixed. When the signal itself carries non-negligible uncertainties (e.g. from theoretical scale variations, PDF uncertainties, or detector modelling), those uncertainties must also be profiled.

The synthesizer introduces additional nuisance parameters per uncertainty source and applies a multiplicative correction to the signal yields. This keeps the signal positive for all nuisance values and is consistent with the log-normal morphing conventions widely used in HEP (e.g. HistFactory).

Two morphing modes are supported, selected via the "type" key of each modifier configuration dictionary:

  • normalization — one nuisance parameter \(\theta_k\) shared across all bins. The factor \(f_{i,k}(\theta_k)\) is the same for every bin modulo the per-bin fractional variation \(\Delta_{i,k}\). Use this for correlated uncertainties such as PDF variations or luminosity, where a single degree of freedom simultaneously shifts all bins.

  • shape — one independent nuisance parameter \(\alpha_{i,k}\) per bin. Each bin is shifted independently. Use this for uncorrelated uncertainties such as statistical uncertainties on theory predictions or scale uncertainties that affect each bin differently.

Log-normal morphing#

For each uncertainty source \(k\) and bin \(i\), a fractional variation \(\Delta_{i,k}\) is defined as

\[\Delta_{i,k} = \frac{\sigma^{(s)}_{i,k}}{n^{(s)}_i},\]

where \(n^{(s)}_i\) is the nominal signal yield and \(\sigma^{(s)}_{i,k}\) is the absolute uncertainty from source \(k\) in bin \(i\).

Normalization modifier ("type": "normalization")

A single nuisance parameter \(\theta_k\) is shared across all bins. The morphing factor for source \(k\) is

\[f_{i,k}(\theta_k) = \exp\!\left[\theta_k \ln\!\bigl(1 + \Delta_{i,k}(\theta_k)\bigr)\right],\]

where the effective variation depends on the sign of \(\theta_k\):

\[\begin{split}\Delta_{i,k}(\theta_k) = \begin{cases} \Delta_{i,k}^{+}, & \theta_k \geq 0 \\ \Delta_{i,k}^{-}, & \theta_k < 0 \end{cases}\end{split}\]

(symmetric uncertainties use \(\Delta^+ = \Delta^-\)).

Shape modifier ("type": "shape")

Each bin \(i\) has its own independent nuisance parameter \(\alpha_{i,k}\), so the morphing factor is

\[f_{i,k}(\alpha_{i,k}) = \exp\!\left[\alpha_{i,k} \ln\!\bigl(1 + \Delta_{i,k}(\alpha_{i,k})\bigr)\right],\]

with \(\Delta_{i,k}(\alpha_{i,k})\) chosen by the sign of \(\alpha_{i,k}\) as above. The per-bin parameters are uncorrelated; each is constrained by an independent standard normal prior.

Combined modifier

When multiple sources are present the total signal modifier is the product of the individual morphing factors:

\[f_i(\boldsymbol{\theta}_{\rm sig}) = \prod_k f_{i,k} = \exp\!\left[\sum_k \ln f_{i,k}\right].\]

The effective signal yield in bin \(i\) thus becomes \(\mu\, n^{(s)}_i \cdot f_i(\boldsymbol{\theta}_{\rm sig})\).

Each nuisance parameter is constrained by a standard normal prior \(\mathcal{N}(\theta \mid 0, 1)\), which is added to the constraint model of the calling backend.

Parameter layout#

Signal uncertainty parameters are appended to the end of the parameter vector after the background nuisance parameters:

pars = [μ, θ₁, …, θ_N,  θ_{sig,1}, …]

For a normalization modifier, one parameter is appended; for a shape modifier, \(N_{\rm bins}\) parameters are appended (one per bin). The domain field in each constraint dictionary records the index of the corresponding parameter in this vector.

Bins with zero nominal signal yield (\(n^{(s)}_i = 0\)) produce \(\Delta_{i,k} = \mathrm{NaN}\), which is replaced by 1 (no modification) so the exponential evaluates to 1 for those bins.

signal_uncertainty_synthesizer(...[, ...])

Synthesize signal uncertainties from a list of modifier configuration dictionaries.

Why there are two choices of modifiers?#

This module is designed with PDF and scale uncertainties in mind. Neither PDF uncertainties nor QCD scale uncertainties are typically pure normalisation uncertainties. Both originate from the theoretical calculation of the signal cross-section and can alter the shape of any differential distribution used as a discriminating observable.

PDF uncertainties come from the parametric uncertainty in the parton distribution functions. Because different parton flavours and momentum fractions dominate different kinematic regimes, varying PDF eigenvectors or replicas (following the PDF4LHC prescription in [13]) changes both the inclusive cross-section and the relative contributions of different kinematic regions. In a multi-bin fit over, say, invariant mass or MET, PDF variations therefore produce correlated, bin-dependent rate changes that affect the shape of the template.

QCD scale uncertainties (\(\mu_R\) and \(\mu_F\) variations by conventional factors of 2) are proxies for missing higher-order corrections. Because fixed-order corrections are themselves kinematic-dependent, e.g., they grow with the hardness of the event, scale variations tend to affect the high-end tail of a distribution differently from the bulk. This is well documented: for example, ATLAS measurements of t-tbar differential distributions [14] and inclusive cross-section analyses consistently show bin-dependent scale-variation envelopes.

In both cases, the dominant effect is often a normalisation shift, but the shape change is physically real and in a multi-bin analysis, it is generally not safe to discard it.

Simple PDFs#

Nuisance-Free (Simple) Likelihood Backends#

This module provides three backend classes that implement nuisance-free (or trivially-marginalised) likelihoods in which the expected counts depend only on the signal strength \(\mu\) — no per-bin systematic nuisance parameters appear in the optimisation.

All three share SimplePDFBase, which stores signal and background yields, constructs the minimum-POI bound, and provides the standard get_objective_function(), get_logpdf_func(), and get_hessian_logpdf_func() interfaces required by the spey optimisation engine.

Available backends#

default.poisson — Poisson

Pure Poisson likelihood. Each bin contributes independently:

\[\mathcal{L}(\mu) = \prod_{i=1}^{N} \mathrm{Poiss}\!\left(n^{\rm obs}_i \,\big|\, \mu n^s_i + n^b_i\right).\]

An optional absolute_uncertainties argument extends the model with unconstrained per-bin nuisance parameters:

\[\mathcal{L}(\mu, \boldsymbol{\theta}) = \prod_{i=1}^{N} \mathrm{Poiss}\!\left(n^{\rm obs}_i \,\big|\, \mu n^s_i + n^b_i + \theta_i \sigma_i\right).\]

Poisson(signal_yields, background_yields, data)

Pure Poisson likelihood (default.poisson).
default.normal — Gaussian

Product of independent Gaussians (uncorrelated):

\[\mathcal{L}(\mu) = \prod_{i=1}^{N} \frac{1}{\sigma_i \sqrt{2\pi}} \exp\!\left[-\frac{(\mu n^s_i + n^b_i - n^{\rm obs}_i)^2} {2\sigma_i^2}\right].\]

This is appropriate when the expected counts are large enough that Poisson statistics can be well approximated by a Gaussian.

Gaussian(signal_yields, background_yields, ...)

Product of independent Gaussians — uncorrelated normal likelihood (default.normal).
default.multivariate_normal — MultivariateNormal

Multivariate Gaussian with an arbitrary (possibly \(\mu\)-dependent) covariance matrix:

\[\mathcal{L}(\mu) = \frac{1}{\sqrt{(2\pi)^N \det\Sigma}} \exp\!\left[-\tfrac{1}{2} (\boldsymbol{\lambda}(\mu) - \mathbf{n}^{\rm obs})^\top \Sigma^{-1} (\boldsymbol{\lambda}(\mu) - \mathbf{n}^{\rm obs})\right],\]

where \(\lambda_i(\mu) = \mu n^s_i + n^b_i\). The covariance matrix \(\Sigma\) may be a constant array or a callable of the full parameter vector, enabling \(\mu\)-dependent uncertainties.

MultivariateNormal(signal_yields, ...[, ...])

Multivariate Normal likelihood with optional parameter-dependent covariance (default.multivariate_normal).

Parameter layout#

All simple backends use a minimal parameter vector:

pars = [μ, (signal_par_0, signal_par_1, …)]

Index 0 is always \(\mu\). Additional signal parameters are only present when MultivariateNormal is initialised with a callable signal_yields and n_signal_parameters > 0.

Minimum POI bound#

The lower bound on \(\mu\) is set to the most negative signal strength for which no bin has negative expected yield,

\[\mu_{\min} = -\min_{i:\,n^s_i > 0} \frac{n^b_i}{n^s_i},\]

matching the convention used in the other default PDF backends. When signal_yields is a callable the bound is set to \(-\infty\).

SimplePDFBase(signal_yields, ...[, ...])

Abstract base class for nuisance-free (simple) PDF backends.

Distributions#

Poisson(loc)

Poisson distribution

Normal(loc, scale[, domain])

Normal distribution

MultivariateNormal(mean, cov[, domain])

Multivariate normal distribution

MainModel(loc[, cov, pdf_type])

Main statistical model, modelled as Poisson distribution which has a variable lambda.

ConstraintModel(pdf_descriptions)

Constraint term modelled as a Gaussian distribution.