Statistical Model

Statistical Model#

This module defines StatisticalModel, the central user-facing object in spey. It wraps any backend that inherits BackendBase and provides a unified API for likelihood evaluation, hypothesis testing, upper-limit extraction, and model combination. The module also exposes statistical_model_wrapper(), the decorator that backends are registered with, and the PoiTest type alias used throughout.

statistical_model_wrapper(func)

Decorator that promotes a BackendBase constructor into a StatisticalModel factory.
class spey.StatisticalModel(backend: BackendBase, analysis: str, xsection: float = nan, ntoys: int = 1000)[source]#

Bases: HypothesisTestingBase

Unified interface to any spey statistical model backend.

StatisticalModel is the central user-facing object in spey. It wraps any backend that inherits BackendBase, giving every backend a consistent API for:

  • evaluating the (negative) log-likelihood \(-\log\mathcal{L}(\mu,\hat{\theta}_\mu)\);

  • maximising the likelihood to obtain \(\hat\mu\) and \(\hat{\theta}\);

  • computing p-values, CLs values, and upper limits via asymptotic, toy-based, or \(\chi^2\) calculators;

  • generating Asimov data;

  • combining two models with the @ operator.

Instances are normally obtained through spey.get_backend() rather than constructed directly:

import spey

# Obtain a backend constructor wrapped as StatisticalModel
pdf_wrapper = spey.get_backend("default.poisson")

# Build the statistical model
model = pdf_wrapper(
    signal_yields=[12.0, 15.0],
    background_yields=[50.0, 60.0],
    data=[48, 63],
    analysis="my_analysis",
    xsection=0.05,  # pb
)

Likelihood evaluation

# Negative log-likelihood at mu = 1
nll = model.likelihood(poi_test=1.0)

# Profile likelihood ratio test statistic
nll_free, _ = model.maximize_likelihood()

# Asimov (expected) likelihood
nll_asimov = model.asimov_likelihood(poi_test=1.0)

Hypothesis testing

# Observed CLs value
cls_obs = model.exclusion_confidence_level(poi_test=1.0)

# Expected (apriori) CLs value
cls_exp = model.exclusion_confidence_level(
    poi_test=1.0, expected=spey.ExpectationType.apriori
)

# One-sided 95 % CL upper limit on the signal strength
mu_ul = model.poi_upper_limit(confidence_level=0.95)

# Upper limit on the cross section (requires xsection to be set)
xsec_ul = model.s95obs

Multi-parameter fits

When a backend exposes more than one parameter of interest, poi_test and poi_indices accept either an int index, a str parameter name, or a dict mapping indices / names to values:

# Fix mu_0 = 1.0, mu_1 = 0.5
nll = model.likelihood(poi_test={0: 1.0, 1: 0.5})

# Retrieve fitted values of two named POIs
muhat_dict, nll = model.maximize_likelihood(poi_indices=[0, 1])

Model combination

combined = model_a @ model_b          # uses the @ operator
# or equivalently:
combined = model_a.combine(model_b)
Parameters:

  • backend (BackendBase) – Statistical model backend. Must be an instance of a class that inherits BackendBase.

  • analysis (str) – Unique identifier of the statistical model used for book-keeping purposes.

  • xsection (float, default np.nan) – Signal cross section in units chosen by the user. Only required for excluded_cross_section(), s95obs, and s95exp.

  • ntoys (int, default 1000) – Number of pseudo-experiments (toys) used by the toy-based hypothesis-testing calculator. Ignored when the asymptotic or \(\chi^2\) calculator is used.

Raises:

AssertionError – If backend does not inherit BackendBase.

Returns:

A statistical model object wrapping the given backend with a unified hypothesis- testing interface.

Return type:

StatisticalModel

analysis: str#

Unique identifier as analysis name

asimov_likelihood(poi_test: float | Dict[int | str, float] = 1.0, expected: ExpectationType = observed, return_nll: bool = True, test_statistics: str = 'qtilde', init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, **kwargs) → float[source]#

Compute likelihood of the statistical model generated with the Asimov data.

