spey.base.hypotest_base.HypothesisTestingBase#

class spey.base.hypotest_base.HypothesisTestingBase(ntoys: int = 1000)[source]#

Abstract base class that provides the full hypothesis-testing API for spey.

Any class that inherits HypothesisTestingBase and implements the four abstract properties and four abstract methods listed below gains the complete set of hypothesis-testing utilities shown in the table.

Abstract interface (must be implemented by subclasses)

Member	Description
`is_alive`	`True` if the signal hypothesis is non-trivially zero.
`is_asymptotic_calculator_available`	`True` if the asymptotic calculator can be used.
`is_toy_calculator_available`	`True` if the toy calculator can be used.
`is_chi_square_calculator_available`	`True` if the \(\chi^2\) calculator can be used.
`likelihood()`	\(-\log\mathcal{L}\) or \(\mathcal{L}\) at fixed \(\mu\).
`maximize_likelihood()`	Global minimisation of \(-\log\mathcal{L}\) (free fit).
`asimov_likelihood()`	\(-\log\mathcal{L}\) on Asimov data at fixed \(\mu\).
`maximize_asimov_likelihood()`	Global minimisation on Asimov data (free fit).

Concrete capabilities (provided automatically)

Method	Description
`chi2()`	Profile likelihood ratio \(\chi^2\).
`exclusion_confidence_level()`	\(CL_s\) at a fixed \(\mu\) (asymptotic, toy, or \(\chi^2\)).
`significance()`	Discovery significance \(\sqrt{q_0}\).
`poi_upper_limit()`	One-sided 95% (or other) CL upper limit on \(\mu\).
`chi2_test()`	One- or two-sided \(\chi^2\) interval on \(\mu\).
`sigma_mu()`	Standard deviation of \(\hat\mu\) from Hessian or Asimov approximation.

Usage examples

All of the concrete methods below are available on StatisticalModel, which inherits this class:

import spey

pdf = spey.get_backend("default.poisson")
model = pdf(
    signal_yields=[5.0, 3.0],
    background_yields=[50.0, 30.0],
    data=[55, 31],
    analysis="example",
    xsection=0.05,
)

# Exclusion confidence level (CLs) at mu = 1
cls_obs = model.exclusion_confidence_level(poi_test=1.0)

# Expected CLs (5 values: -2s, -1s, central, +1s, +2s)
cls_exp = model.exclusion_confidence_level(
    poi_test=1.0, expected=spey.ExpectationType.apriori
)

# 95% CL upper limit on mu
mu_ul = model.poi_upper_limit(confidence_level=0.95)

# Discovery significance
sqrt_q0A, sqrt_q0, pvals, exp_pvals = model.significance()

# Two-sided chi^2 interval at 68% CL
mu_lo, mu_hi = model.chi2_test(confidence_level=0.68, limit_type="two-sided")

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

__init__(ntoys: int = 1000)[source]#

Methods

`__init__`([ntoys])
`asimov_likelihood`([poi_test, expected, ...])	Compute the (negative) log-likelihood on Asimov data at a fixed \(\mu\).
`chi2`([poi_test, poi_test_denominator, ...])	Compute the profile likelihood ratio \(\chi^2\) test statistic.
`chi2_test`([expected, confidence_level, ...])	Determine parameter value(s) that constrain the \(\chi^2\) distribution at a specified confidence level via 1D profiling.
`exclusion_confidence_level`([poi_test, ...])	Compute the exclusion confidence level \(CL_s\) at a given \(\mu\).
`fixed_poi_sampler`(poi_test[, size, ...])	Sample data from the statistical model with fixed parameter of interest.
`likelihood`([poi_test, expected, return_nll, ...])	Compute the (negative) log-likelihood at a fixed parameter of interest.
`maximize_asimov_likelihood`([return_nll, ...])	Find the global maximum of the likelihood on Asimov data (free fit).
`maximize_likelihood`([return_nll, expected, ...])	Find the global maximum of the likelihood (free fit).
`poi_upper_limit`([expected, ...])	Compute the upper limit for the parameter of interest (POI), denoted as \(\mu\).
`pull`([poi_test, expected, allow_negative_signal])	Pull: measures how many standard deviations the observation is away from the expectation.
`sigma_mu`(poi_test[, expected, test_statistics])	Estimate the standard deviation of \(\hat\mu\) at a fixed \(\mu\).
`significance`([expected])	Compute the discovery significance of a positive signal.

Attributes

`ntoys`	Number of toy pseudo-experiments used by the toy-based calculator.
`is_alive`	Whether the signal hypothesis has at least one non-zero bin yield.
`is_asymptotic_calculator_available`	Whether the asymptotic calculator is available for this model.
`is_chi_square_calculator_available`	Whether the \(\chi^2\) calculator is available for this model.
`is_toy_calculator_available`	Whether the toy (pseudo-experiment) calculator is available for this model.

spey.base.hypotest_base.HypothesisTestingBase

Contents

spey.base.hypotest_base.HypothesisTestingBase#