hepstats.hypotests.core.upperlimit module#

class hepstats.hypotests.core.upperlimit.UpperLimit(calculator, poinull, poialt, qtilde=False)[source]#

Bases: BaseTest

Class for upper limit calculation.

Parameters:

calculator (BaseCalculator) – calculator to use for computing the pvalues.
poinull (POI | POIarray) – parameters of interest for the null hypothesis.
poialt (POI) – parameters of interest for the alternative hypothesis.
qtilde (bool) – if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic.

Example with zfit:

>>> import numpy as np
>>> import zfit
>>> from zfit.loss import ExtendedUnbinnedNLL
>>> from zfit.minimize import Minuit
>>>
>>> bounds = (0.1, 3.0)
>>> zfit.Space('x', limits=bounds)
>>>
>>> bkg = np.random.exponential(0.5, 300)
>>> peak = np.random.normal(1.2, 0.1, 10)
>>> data = np.concatenate((bkg, peak))
>>> data = data[(data > bounds[0]) & (data < bounds[1])]
>>> N = data.size
>>> data = zfit.data.Data.from_numpy(obs=obs, array=data)
>>>
>>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
>>> Nsig = zfit.Parameter("Ns", 20., -20., N)
>>> Nbkg = zfit.Parameter("Nbkg", N, 0., N*1.1)
>>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=1.2, sigma=0.1)
>>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
>>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)
>>>
>>> from hepstats.hypotests.calculators import AsymptoticCalculator
>>> from hepstats.hypotests import UpperLimit
>>> from hepstats.hypotests.parameters import POI, POIarray
>>>
>>> calculator = AsymptoticCalculator(loss, Minuit())
>>> poinull = POIarray(Nsig, np.linspace(0.0, 25, 20))
>>> poialt = POI(Nsig, 0)
>>> ul = UpperLimit(calculator, poinull, poialt)
>>> ul.upperlimit(alpha=0.05, CLs=True)
Observed upper limit: Nsig = 15.725784747406346
Expected upper limit: Nsig = 11.927442041887158
Expected upper limit +1 sigma: Nsig = 16.596396280677116
Expected upper limit -1 sigma: Nsig = 8.592750403611896
Expected upper limit +2 sigma: Nsig = 22.24864429383046
Expected upper limit -2 sigma: Nsig = 6.400549971360598

property qtilde: bool#: Returns True if qtilde test statistic is used, else False.

pvalues(CLs=True)[source]#

Returns p-values scanned for the values of the parameters of interest in the null hypothesis.

Parameters:: CLs (int) – if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\).
Return type:: dict[str, ndarray]
Returns:: Dictionary of p-values for CLsb, CLs, expected (+/- sigma bands).

upperlimit(alpha=0.05, CLs=True, printlevel=1)[source]#

Returns the upper limit of the parameter of interest.

Parameters:

alpha (float) – significance level.
CLs (bool) – if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\).
printlevel (int) – if > 0 print the result.

Return type:

dict[str, float]

Returns:

Dictionnary of upper limits for observed, expected (+/- sigma bands).

property calculator#: Returns the calculator.

property poialt#: Returns the POI for the alternative hypothesis.

property poinull#: Returns the POI for the null hypothesis.