Parameters:

  • poi_test (PoiTest, default 1.0) – Parameter of interest, \(\mu\). Accepts the same formats as likelihood(): a plain float fixes the primary POI, while a dict of {index_or_name: value} fixes multiple parameters simultaneously.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • return_nll (bool, default True) – If True, returns negative log-likelihood value. if False returns likelihood value.

  • test_statistics (Text, default "qtilde") –

    test statistics.

    • 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).

      Warning

      Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.

    • 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).

    • 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).

    The choice of test_statistics will effect the generation of the Asimov data where the fit is performed via \(\mu=1\) if test_statistics="q0" and \(\mu=0\) for others. Note that this \(\mu\) does not correspond to the poi_test input of this function but it determines how Asimov data is generated.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • kwargs –

    Keyword arguments forwarded to both the Asimov data generation fit (via generate_asimov_data()) and the subsequent likelihood evaluation (via likelihood()). Both calls receive an independent copy of kwargs.

    Consumed by prepare_for_fit:

    • do_grad (bool, default True): Whether to request the gradient of the objective function from the backend. Falls back to False automatically if the backend raises NotImplementedError.

    • constraints (List[Dict], default []): Additional scipy-style constraint dicts to pass to the optimiser. Any constraints defined on the backend itself are always appended.

    Consumed by fit (the core optimisation loop):

    • minimizer (str, default "scipy" or the value of the SPEY_OPTIMISER environment variable): Selects the numerical minimiser. Accepted values are "scipy" and "minuit" (requires iminuit).

    • hessian (Callable[[np.ndarray], np.ndarray], default None): Hessian of the objective function. Passed to scipy as hess; ignored by minuit.

    Scipy-minimiser options (used when minimizer="scipy"):

    • method (str, default "SLSQP"): Scipy optimisation method.

    • maxiter (int, default 10000): Maximum number of iterations.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (bool, default False): If True, print convergence messages.

    • ntrials (int, default 1): Number of re-tries with progressively expanded parameter bounds when the minimiser does not converge.

    Minuit-minimiser options (used when minimizer="minuit"):

    • method (str, default "migrad"): Minuit algorithm ("migrad" or "simplex").

    • maxiter (int, default 10000): Maximum number of function calls.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (int, default 0): Minuit print level (0 = silent).

    • strategy (int, default 0): Minuit strategy (0 = fast, 1 = default, 2 = slow but more accurate).

    • errordef (float, default Minuit.LIKELIHOOD): Value by which Minuit defines a one-sigma interval (0.5 for NLL, 1.0 for \(\chi^2\)).

    Note

    fixed_poi_value is not an accepted kwarg here. The POI used for Asimov data generation is determined by test_statistics (1.0 for "q0", 0.0 otherwise), and poi_test fixes the POI for the likelihood evaluation. Passing fixed_poi_value would cause a TypeError in both inner calls and is therefore intercepted and discarded with a warning.

    Unknown keys are logged as a warning and silently discarded by the minimiser.

Returns:

likelihood computed for asimov data

Return type:

float

property available_calculators: List[str]#

Returns available calculator names.

Possible entries are 'toy', 'asymptotic', and 'chi_square', depending on what the underlying backend supports.

Returns:

Subset of ['toy', 'asymptotic', 'chi_square'] listing the calculators that are available for this model.

Return type:

List[str]

property backend: BackendBase#

The underlying backend instance.

Returns:

The backend object that was supplied at construction time. All likelihood and sampling calls are delegated to this object.

Return type:

BackendBase

property backend_type: str#

Human-readable name of the backend.

Returns the value of the backend’s name attribute when present, and falls back to the class name otherwise.

Returns:

Backend identifier string (e.g. "default.poisson").

Return type:

str

chi2(poi_test: float | Dict[int | str, float] = 1.0, poi_test_denominator: float | Dict[int | str, float] | None = None, expected: ExpectationType = observed, allow_negative_signal: bool = False, init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, mle_kwargs=None, likelihood_kwargs=None) → float#

Compute the profile likelihood ratio \(\chi^2\) test statistic.

When poi_test_denominator=None, evaluates the profile likelihood ratio against the unconditional maximum:

\[\chi^2 = -2\log\left(\frac{\mathcal{L}(\mu,\hat\theta_\mu)}{\mathcal{L}(\hat\mu,\hat\theta)}\right)\]

When poi_test_denominator is set, it replaces the denominator with a second fixed-\(\mu\) likelihood:

\[\chi^2 = -2\log\left(\frac{\mathcal{L}(\mu,\theta_\mu)}{\mathcal{L}(\mu_{\rm denom},\theta_{\mu_{\rm denom}})}\right)\]

where \(\mu_{\rm denom}\) is poi_test_denominator which is typically zero to compare signal model with the background only model.

Parameters:

  • poi_test (PoiTest or list[float], default 1.0) – Parameter of interest, \(\mu\). A plain float (or iterable of floats) fixes the primary POI — when iterable, \(\chi^2\) is computed for each element. Alternatively, a dict of {index_or_name: value} fixes multiple parameters simultaneously (iterating over dicts is not supported).

  • poi_test_denominator (PoiTest, default None) – Parameter of interest for the denominator. Accepts the same formats as poi_test. If None the maximum likelihood is computed instead.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative. Only valid when poi_test_denominator=None.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • mle_kwargs (dict, default None) –

    Keyword arguments forwarded to the denominator evaluation. When poi_test_denominator=None they are passed to maximize_likelihood() (free fit of \(\hat\mu,\hat\theta\)); otherwise they are passed to likelihood() at the fixed \(\mu_{\rm denom}\). If None, an empty dict is used. Accepted keys:

    Consumed by prepare_for_fit:

    • do_grad (bool, default True): Request the gradient of the objective function from the backend. Falls back to False automatically if the backend raises NotImplementedError.

    • constraints (List[Dict], default []): Additional scipy-style constraint dicts appended to any backend-defined constraints.

    • fixed_poi_value (Union[float, Dict[int, float]], default None): Fix one or more POIs during the maximisation while the remaining parameters are profiled freely. Only effective in the maximize_likelihood branch (i.e. when poi_test_denominator=None); ignored (with a warning) by likelihood, which takes the fixed POIs from poi_test_denominator.

    Consumed by fit (the core optimisation loop):

    • minimizer (str, default "scipy" or the value of the SPEY_OPTIMISER environment variable): Selects the numerical minimiser. Accepted values are "scipy" and "minuit" (requires iminuit).

    • hessian (Callable[[np.ndarray], np.ndarray], default None): Hessian of the objective function. Passed to scipy as the hess argument; ignored by minuit.

    Scipy-minimiser options (used when minimizer="scipy"):

    • method (str, default "SLSQP"): Scipy optimisation method (e.g. "SLSQP", "L-BFGS-B", "trust-constr").

    • maxiter (int, default 10000): Maximum number of iterations.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (bool, default False): Print convergence messages if True.

    • ntrials (int, default 1): Number of re-tries with progressively expanded parameter bounds when the minimiser does not converge.

    Minuit-minimiser options (used when minimizer="minuit"):

    • method (str, default "migrad"): Minuit algorithm ("migrad" or "simplex").

    • maxiter (int, default 10000): Maximum number of function calls.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (int, default 0): Minuit print level (0 = silent).

    • strategy (int, default 0): Minuit strategy (0 = fast, 1 = default, 2 = slow but more accurate).

    • errordef (float, default Minuit.LIKELIHOOD): Value by which Minuit defines a one-sigma interval (0.5 for NLL, 1.0 for \(\chi^2\)).

    Unknown keys are logged as a warning and silently discarded by the minimiser.

  • likelihood_kwargs (dict, default None) –

    Keyword arguments forwarded to likelihood() when evaluating the numerator at each requested poi_test value (including every element of an iterable or scan). If None, an empty dict is used. Accepts the same keys as mle_kwargs above, with one caveat:

    • fixed_poi_value is not supported here — the numerator’s fixed POIs are controlled entirely by poi_test. Passing fixed_poi_value is logged as a warning and discarded.

