AsymptoticTestStatDistribution

class pyhf.infer.calculators.AsymptoticTestStatDistribution(shift, cutoff=- inf)[source]

Bases: object

The distribution the test statistic in the asymptotic case.

Note: These distributions are in \(-\hat{\mu}/\sigma\) space. In the ROOT implementation the same sigma is assumed for both hypotheses and \(p\)-values etc are computed in that space. This assumption is necessarily valid, but we keep this for compatibility reasons.

In the \(-\hat{\mu}/\sigma\) space, the test statistic (i.e. \(\hat{\mu}/\sigma\)) is normally distributed with unit variance and its mean at the \(-\mu'\), where \(\mu'\) is the true poi value of the hypothesis.

__init__(shift, cutoff=- inf)[source]

Asymptotic test statistic distribution.

Parameters

shift (float) – The displacement of the test statistic distribution.

Returns

The asymptotic distribution of test statistic.

Return type

AsymptoticTestStatDistribution

Methods

cdf(value)[source]

Compute the value of the cumulative distribution function for a given value of the test statistic.

Example

>>> import pyhf
>>> pyhf.set_backend("numpy")
>>> bkg_dist = pyhf.infer.calculators.AsymptoticTestStatDistribution(0.0)
>>> bkg_dist.cdf(0.0)
0.5
Parameters

value (float) – The test statistic value.

Returns

The integrated probability to observe a test statistic less than or equal to the observed value.

Return type

Float

expected_value(nsigma)[source]

Return the expected value of the test statistic.

Example

>>> import pyhf
>>> pyhf.set_backend("numpy")
>>> bkg_dist = pyhf.infer.calculators.AsymptoticTestStatDistribution(0.0)
>>> n_sigma = pyhf.tensorlib.astensor([-2, -1, 0, 1, 2])
>>> bkg_dist.expected_value(n_sigma)
array([-2., -1.,  0.,  1.,  2.])
Parameters

nsigma (int or tensor) – The number of standard deviations.

Returns

The expected value of the test statistic.

Return type

Float

pvalue(value)[source]

The \(p\)-value for a given value of the test statistic corresponding to signal strength \(\mu\) and Asimov strength \(\mu'\) as defined in Equations (59) and (57) of [1007.1727]

\[p_{\mu} = 1-F\left(q_{\mu}\middle|\mu'\right) = 1- \Phi\left(\sqrt{q_{\mu}} - \frac{\left(\mu-\mu'\right)}{\sigma}\right)\]

with Equation (29)

\[\frac{(\mu-\mu')}{\sigma} = \sqrt{\Lambda}= \sqrt{q_{\mu,A}}\]

given the observed test statistics \(q_{\mu}\) and \(q_{\mu,A}\).

Example

>>> import pyhf
>>> pyhf.set_backend("numpy")
>>> bkg_dist = pyhf.infer.calculators.AsymptoticTestStatDistribution(0.0)
>>> bkg_dist.pvalue(0.0)
array(0.5)
Parameters

value (float) – The test statistic value.

Returns

The integrated probability to observe a value at least as large as the observed one.

Return type

Tensor