pyhf.infer.test_statistics.q0

pyhf.infer.test_statistics.q0(mu, data, pdf, init_pars, par_bounds, fixed_params, return_fitted_pars=False)[source]

The test statistic, \(q_{0}\), for discovery of a positive signal as defined in Equation (12) in [1007.1727], for \(\mu=0\).

\begin{equation} q_{0} = \left\{\begin{array}{ll} -2\ln\lambda\left(0\right), &\hat{\mu} \ge 0,\\ 0, & \hat{\mu} < 0, \end{array}\right. \end{equation}

Example

>>> import pyhf
>>> pyhf.set_backend("numpy")
>>> model = pyhf.simplemodels.uncorrelated_background(
...     signal=[12.0, 11.0], bkg=[50.0, 52.0], bkg_uncertainty=[3.0, 7.0]
... )
>>> observations = [60, 65]
>>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
>>> test_mu = 0.0
>>> init_pars = model.config.suggested_init()
>>> par_bounds = model.config.suggested_bounds()
>>> fixed_params = model.config.suggested_fixed()
>>> pyhf.infer.test_statistics.q0(test_mu, data, model, init_pars, par_bounds, fixed_params)
array(2.98339447)
>>> pyhf.infer.test_statistics.q0(
...     test_mu, data, model, init_pars, par_bounds, fixed_params, return_fitted_pars=True
... )
(array(2.98339447), (array([0.        , 1.03050845, 1.12128752]), array([0.95260667, 0.99635345, 1.02140172])))

Parameters:

mu (Number or Tensor) – The signal strength parameter (must be set to zero)
data (Tensor) – The data to be considered
pdf (Model) – The HistFactory statistical model used in the likelihood ratio calculation
init_pars (list of float) – The starting values of the model parameters for minimization.
par_bounds (list of list/tuple) – The extrema of values the model parameters are allowed to reach in the fit. The shape should be (n, 2) for n model parameters.
fixed_params (tuple or list of bool) – The flag to set a parameter constant to its starting value during minimization.
return_fitted_pars (bool) – Return the best-fit parameter tensors the fixed-POI and unconstrained fits have converged on (i.e. \(\mu, \hat{\hat{\theta}}\) and \(\hat{\mu}, \hat{\theta}\))

Returns:

The calculated test statistic, \(q_{0}\)
The parameter tensors corresponding to the constrained best fit, \(\mu, \hat{\hat{\theta}}\), and the unconstrained best fit, \(\hat{\mu}, \hat{\theta}\). Only returned if return_fitted_pars is True.

Return type:

Tuple of a Float and a Tuple of Tensors