Returns:

value of the \(\chi^2\).

Return type:

float

chi2_test(expected: ExpectationType = observed, confidence_level: float = 0.95, limit_type: Literal['right', 'left', 'two-sided'] = 'two-sided', allow_negative_signal: bool = None, parameter: int | str | None = None, poi_value: float = 1.0, n_scan: int = 3, n_multistart: int = 2, **kwargs) → List[float]#

Determine parameter value(s) that constrain the \(\chi^2\) distribution at a specified confidence level via 1D profiling.

When parameter=None (default), the method profiles the primary POI and finds the POI values where the profile \(\chi^2\) equals the threshold chi2.isf(alpha, df=1).

When parameter is set to a nuisance parameter index or name, the POI is fixed to poi_value (default 1.0) and the method profiles the chosen nuisance parameter instead, locating the nuisance value(s) at the same \(\chi^2\) threshold. This is useful for setting 1D confidence intervals on any model parameter.

Added in version 0.2.0.

Changed in version 0.2.7: The ability to profile any given nuisance parameter has been implemented. The 1D profile is now enumerated by coarse scan plus bracketed root refinement, so non-convex likelihoods with disjoint confidence regions return every crossing in ascending order. A small multi-start is performed before the root search to harden the NLL minimum used as the anchor of the \(\chi^2\) threshold.

Attention

The degrees of freedom are set to one, referring to the single profiled parameter (either the POI or the selected nuisance parameter).

Parameters:

  • expected (ExpectationType) –

    Specifies the type of expectation for the fitting algorithm and p-value computation.

    • observed: Computes p-values using post-fit prescription, assuming experimental data as the truth.

    • apriori: Computes expected p-values using pre-fit prescription, assuming the Standard Model (SM) as the truth.

  • confidence_level (float, default 0.95) – The confidence level for the interval. Must be between 0 and 1. This refers to the total inner area under the bell curve, noted as \(CL\) below.

  • limit_type ('right', 'left' or 'two-sided', default 'two-sided') – Specifies which side of the \(\chi^2\) distribution should be constrained.

  • allow_negative_signal (bool, default None) – Controls whether the POI can be negative during the global unconstrained maximisation. If None, it is set to True for two-sided and left limits, and False for right limits. Ignored when parameter is not None (the global fit is always unconstrained in that case).

  • parameter (int or str, default None) – Index or name of the nuisance parameter to profile. When None (default) the primary POI is profiled (existing behaviour). When set, the POI is fixed to poi_value and the selected nuisance parameter is scanned instead. String values are resolved via parameter_names.

  • poi_value (float, default 1.0) – Fixed value of the primary POI when profiling a nuisance parameter (i.e. when parameter is not None). Has no effect when parameter=None. If poi_value=None, primary POI will also be minimised during optimisation.

  • n_scan (int, default 121) – Number of uniformly-spaced grid points used by the coarse scan that enumerates sign changes of the profile \(\chi^2 - \text{threshold}\) function. Each sign-change interval is then refined to full precision with toms748(). Increasing this value improves detection of narrow features in non-convex profiles at the cost of additional NLL evaluations; values below 3 are clamped to 3.

  • n_multistart (int, default 9) – Number of evenly-spaced evaluations used by the internal multi-start scan that re-anchors the NLL minimum before the root search. A bounded scalar minimisation is then run around the best point found by the scan. Increasing this value reduces the risk of the anchor being trapped in a local minimum at the cost of additional NLL evaluations; values below 2 are clamped to 2.

Keyword Arguments:

  • xtol (float, default 2e-12) – Absolute tolerance passed to toms748(). The root-finder stops when the bracket width falls below this value.

  • rtol (float, default 1e-4) – Relative tolerance passed to toms748(). The root-finder stops when the bracket width is smaller than rtol * |root|.

  • maxiter (int, default 10000) – Maximum number of function evaluations allowed inside toms748().

