pyhf.utils.hypotest

pyhf.utils.hypotest(poi_test, data, pdf, init_pars=None, par_bounds=None, qtilde=False, **kwargs)[source]

Computes \(p\)-values and test statistics for a single value of the parameter of interest

Parameters
  • poi_test (Number or Tensor) – The value of the parameter of interest (POI)

  • data (Number or Tensor) – The root of the calculated test statistic given the Asimov data, \(\sqrt{q_{\mu,A}}\)

  • pdf (pyhf.pdf.Model) – The HistFactory statistical model

  • init_pars (Array or Tensor) – The initial parameter values to be used for minimization

  • par_bounds (Array or Tensor) – The parameter value bounds to be used for minimization

  • qtilde (Bool) – When True perform the calculation using the alternative test statistic, \(\tilde{q}\), as defined in Equation (62) of arXiv:1007.1727

Keyword Arguments
  • return_tail_probs (bool) – Bool for returning \(\textrm{CL}_{s+b}\) and \(\textrm{CL}_{b}\)

  • return_expected (bool) – Bool for returning \(\textrm{CL}_{\textrm{exp}}\)

  • return_expected_set (bool) – Bool for returning the \((-2,-1,0,1,2)\sigma\) \(\textrm{CL}_{\textrm{exp}}\) — the “Brazil band”

  • return_test_statistics (bool) – Bool for returning \(q_{\mu}\) and \(q_{\mu,A}\)

Returns

  • \(\textrm{CL}_{s}\): The \(p\)-value compared to the given threshold \(\alpha\), typically taken to be \(0.05\), defined in arXiv:1007.1727 as

\[\textrm{CL}_{s} = \frac{\textrm{CL}_{s+b}}{\textrm{CL}_{b}} = \frac{p_{s+b}}{1-p_{b}}\]

to protect against excluding signal models in which there is little sensitivity. In the case that \(\textrm{CL}_{s} \leq \alpha\) the given signal model is excluded.

  • \(\left[\textrm{CL}_{s+b}, \textrm{CL}_{b}\right]\): The signal + background \(p\)-value and 1 minus the background only \(p\)-value as defined in Equations (75) and (76) of arXiv:1007.1727

\[\textrm{CL}_{s+b} = p_{s+b} = \int\limits_{q_{\textrm{obs}}}^{\infty} f\left(q\,\middle|s+b\right)\,dq = 1 - \Phi\left(\frac{q_{\textrm{obs}} + 1/\sigma_{s+b}^{2}}{2/\sigma_{s+b}}\right)\]
\[\textrm{CL}_{b} = 1- p_{b} = 1 - \int\limits_{-\infty}^{q_{\textrm{obs}}} f\left(q\,\middle|b\right)\,dq = 1 - \Phi\left(\frac{q_{\textrm{obs}} - 1/\sigma_{b}^{2}}{2/\sigma_{b}}\right)\]

with Equations (73) and (74) for the mean

\[E\left[q\right] = \frac{1 - 2\mu}{\sigma^{2}}\]

and variance

\[V\left[q\right] = \frac{4}{\sigma^{2}}\]

of the test statistic \(q\) under the background only and and signal + background hypotheses. Only returned when return_tail_probs is True.

  • \(\textrm{CL}_{s,\textrm{exp}}\): The expected \(\textrm{CL}_{s}\) value corresponding to the test statistic under the background only hypothesis \(\left(\mu=0\right)\). Only returned when return_expected is True.

  • \(\textrm{CL}_{s,\textrm{exp}}\) band: The set of expected \(\textrm{CL}_{s}\) values corresponding to the median significance of variations of the signal strength from the background only hypothesis \(\left(\mu=0\right)\) at \((-2,-1,0,1,2)\sigma\). That is, the \(p\)-values that satisfy Equation (89) of arXiv:1007.1727

\[\textrm{band}_{N\sigma} = \mu' + \sigma\,\Phi^{-1}\left(1-\alpha\right) \pm N\sigma\]

for \(\mu'=0\) and \(N \in \left\{-2, -1, 0, 1, 2\right\}\). These values define the boundaries of an uncertainty band sometimes referred to as the “Brazil band”. Only returned when return_expected_set is True.

  • \(\left[q_{\mu}, q_{\mu,A}\right]\): The test statistics for the observed and Asimov datasets respectively. Only returned when return_test_statistics is True.

Return type

Tuple of Floats and lists of Floats