spey.backends.default_pdf.DefaultPDFBase#

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

Abstract base class shared by all default PDF backends.

This class handles the common infrastructure:

storing signal, background, and observed yields as autograd-compatible arrays to enable automatic differentiation of the likelihood;
constructing the ModelConfig with the minimum POI, suggested initialisations, and parameter bounds;
computing the lower bound on the POI as

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

which is the most negative signal strength for which no bin has negative expected yield;
providing default implementations of get_objective_function(), get_logpdf_func(), get_hessian_logpdf_func(), get_sampler(), and expected_data() that delegate to the per-subclass main_model and constraint_model properties.

Subclasses must override main_model and constraint_model to supply the appropriate \(\lambda(\mu,\boldsymbol{\theta})\) function and constraint distribution.

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. When a callable is supplied n_signal_parameters must be set to the number of extra parameters the function expects.

Note

When signal_yields is callable the minimum POI is set to \(-\infty\) and modifiers cannot be used simultaneously.
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 | Callable | None) –
Background covariance matrix \(\Sigma\). Diagonal elements are squared absolute uncertainties; off-diagonal elements encode inter-bin correlations. May be None for backends that do not use a covariance matrix (e.g. UncorrelatedBackground), or a callable that returns the matrix given an array of parameters.

Warning

The diagonal entries must be squared absolute uncertainties, not standard deviations. For uncorrelated bins pass a diagonal matrix with \(\Sigma_{ii} = \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 that a callable signal_yields function accepts. These parameters are inserted into the parameter vector after \(\mu\) and before the background nuisance parameters:
```
pars = [μ, sig_par_0, …, sig_par_{n-1}, θ_bkg_1, …, θ_bkg_N, θ_sig_1, …]
```
Has no effect when signal_yields is a plain array.
signal_parameter_bounds (List[Tuple[Optional[float], Optional[float]]] | None) – Optimiser bounds for each of the n_signal_parameters extra signal parameters. Each entry is a (lower, upper) pair; use None for either element to leave that side unbounded. When the argument itself is None every extra signal parameter receives (None, None). Must have exactly n_signal_parameters entries when provided.

Note

All array inputs are immediately cast to autograd.numpy.array() with dtype=float64 so that the full parameter-space gradient and Hessian of the likelihood can be computed via automatic differentiation.

__init__(signal_yields: ndarray | Callable[[ndarray], ndarray], background_yields: ndarray, data: ndarray, covariance_matrix: ndarray | Callable[[ndarray], ndarray] = None, 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, data)
`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.DefaultPDFBase

Contents

spey.backends.default_pdf.DefaultPDFBase#