Returns:

Parameter value(s) at which the profile \(\chi^2\) equals the threshold, in ascending order. For a convex profile this is one value for one-sided limits and two values for two-sided limits (backwards compatible); for a non-convex profile with disjoint confidence regions every crossing is returned, so users that rely on a fixed list length should check len(result) before unpacking.

Return type:

List[float]

Raises:

ValueError – If parameter refers to the POI index, if the parameter name is not found in the model config, if the parameter index is out of range, or if the model has only one parameter (no nuisance parameters to profile).

combine(other, **kwargs)[source]#

Combination routine between two statistical models.

Note

This function’s availability is backend dependent.

Parameters:

  • other (StatisticalModel) – Statistical model to be combined with this model

  • kwargs – backend specific arguments.

Raises:

  • CombinerNotAvailable – If this statistical model does not have a combination routine implementation.

  • AssertionError – If the combination routine in the backend does not return a BackendBase object.

Returns:

Returns a new combined statistical model.

Return type:

StatisticalModel

property config: ModelConfig#

Retreive model configuration

excluded_cross_section(expected: ExpectationType = observed) → float[source]#

Compute excluded cross section value at 95% CL

Parameters:

expected (ExpectationType) –

Sets which values the fitting algorithm should focus and p-values to be computed.

  • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

  • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

  • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

Raises:

UnknownCrossSection – If the cross-section is nan.

Returns:

Returns the upper limit at 95% CL on cross section value where the unit is defined by the user.

Return type:

float

exclusion_confidence_level(poi_test: float | Dict[int | str, float] = 1.0, expected: ExpectationType = observed, allow_negative_signal: bool = False, calculator: Literal['asymptotic', 'toy', 'chi_square'] = 'asymptotic', **kwargs) → List[float]#

Compute the exclusion confidence level \(CL_s\) at a given \(\mu\).

\(CL_s\) is defined as

\[CL_s = \frac{p_{s+b}}{1 - p_b}\]

and is returned as \(1 - p\text{-value}\). The number of returned values depends on the expected mode:

  • observed → one value (fitted to observed data).

  • aposteriori / apriori → five values representing \(-2\sigma,\,-1\sigma,\,\text{central},\,+1\sigma,\,+2\sigma\) fluctuations from the background.

Parameters:

  • poi_test (PoiTest, default 1.0) – Parameter of interest \(\mu\) at which to evaluate \(CL_s\).

  • expected (ExpectationType) –

    Selects the expectation mode.

    • observed: Post-fit, returns one value (default).

    • aposteriori: Post-fit nuisance treatment, returns five expected values.

    • apriori: Pre-fit / SM hypothesis, returns five expected values.

    Setting expected="all" returns both the observed and the five expected values simultaneously.

  • allow_negative_signal (bool, default False) – When True, \(\hat\mu\) is unconstrained, switching the test statistic from \(\tilde{q}_\mu\) to \(q_\mu\).

  • calculator ('asymptotic', 'toy' or 'chi_square', default 'asymptotic') –

    • "asymptotic": Asymptotic formulae from [arXiv:1007.1727].

    • "toy": Pseudo-experiment-based p-values (requires is_toy_calculator_available).

    • "chi_square": \(\chi^2\)-based p-values; uses \(\chi^2 = -2\log[\mathcal{L}(\mu,\hat\theta_\mu)/\mathcal{L}(0,\hat\theta_0)]\).

  • kwargs –

    Additional keyword arguments forwarded to the optimiser, including:

    • init_pars (List[float], default None): Initial parameter values for the optimiser.

    • par_bounds (List[Tuple[float, float]], default None): Parameter bounds for the optimiser.

Raises:

CalculatorNotAvailable – If the requested calculator is not available.

Returns:

\(CL_s\) value(s). One value for observed; five values ordered \((-2\sigma,\,-1\sigma,\,\text{central},\,+1\sigma,\,+2\sigma)\) for expected modes.

Return type:

List[float]

fixed_poi_sampler(poi_test: float | Dict[int | str, float], size: int | None = None, expected: ExpectationType = observed, init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, **kwargs) → ndarray | Callable[[int], ndarray][source]#

Sample data from the statistical model with fixed parameter of interest.

Parameters:

  • poi_test (PoiTest) – Parameter of interest, \(\mu\). A plain float fixes the primary POI; a dict of {index_or_name: value} fixes multiple parameters at once.

  • size (int, default None) – sample size. If None a callable function will be returned which takes sample size as input.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • kwargs – keyword arguments for the optimiser.

Raises:

MethodNotAvailable – If backend does not have sampler implementation.

Returns:

Sampled data with shape of (size, number of bins) or callable function to sample from directly.

Return type:

Union[np.ndarray, Callable[[int], np.ndarray]]

generate_asimov_data(expected: ExpectationType = observed, test_statistic: str = 'qtilde', init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, **kwargs) → List[float][source]#

Generate Asimov data for the statistical model. This function generates a set of parameters (nuisance and poi i.e. \(\theta\) and \(\mu\)) with respect to test_statistic input which determines the value of \(\mu\) i.e. if test_statistic="q0" \(\mu=1\) and 0 for anything else. The objective function is used to optimize the statistical model to find the fit parameters for fixed poi optimisation. Then fit parameters are used to retrieve the expected data through expected_data() function.

Parameters:

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • test_statistic (Text, default "qtilde") –

    test statistics.

    • 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).

      Warning

      Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.

    • 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).

    • 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • kwargs – keyword arguments for the optimiser.

Returns:

Asimov data

Return type:

List[float]

property is_alive: bool#

Returns True if at least one bin has non-zero signal yield.

property is_asymptotic_calculator_available: bool#

Whether the asymptotic calculator can be used with this backend.

The asymptotic calculator requires either:

  • a working expected_data() implementation, or

  • both asimov_negative_loglikelihood() and minimize_asimov_negative_loglikelihood() to be overridden by the backend.

Returns:

True if the asymptotic calculator is available.

Return type:

bool

property is_chi_square_calculator_available: bool#

Whether the \(\chi^2\) calculator can be used with this backend.

The \(\chi^2\) calculator only requires the negative log-likelihood, which every backend must implement, so this property always returns True.

Returns:

Always True.

Return type:

bool

property is_toy_calculator_available: bool#

Whether the toy (pseudo-experiment) calculator can be used with this backend.

Requires the backend to override get_sampler().

Returns:

True if the toy calculator is available.

Return type:

bool

likelihood(poi_test: float | Dict[int | str, float] = 1.0, expected: ExpectationType = observed, return_nll: bool = True, data: List[float] | ndarray | None = None, return_parameters: bool = False, init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, **kwargs) → float | Tuple[float, ndarray][source]#

Compute the likelihood of the statistical model at a fixed parameter of interest.

Parameters:

  • poi_test (PoiTest, default 1.0) – Parameter of interest, \(\mu\). Can be a single float (fixes the primary POI identified by poi_index) or a dict mapping POI indices (int) or names (str) to their fixed values. String keys are resolved via parameter_names. When a float is given, behaviour is identical to previous versions.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • return_nll (bool, default True) – If True, returns negative log-likelihood value. if False returns likelihood value.

  • data (Union[List[float], np.ndarray], default None) – input data that to fit. If None data will be set according to expected input.

  • return_parameters (bool, default False) – Return fit parameters.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • kwargs –

    Keyword arguments forwarded through prepare_for_fit to the optimiser. The following keys are recognised:

    Consumed by prepare_for_fit:

    • do_grad (bool, default True): Whether to request the gradient of the objective function from the backend. Falls back to False automatically if the backend raises NotImplementedError.

    • constraints (List[Dict], default []): Additional scipy-style constraint dicts to pass to the optimiser. Any constraints defined on the backend itself are always appended.

    Consumed by fit (the core optimisation loop):

    • minimizer (str, default "scipy" or the value of the SPEY_OPTIMISER environment variable): Selects the numerical minimiser. Accepted values are "scipy" and "minuit" (requires iminuit).

    • hessian (Callable[[np.ndarray], np.ndarray], default None): Hessian of the objective function with respect to the variational parameters. Passed to scipy as the hess argument; ignored by the minuit minimiser.

    Scipy-minimiser options (used when minimizer="scipy"):

    • method (str, default "SLSQP"): Scipy optimisation method (e.g. "SLSQP", "L-BFGS-B", "trust-constr").

    • maxiter (int, default 10000): Maximum number of iterations.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (bool, default False): If True, print convergence messages.

    • ntrials (int, default 1): Number of re-tries with progressively expanded parameter bounds when the minimiser does not converge.

    Minuit-minimiser options (used when minimizer="minuit"):

    • method (str, default "migrad"): Minuit algorithm. Accepted values are "migrad" and "simplex".

    • maxiter (int, default 10000): Maximum number of function calls.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (int, default 0): Minuit print level (0 = silent).

    • strategy (int, default 0): Minuit strategy (0 = fast, 1 = default, 2 = slow but more accurate).

    • errordef (float, default Minuit.LIKELIHOOD): Value by which Minuit defines a one-sigma interval (0.5 for NLL, 1.0 for \(\chi^2\)).

    Unknown keys are logged as a warning and silently discarded by the minimiser.

Returns:

Likelihood of the statistical model at a fixed signal strength.

Return type:

float

maximize_asimov_likelihood(return_nll: bool = True, expected: ExpectationType = observed, test_statistics: str = 'qtilde', init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, poi_indices: List[int | str] | None = None, **kwargs) → Tuple[float | Dict[int | str, float], float][source]#

Find the maximum of the likelihood which computed with respect to Asimov data.

Parameters:

  • return_nll (bool, default True) – If True, returns negative log-likelihood value. if False returns likelihood value.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • test_statistics (Text, default "qtilde") –

    test statistic.

    • 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).

      Warning

      Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.

    • 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).

    • 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • poi_indices (List[Union[int, str]], default None) – If None, returns the primary POI value as a single float. If a list of parameter indices (int) or names (str) is provided, returns a dict mapping each requested key to its fitted value. Passed directly to maximize_likelihood().

  • kwargs –

    Keyword arguments forwarded to both the Asimov data generation fit (via generate_asimov_data()) and the subsequent maximisation (via maximize_likelihood()). Both calls receive an independent copy of kwargs.

    Consumed by prepare_for_fit:

    • do_grad (bool, default True): Whether to request the gradient of the objective function from the backend. Falls back to False automatically if the backend raises NotImplementedError.

    • constraints (List[Dict], default []): Additional scipy-style constraint dicts to pass to the optimiser. Any constraints defined on the backend itself are always appended.

    Consumed by fit (the core optimisation loop):

    • minimizer (str, default "scipy" or the value of the SPEY_OPTIMISER environment variable): Selects the numerical minimiser. Accepted values are "scipy" and "minuit" (requires iminuit).

    • hessian (Callable[[np.ndarray], np.ndarray], default None): Hessian of the objective function. Passed to scipy as hess; ignored by minuit.

    • fixed_poi_value (Union[float, Dict[int, float]], default None): Fix one or more POIs during the maximisation step while allowing the remaining parameters to be profiled freely. A plain float fixes the primary POI; a dict of {index: value} fixes multiple POIs simultaneously. This kwarg is intercepted and discarded (with a warning) in the Asimov data generation step, where the POI is already determined by test_statistics.

    Scipy-minimiser options (used when minimizer="scipy"):

    • method (str, default "SLSQP"): Scipy optimisation method.

    • maxiter (int, default 10000): Maximum number of iterations.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (bool, default False): If True, print convergence messages.

    • ntrials (int, default 1): Number of re-tries with progressively expanded parameter bounds when the minimiser does not converge.

    Minuit-minimiser options (used when minimizer="minuit"):

    • method (str, default "migrad"): Minuit algorithm ("migrad" or "simplex").

    • maxiter (int, default 10000): Maximum number of function calls.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (int, default 0): Minuit print level (0 = silent).

    • strategy (int, default 0): Minuit strategy (0 = fast, 1 = default, 2 = slow but more accurate).

    • errordef (float, default Minuit.LIKELIHOOD): Value by which Minuit defines a one-sigma interval (0.5 for NLL, 1.0 for \(\chi^2\)).

    Unknown keys are logged as a warning and silently discarded by the minimiser.

Returns:

When poi_indices=None: \(\hat\mu\) (float) and the (negative) log-likelihood. When poi_indices is provided: a dict of {index_or_name: fitted_value} and the (negative) log-likelihood.

Return type:

Tuple[Union[float, Dict[Union[int, str], float]], float]

maximize_likelihood(return_nll: bool | None = True, expected: ExpectationType | None = observed, allow_negative_signal: bool | None = True, data: List[float] | ndarray | None = None, init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, poi_indices: List[int | str] | None = None, **kwargs) → Tuple[float | Dict[int | str, float], float][source]#

Find the maximum of the likelihood.

Parameters:

  • return_nll (bool, default True) – If True, returns negative log-likelihood value. if False returns likelihood value.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.

  • data (Union[List[float], np.ndarray], default None) – input data that to fit. If None data will be set according to expected input.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • poi_indices (List[Union[int, str]], default None) – If None, returns a single float for the primary POI (identified by poi_index). If a list of parameter indices (int) or names (str) is provided, returns a dict mapping each requested key to its fitted value. String keys are resolved via parameter_names.

  • kwargs –

    Keyword arguments forwarded through prepare_for_fit to the optimiser. Accepts the same keys as likelihood():

    Consumed by prepare_for_fit:

    • do_grad (bool, default True): Whether to request the gradient of the objective function from the backend. Falls back to False automatically if the backend raises NotImplementedError.

    • constraints (List[Dict], default []): Additional scipy-style constraint dicts to pass to the optimiser. Any constraints defined on the backend itself are always appended.

    • fixed_poi_value (Union[float, Dict[int, float]], default None): Fix one or more parameters of interest during the optimisation while allowing the remaining parameters (nuisance and other POIs) to be minimised freely. A plain float fixes the primary POI (identified by poi_index); a dict of {index: value} fixes multiple POIs simultaneously. This is particularly useful in multi-POI fits where, for example, one signal strength is held fixed while others are profiled out.

    Consumed by fit (the core optimisation loop):

    • minimizer (str, default "scipy" or the value of the SPEY_OPTIMISER environment variable): Selects the numerical minimiser. Accepted values are "scipy" and "minuit" (requires iminuit).

    • hessian (Callable[[np.ndarray], np.ndarray], default None): Hessian of the objective function with respect to the variational parameters. Passed to scipy as the hess argument; ignored by the minuit minimiser.

    Scipy-minimiser options (used when minimizer="scipy"):

    • method (str, default "SLSQP"): Scipy optimisation method.

    • maxiter (int, default 10000): Maximum number of iterations.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (bool, default False): If True, print convergence messages.

    • ntrials (int, default 1): Number of re-tries with progressively expanded parameter bounds when the minimiser does not converge.

    Minuit-minimiser options (used when minimizer="minuit"):

    • method (str, default "migrad"): Minuit algorithm ("migrad" or "simplex").

    • maxiter (int, default 10000): Maximum number of function calls.

    • tol (float, default 1e-6): Convergence tolerance.

    • disp (int, default 0): Minuit print level.

    • strategy (int, default 0): Minuit strategy (0 = fast, 1 = default, 2 = slow but more accurate).

    • errordef (float, default Minuit.LIKELIHOOD): Value by which Minuit defines a one-sigma interval.

    Unknown keys are logged as a warning and silently discarded by the minimiser.

Returns:

When poi_indices=None: \(\hat\mu\) (float) and the (negative) log-likelihood. When poi_indices is provided: a dict of {index_or_name: fitted_value} and the (negative) log-likelihood.

Return type:

Tuple[Union[float, Dict[Union[int, str], float]], float]

ntoys#

Number of toy pseudo-experiments used by the toy-based calculator.

poi_upper_limit(expected: ExpectationType = observed, confidence_level: float = 0.95, low_init: float = 1.0, hig_init: float = 1.0, expected_pvalue: Literal['nominal', '1sigma', '2sigma'] = 'nominal', maxiter: int = 10000, optimiser_arguments: Dict[str, Any] | None = None) → float | List[float]#

Compute the upper limit for the parameter of interest (POI), denoted as \(\mu\).

Parameters:

  • expected (ExpectationType, default observed) –

    Specifies the type of expectation for the fitting algorithm and p-value computation.

    • observed: Computes p-values using post-fit prescription, assuming experimental data as the truth (default).

    • aposteriori: Computes expected p-values using post-fit prescription, assuming experimental data as the truth.

    • apriori: Computes expected p-values using pre-fit prescription, assuming the Standard Model (SM) as the truth.

  • confidence_level (float, default 0.95) – Confidence level for the upper limit, representing \(1 - CL_s\). Must be between 0 and 1. Default is 0.95.

  • low_init (Optional[float], default 1.0) –

    Initial lower limit for the search algorithm. If None, it is determined by \(\hat\mu + 1.5\sigma_{\hat\mu}\). Default is 1.0.

    Note

    \(\sigma_{\hat\mu}\) is determined via sigma_mu() function.

  • hig_init (Optional[float], default 1.0) –

    Initial upper limit for the search algorithm. If None, it is determined by \(\hat\mu + 2.5\sigma_{\hat\mu}\). Default is 1.0.

    Note

    \(\sigma_{\hat\mu}\) is determined via sigma_mu() function.

  • expected_pvalue (Literal["nominal", "1sigma", "2sigma"], default "nominal") –

    In case of aposteriori and apriori expectation, specifies the type of expected p-value for upper limit calculation.

    • "nominal": Computes the upper limit for the central p-value. Returns a single value.

    • "1sigma": Computes the upper limit for the central p-value and \(1\sigma\) fluctuation from background. Returns 3 values.

    • "2sigma": Computes the upper limit for the central p-value and \(1\sigma\) and \(2\sigma\) fluctuation from background. Returns 5 values.

    Note

    For expected=spey.ExpectationType.observed, expected_pvalue argument will be overwritten to "nominal".

  • allow_negative_signal (bool, default True) – Allows for negative signal values, changing the computation of the test statistic. Default is False.

  • maxiter (int, default 10000) – Maximum number of iterations for the optimiser. Default is 10000.

  • optimiser_arguments (Dict, default None) – Additional arguments for the optimiser used to compute the likelihood and its maximum. Default is None.

Returns:

  • A single value representing the upper limit for the nominal case.

  • A list of values representing the upper limits for the central value and statistical deviations (for “1sigma” and “2sigma” cases). The order is: \(-2\sigma\), \(-1\sigma\), central value, \(1\sigma\), \(2\sigma\).

Return type:

Union[float, List[float]]

Raises:

AssertionError – If the confidence level is not between 0 and 1.

prepare_for_fit(data: List[float] | ndarray | None = None, expected: ExpectationType = observed, allow_negative_signal: bool | None = True, **kwargs) → Dict[source]#

Prepare backend for the optimiser.

Parameters:

  • data (Union[List[float], np.ndarray], default None) – input data that to fit

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.

Returns:

Dictionary of necessary toolset for the fit. objective function, "func", use gradient boolean, "do_grad" and function to compute negative log-likelihood with given fit parameters, "nll".

Return type:

Dict

pull(poi_test: float | Dict[int | str, float] = 1.0, expected: ExpectationType = observed, allow_negative_signal: bool = True, **kwargs) → float#

Pull: measures how many standard deviations the observation is away from the expectation.

\[\text{pull}(\mu) = \operatorname{sign}(\hat{\mu}-\mu) \sqrt{-2\log\frac{L(\mu,\hat{\hat{\theta}}(\mu))}{L(\hat{\mu},\hat{\theta})}}\]

the square of the pull is the likelihood-ratio test statistic.

Parameters:

  • poi_test (PoiTest or list[float], default 1.0) – Parameter of interest, \(\mu\). A plain float (or iterable of floats) fixes the primary POI — when iterable, \(\chi^2\) is computed for each element. Alternatively, a dict of {index_or_name: value} fixes multiple parameters simultaneously (iterating over dicts is not supported).

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative. Only valid when poi_test_denominator=None.

  • kwargs – keyword arguments for the optimiser.

Returns:

value of pull.

Return type:

float

property s95exp: float#

Expected excluded cross section at 95% CL (pre-fit / a-priori expectation).

Shorthand for excluded_cross_section(ExpectationType.apriori). The result represents the cross-section value that would be excluded at the 95% confidence level if no signal were present (SM hypothesis), expressed in the same units as xsection.

Raises:

UnknownCrossSection – If xsection has not been set (i.e. is nan).

Returns:

Expected 95% CL excluded cross section value in user-defined units.

Return type:

float

property s95obs: float#

Observed excluded cross section at 95% CL (post-fit / observed expectation).

Shorthand for excluded_cross_section(ExpectationType.observed). The result represents the cross-section value excluded at the 95% confidence level using the actual observed data, expressed in the same units as xsection.

Raises:

UnknownCrossSection – If xsection has not been set (i.e. is nan).

Returns:

Observed 95% CL excluded cross section value in user-defined units.

Return type:

float

sigma_mu(poi_test: float | Dict[int | str, float], expected: ExpectationType = observed, test_statistics: Literal['qtilde', 'q', 'q0'] = 'qtilde', **kwargs) → float#

Estimate the standard deviation of \(\hat\mu\) at a fixed \(\mu\).

Attempts the Hessian-based estimate first (via sigma_mu_from_hessian()) if that method exists on the subclass. When the Hessian is not available, falls back to the Asimov approximation from eq. (31) of [arXiv:1007.1727]:

\[\sigma_A = \frac{|\mu - \mu^\prime|}{\sqrt{q_{\mu,A}}}, \qquad q_{\mu,A} = -2\ln\lambda_A(\mu)\]

where \(\mu^\prime\) is the best-fit value on the Asimov dataset.

Parameters:

  • poi_test (PoiTest) – Parameter of interest value \(\mu\) at which to evaluate \(\sigma_\mu\).

  • expected (ExpectationType) –

    Selects which dataset to condition on.

    • observed: Use observed data (post-fit, default).

    • aposteriori: Use observed data with post-fit nuisance treatment.

    • apriori: Use background-only prediction (pre-fit / SM hypothesis).

  • test_statistics (str, default "qtilde") –

    Test statistic used for the Asimov approximation (ignored when the Hessian path is taken).

    • 'qtilde': \(\tilde{q}_\mu\), eq. (62) of [arXiv:1007.1727].

      Warning

      This assumes \(\hat\mu \geq 0\). spey’s public API enforces this automatically.

    • 'q': \(q_\mu\), eq. (54) of [arXiv:1007.1727].

    • 'q0': Discovery statistic \(q_0\), eq. (47) of [arXiv:1007.1727].

  • kwargs –

    Additional keyword arguments forwarded to the optimiser, including:

    • init_pars (List[float], default None): Initial parameter values for the optimiser.

    • par_bounds (List[Tuple[float, float]], default None): Parameter bounds for the optimiser.

Returns:

Estimated standard deviation \(\sigma_\mu\) of the parameter of interest at the given \(\mu\).

Return type:

float

sigma_mu_from_hessian(poi_test: float | Dict[int | str, float], expected: ExpectationType = observed, init_pars: List[float] | None = None, par_bounds: List[Tuple[float, float]] | None = None, **kwargs) → float[source]#

Compute variance of \(\mu\) from inverse Hessian. See eq. (27-28) in [arXiv:1007.1727].

Parameters:

  • poi_test (PoiTest) – Parameter of interest, \(\mu\). A plain float fixes the primary POI; a dict of {index_or_name: value} fixes multiple parameters simultaneously.

  • expected (ExpectationType) –

    Sets which values the fitting algorithm should focus and p-values to be computed.

    • observed: Computes the p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth (default).

    • aposteriori: Computes the expected p-values with via post-fit prescription which means that the experimental data will be assumed to be the truth.

    • apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.

  • init_pars (List[float], default None) – initial parameters for the optimiser

  • par_bounds (List[Tuple[float, float]], default None) – parameter bounds for the optimiser.

  • kwargs – keyword arguments for the optimiser.

Raises:

MethodNotAvailable – If backend does not have Hessian implementation.

Returns:

variance on parameter of interest.

Return type:

float

significance(expected: ExpectationType = observed, **kwargs) → Tuple[float, float, List[float], List[float]]#

Compute the discovery significance of a positive signal.

Uses the discovery test statistic \(q_0\) (eq. 47 of [arXiv:1007.1727]) to quantify the evidence for a signal above the background-only hypothesis. The Asimov significance \(\sqrt{q_{0,A}}\) gives the median expected sensitivity, while \(\sqrt{q_0}\) is computed from the observed data. See sec. 5.1 of [arXiv:1007.1727] for details.

Note

aposteriori and observed both perform a post-fit computation and therefore return identical results. The only meaningful distinction is between post-fit (observed) and pre-fit (apriori) computations.

Parameters:

  • expected (ExpectationType) –

    Selects which dataset to condition on.

    • observed: Post-fit (default).

    • apriori: Pre-fit / SM hypothesis.

  • kwargs –

    Additional keyword arguments forwarded to the optimiser, including:

    • init_pars (List[float], default None): Initial parameter values for the optimiser.

    • par_bounds (List[Tuple[float, float]], default None): Parameter bounds for the optimiser.

Returns:

A 4-tuple (sqrt_q0A, sqrt_q0, pvalues, expected_pvalues) where:

  • sqrt_q0A — Asimov discovery significance \(\sqrt{q_{0,A}}\).

  • sqrt_q0 — Observed discovery significance \(\sqrt{q_0}\).

  • pvalues — Observed p-value(s) for the \(q_0\) test.

  • expected_pvalues — Expected p-value(s) at \(-2\sigma,\,-1\sigma,\,\text{central},\,+1\sigma,\,+2\sigma\).

Return type:

Tuple[float, float, List[float], List[float]]

xsection: float#

Value of the cross section, unit is defined by the user.