Submodules

hepstats.modeling module

Module for algorithms and methods used to model distributions.

This module contains in particular:

  • Bayesian Blocks binning algorithm.

Bayesian blocks

Bayesian Block implementation

Dynamic programming algorithm for finding the optimal adaptive-width histogram. Modified from the bayesian blocks python implementation found in astroML [VCIG12].

  • Based on Scargle et al 2012 [SNJC13]

  • Initial Python Implementation [BB_]

  • Initial Examination in HEP context [PBS17]

class hepstats.modeling.bayesian_blocks.Prior(p0=0.05, gamma=None)[source]

Bases: object

Helper class for calculating the prior on the fitness function.

Methods

calc

calc(self, N)[source]
hepstats.modeling.bayesian_blocks.bayesian_blocks(data, weights=None, p0=0.05, gamma=None)[source]

Bayesian Blocks Implementation.

This is a flexible implementation of the Bayesian Blocks algorithm described in Scargle 2012 [1]_. It has been modified to natively accept weighted events, for ease of use in HEP applications.

Args:
  • data (array): Input data values (one dimensional, length N). Repeat values are allowed.

  • weights (array_like, optional): Weights for data (otherwise assume all data points have a weight of 1). Must be same length as data. Defaults to None.

  • p0 (float, optional): False-positive rate, between 0 and 1. A lower number places a stricter penalty against creating more bin edges, thus reducing the potential for false-positive bin edges. In general, the larger the number of bins, the small the p0 should be to prevent the creation of spurious, jagged bins. Defaults to 0.05.

  • gamma (float, optional): If specified, then use this gamma to compute the general prior form, p ~ gamma^N. If gamma is specified, p0 is ignored. Defaults to None.

Returns:
  • edges (ndarray): Array containing the (N+1) bin edges

Examples:

Unweighted data:

>>> d = np.random.normal(size=100)
>>> bins = bayesian_blocks(d, p0=0.01)

Unweighted data with repeats:

>>> d = np.random.normal(size=100)
>>> d[80:] = d[:20]
>>> bins = bayesian_blocks(d, p0=0.01)

Weighted data:

>>> d = np.random.normal(size=100)
>>> w = np.random.uniform(1,2, size=100)
>>> bins = bayesian_blocks(d, w, p0=0.01)

hepstats.hypotests module

Module for hypothesis tests, upper limits and confidence intervals calculations.

Parameters

Module defining the parameter of interest classes, currently includes:

  • POIarray

  • POI

class hepstats.hypotests.parameters.POI(parameter, value)[source]

Bases: hepstats.hypotests.parameters.POIarray

Class for single value parameter of interest:

Args:
  • parameter: the parameter of interest

  • values (float, int): value of the parameter of interest

Example with zfit:
>>> Nsig = zfit.Parameter("Nsig")
>>> poi = POI(Nsig, value=0)
Attributes
ndim

Returns the number of dimension of the POIarray.

shape

Returns the shape of the POIarray.

value

Returns the value of the POI.

values

Returns the values of the POIarray.

Methods

append(self, values)

Append values in the POIarray.

property value

Returns the value of the POI.

class hepstats.hypotests.parameters.POIarray(parameter, values)[source]

Bases: object

Class for parameters of interest with multiple values:

Args:
  • parameter: the parameter of interest

  • values (list(float),`numpy.array`): values of the parameter of interest

Example with zfit:
>>> Nsig = zfit.Parameter("Nsig")
>>> poi = POIarray(Nsig, value=np.linspace(0,10,10))
Attributes
ndim

Returns the number of dimension of the POIarray.

shape

Returns the shape of the POIarray.

values

Returns the values of the POIarray.

Methods

append(self, values)

Append values in the POIarray.

append(self, values)[source]

Append values in the POIarray.

Args:
  • values (list(float),`numpy.array`): values to append

property ndim

Returns the number of dimension of the POIarray.

property shape

Returns the shape of the POIarray.

property values

Returns the values of the POIarray.

hepstats.hypotests.parameters.asarray(POI)[source]

Transforms a POI instance into a POIarray instance.

Calculators

Module defining the base class for the calculators for statistical tests based on the likelyhood ratio.

Any calculator can be a subclass of BaseCalculator. Currently implemented:

  • AsymptoticCalculator: calculator using the asymptotic formulae of the likehood ratio.

Acronyms used in the code:
  • nll = negative log-likehood, the likehood being the loss attribute of a calculator;

  • obs = observed, i.e. measured on provided data.

class hepstats.hypotests.calculators.basecalculator.BaseCalculator(input, minimizer)[source]

Bases: hepstats.hypotests.hypotests_object.HypotestsObject

Base class for calculator.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

Example with zfit:
>>> import zfit
>>> from zfit.core.loss import UnbinnedNLL
>>> from zfit.minimize import Minuit
>>> obs = zfit.Space('x', limits=(0.1, 2.0))
>>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
>>> mean = zfit.Parameter("mu", 1.2)
>>> sigma = zfit.Parameter("sigma", 0.1)
>>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> loss = UnbinnedNLL(model=model, data=data)
>>> calc = BaseCalculator(input=loss, minimizer=Minuit())
Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

check_pois(pois)

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

check_pois_compatibility(poi1, poi2)

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull, poialt, nsigma)

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

expected_pvalue(self, poinull, poialt, nsigma)

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

obs_nll(self, pois)

Compute observed negative log-likelihood values for given parameters of interest.

pvalue(self, poinull, poialt, NoneType] = None)

Computes pvalues for the null and alternative hypothesis.

q(self, nll1, nll2, poi1, poi2[, onesided, …])

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

qobs(self, poinull[, onesided, …])

Computes observed values of the \(\Delta\) log-likelihood test statistic.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

static check_pois(pois)[source]

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

static check_pois_compatibility(poi1, poi2)[source]

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: List[hepstats.hypotests.parameters.POI], nsigma, alpha=0.05, CLs=False, qtilde=False, onesided=True, onesideddiscovery=False)[source]

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

Args:
  • poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

  • poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

  • nsigma (numpy.array): array of values of \(\sigma\) to compute the expected pvalue

  • alpha (float, default=0.05): significance level

  • CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

  • qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

Returns:

numpy.array: array of expected POI values for each :math:`sigma value

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POI(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> nll = calc.expected_poi(poinull, poialt)
expected_pvalue(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: List[hepstats.hypotests.parameters.POI], nsigma, CLs=False, qtilde=False, onesided=True, onesideddiscovery=False) → Dict[int, <built-in function array>][source]

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

Args:
  • poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

  • poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

  • nsigma (numpy.array): array of values of \(\sigma\) to compute the expected pvalue

  • CLs (bool, optional): if True computes pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

  • qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

Returns:

numpy.array: array of expected pvalues for each \(\sigma\) value

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POI(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> nll = calc.expected_pvalue(poinull, poialt)
obs_nll(self, pois) → numpy.ndarray[source]

Compute observed negative log-likelihood values for given parameters of interest.

Args:
  • pois (List[hypotests.POI]): parameters of interest

Returns:

numpy.array: observed nll values

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poi = POI(mean, [1.1, 1.2, 1.0])
>>> nll = calc.obs_nll(poi)
pvalue(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: Union[List[hepstats.hypotests.parameters.POI], NoneType] = None, qtilde=False, onesided=True, onesideddiscovery=False) → Tuple[numpy.ndarray, numpy.ndarray][source]

Computes pvalues for the null and alternative hypothesis.

Args:
  • poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

  • poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

  • qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

Returns:

Tuple(numpy.array, numpy.array): pnull, palt

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POI(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> pvalues = calc.pavalue(poinull, poialt)
q(self, nll1: <built-in function array>, nll2: <built-in function array>, poi1, poi2, onesided=True, onesideddiscovery=False) → numpy.ndarray[source]

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

Args:
  • nll1 (numpy.array): array of nll values #1, evaluated with poi1

  • nll2 (numpy.array): array of nll values #2, evaluated with poi2

  • poi1 ((List[hypotests.POI])): list of POI’s #1

  • poi2 ((List[hypotests.POI])): list of POI’s #2

  • onesided (bool, optional, default=True)

  • onesideddiscovery (bool, optional, default=True)

Returns:

numpy.array: array of \(q\) values

qobs(self, poinull: List[hepstats.hypotests.parameters.POI], onesided=True, onesideddiscovery=False, qtilde=False)[source]

Computes observed values of the \(\Delta\) log-likelihood test statistic.

Args:
  • poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

  • qtilde (bool, optional): if True use the \(\tilde{q}\) test statistics else (default) use the \(q\) test statistic

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

Returns:

numpy.array: observed values of q

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poi = POI(mean, [1.1, 1.2, 1.0])
>>> q = calc.qobs(poi)
class hepstats.hypotests.calculators.basecalculator.BaseToysCalculator(input, minimizer, sampler, sample)[source]

Bases: hepstats.hypotests.calculators.basecalculator.BaseCalculator

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

check_pois(pois)

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

check_pois_compatibility(poi1, poi2)

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull, poialt, nsigma)

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

expected_pvalue(self, poinull, poialt, nsigma)

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

obs_nll(self, pois)

Compute observed negative log-likelihood values for given parameters of interest.

pvalue(self, poinull, poialt, NoneType] = None)

Computes pvalues for the null and alternative hypothesis.

q(self, nll1, nll2, poi1, poi2[, onesided, …])

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

qobs(self, poinull[, onesided, …])

Computes observed values of the \(\Delta\) log-likelihood test statistic.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

class hepstats.hypotests.calculators.basecalculator.ToysCalculator(input, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler>, sample=<function base_sample>)[source]

Bases: hepstats.hypotests.calculators.basecalculator.BaseToysCalculator, hepstats.hypotests.toyutils.ToysManager

Class for calculators using toys.

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

ntoysalt

Returns the number of toys generated for the alternative hypothesis.

ntoysnull

Returns the number of toys generated for the null hypothesis.

Methods

add_toyresult(self, toy)

Add ToyResult to the manager.

check_pois(pois)

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

check_pois_compatibility(poi1, poi2)

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull, poialt, nsigma)

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

expected_pvalue(self, poinull, poialt, nsigma)

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

from_yaml(filename, loss, minimizer[, …])

ToysCalculator constructor with the toys loaded from a yaml file.

generate_and_fit_toys(self, ntoys, poigen, …)

Generate and fit toys for at a given POI (poigen).

get_parameter(self, name)

Returns the parameter in loss function with given input name.

get_toyresult(self, poigen, poieval)

Getter function.

get_toys_alt(self, poigen, poieval[, qtilde])

Return the generated toys for the alternative hypothesis.

get_toys_null(self, poigen, poieval[, qtilde])

Return the generated toys for the null hypothesis.

keys(self)

Returns keys of the ToysManager instance defined as key = (toy.poigen, toy.poieval) for a given ToyResult instance toy.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

ntoys(self, poigen, poieval)

Return the number of toys generated from given value of a POI, and scanned/evaluated for given values_equal of the same POI.

obs_nll(self, pois)

Compute observed negative log-likelihood values for given parameters of interest.

pvalue(self, poinull, poialt, NoneType] = None)

Computes pvalues for the null and alternative hypothesis.

q(self, nll1, nll2, poi1, poi2[, onesided, …])

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

qobs(self, poinull[, onesided, …])

Computes observed values of the \(\Delta\) log-likelihood test statistic.

sample(self, sampler, ntoys[, poi])

Returns the samples generated from the sampler for a given value of a parameter of interest

sampler(self[, floating_params])

Create sampler with models.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

to_yaml(self, filename)

Save the toys into a yaml file under the key toys.

toyresults_to_dict(self)

Returns a list of all the toy results converted into dictionnaries

toys_loss(self, parameter_name)

Construct a loss function constructed with a sampler for a given floating parameter

toysresults_from_yaml(self, filename)

Extract toy results from a yaml file.

values(self)

Returns values of ToysManager instance that are ToyResult instances.

classmethod from_yaml(filename, loss, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler at 0x129062560>, sample=<function base_sample at 0x1290628c0>)[source]

ToysCalculator constructor with the toys loaded from a yaml file.

Args:
  • filename (str)

  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

  • ntoysnull (int, default=100): minimum number of toys to generate for the null hypothesis

  • ntoysalt (int, default=100): minimum number of toys to generate for the alternative hypothesis

  • sampler : function used to create sampler with models, number of events and floating parameters in the sample Default is hepstats.fitutils.sampling.base_sampler.

  • sample : function used to get samples from the sampler. Default is hepstats.fitutils.sampling.base_sample.

Returns

ToysCalculator

get_toys_alt(self, poigen, poieval, qtilde=False)[source]

Return the generated toys for the alternative hypothesis.

Args:
  • poigen (POI): POI used to generate the toys

  • ntoys (int): number of toys to generate

  • poieval (POIarray): POI values to evaluate the loss function

  • qtilde (bool, optional): if True use the :math:` ilde{q}` test statistics else (default) use the \(q\) test statistic

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> calc.get_toys_alt(poialt, poieval=poinull)
get_toys_null(self, poigen, poieval, qtilde=False)[source]

Return the generated toys for the null hypothesis.

Args:
  • poigen (POI): POI used to generate the toys

  • ntoys (int): number of toys to generate

  • poieval (POIarray): POI values to evaluate the loss function

  • qtilde (bool, optional): if True use the :math:` ilde{q}` test statistics else (default) use the \(q\) test statistic

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> for p in poinull:
...     calc.get_toys_alt(p, poieval=poialt)
property ntoysalt

Returns the number of toys generated for the alternative hypothesis.

property ntoysnull

Returns the number of toys generated for the null hypothesis.

Asymptotic

class hepstats.hypotests.calculators.asymptotic_calculator.AsymptoticCalculator(input, minimizer, asimov_bins=100)[source]

Bases: hepstats.hypotests.calculators.basecalculator.BaseCalculator

Class for asymptotic calculators. Can be used only with one parameter of interest.

See G. Cowan, K. Cranmer, E. Gross and O. Vitells: Asymptotic formulae for likelihood- based tests of new physics. Eur. Phys. J., C71:1–19, 2011

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

asimov_dataset(self, poi)

Gets the Asimov dataset for a given alternative hypothesis.

asimov_loss(self, poi)

Constructs a loss function using the Asimov dataset for a given alternative hypothesis.

asimov_nll(self, pois, poialt)

Computes negative log-likelihood values for given parameters of interest using the Asimov dataset generated with a given alternative hypothesis.

check_pois(pois)

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

check_pois_compatibility(poi1, poi2)

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull, poialt, nsigma)

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

expected_pvalue(self, poinull, poialt, nsigma)

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

obs_nll(self, pois)

Compute observed negative log-likelihood values for given parameters of interest.

palt(self, qobs, qalt[, onesided, …])

Computes the pvalue for the alternative hypothesis.

pnull(self, qobs[, qalt, onesided, …])

Computes the pvalue for the null hypothesis.

pvalue(self, poinull, poialt, NoneType] = None)

Computes pvalues for the null and alternative hypothesis.

q(self, nll1, nll2, poi1, poi2[, onesided, …])

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

qalt(self, poinull, poialt, onesided, …)

Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic using the asimov dataset.

qobs(self, poinull[, onesided, …])

Computes observed values of the \(\Delta\) log-likelihood test statistic.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

asimov_dataset(self, poi) → Tuple[numpy.ndarray, numpy.ndarray][source]

Gets the Asimov dataset for a given alternative hypothesis.

Args:
  • poi (POI): parameter of interest of the alternative hypothesis

Returns:

Dataset

Example with zfit:
>>> poialt = POI(mean, 1.2)
>>> dataset = calc.asimov_dataset(poialt)
asimov_loss(self, poi)[source]

Constructs a loss function using the Asimov dataset for a given alternative hypothesis.

Args:
  • poi (POI): parameter of interest of the alternative hypothesis

Returns:

Loss function

Example with zfit:
>>> poialt = POI(mean, 1.2)
>>> loss = calc.asimov_loss(poialt)
asimov_nll(self, pois, poialt) → numpy.ndarray[source]

Computes negative log-likelihood values for given parameters of interest using the Asimov dataset generated with a given alternative hypothesis.

Args:
  • pois (POIarray): parameters of interest

  • poialt (POI): parameter of interest of the alternative hypothesis

Returns:

numpy.array: alternative nll values

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> nll = calc.asimov_nll(poinull, poialt)
static check_pois(pois)[source]

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

palt(self, qobs, qalt, onesided=True, onesideddiscovery=False, qtilde=False) → numpy.ndarray[source]

Computes the pvalue for the alternative hypothesis.

Args:
  • qobs (np.array): observed values of the test-statistic q

  • qalt (np.array): alternative values of the test-statistic q using the Asimov dataset

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

  • qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

Returns:

numpy.array : array of the pvalues for the alternative hypothesis

pnull(self, qobs, qalt=None, onesided=True, onesideddiscovery=False, qtilde=False, nsigma=0) → numpy.ndarray[source]

Computes the pvalue for the null hypothesis.

Args:
  • qobs (numpy.array): observed values of the test-statistic q

  • qalt (numpy.array): alternative values of the test-statistic q using the asimov dataset

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

  • qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  • nsigma (float, optional): significance shift

Returns:

np.array : array of the pvalues for the null hypothesis

qalt(self, poinull, poialt, onesided, onesideddiscovery) → numpy.ndarray[source]

Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic using the asimov dataset.

Args:
  • poinull (POIarray): parameters of interest for the null hypothesis

  • poialt (POIarray): parameters of interest for the alternative hypothesis

  • onesided (bool, optional): if True (default) computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

Returns:

numpy.array: observed values of q

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POI(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, [1.2])
>>> q = calc.qalt([poinull], [poialt])
hepstats.hypotests.calculators.asymptotic_calculator.generate_asimov_hist(model, params, nbins=100)[source]

Generate the Asimov histogram using a model and dictionary of parameters.

Args:
  • model : model used to generate the dataset

  • params (Dict) : values of the parameters of the models

  • nbins (int, optional) : number of bins

Returns:

(numpy.array, numpy.array) : hist, bin_edges

Example with zfit:
>>> obs = zfit.Space('x', limits=(0.1, 2.0))
>>> mean = zfit.Parameter("mu", 1.2)
>>> sigma = zfit.Parameter("sigma", 0.1)
>>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> hist, bin_edges = generate_asimov_hist(model, {"mean": 1.2, "sigma": 0.1})

Frequentist

class hepstats.hypotests.calculators.frequentist_calculator.FrequentistCalculator(input, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler>, sample=<function base_sample>)[source]

Bases: hepstats.hypotests.calculators.basecalculator.ToysCalculator

Frequentist calculator class.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

  • ntoysnull (int, default=100): minimum number of toys to generate for the null hypothesis

  • ntoysalt (int, default=100): minimum number of toys to generate for the alternative hypothesis

  • sampler : function used to create sampler with models, number of events and floating parameters in the sample. Default is hepstats.fitutils.sampling.base_sampler.

  • sample : function used to get samples from the sampler. Default is hepstats.fitutils.sampling.base_sample.

Example with zfit:
>>> import zfit
>>> from zfit.core.loss import UnbinnedNLL
>>> from zfit.minimize import MinuitMinimizer
>>> obs = zfit.Space('x', limits=(0.1, 2.0))
>>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
>>> mean = zfit.Parameter("mu", 1.2)
>>> sigma = zfit.Parameter("sigma", 0.1)
>>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> loss = UnbinnedNLL(model=[model], data=[data], fit_range=[obs])
>>> calc = FrequentistCalculator(input=loss, minimizer=MinuitMinimizer(), ntoysnull=1000, ntoysalt=1000)
Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

ntoysalt

Returns the number of toys generated for the alternative hypothesis.

ntoysnull

Returns the number of toys generated for the null hypothesis.

Methods

add_toyresult(self, toy)

Add ToyResult to the manager.

check_pois(pois)

Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

check_pois_compatibility(poi1, poi2)

Checks compatibility between two lists of hepstats.parameters.POIarray instances.

expected_poi(self, poinull, poialt, nsigma)

Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

expected_pvalue(self, poinull, poialt, nsigma)

Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

from_yaml(filename, loss, minimizer[, …])

ToysCalculator constructor with the toys loaded from a yaml file.

generate_and_fit_toys(self, ntoys, poigen, …)

Generate and fit toys for at a given POI (poigen).

get_parameter(self, name)

Returns the parameter in loss function with given input name.

get_toyresult(self, poigen, poieval)

Getter function.

get_toys_alt(self, poigen, poieval[, qtilde])

Return the generated toys for the alternative hypothesis.

get_toys_null(self, poigen, poieval[, qtilde])

Return the generated toys for the null hypothesis.

keys(self)

Returns keys of the ToysManager instance defined as key = (toy.poigen, toy.poieval) for a given ToyResult instance toy.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

ntoys(self, poigen, poieval)

Return the number of toys generated from given value of a POI, and scanned/evaluated for given values_equal of the same POI.

obs_nll(self, pois)

Compute observed negative log-likelihood values for given parameters of interest.

pvalue(self, poinull, poialt, NoneType] = None)

Computes pvalues for the null and alternative hypothesis.

q(self, nll1, nll2, poi1, poi2[, onesided, …])

Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

qalt(self, poinull, poialt, onesided, …[, …])

Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic.

qnull(self, poinull, poialt, onesided, …)

Computes null hypothesis values of the \(\Delta\) log-likelihood test statistic.

qobs(self, poinull[, onesided, …])

Computes observed values of the \(\Delta\) log-likelihood test statistic.

sample(self, sampler, ntoys[, poi])

Returns the samples generated from the sampler for a given value of a parameter of interest

sampler(self[, floating_params])

Create sampler with models.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

to_yaml(self, filename)

Save the toys into a yaml file under the key toys.

toyresults_to_dict(self)

Returns a list of all the toy results converted into dictionnaries

toys_loss(self, parameter_name)

Construct a loss function constructed with a sampler for a given floating parameter

toysresults_from_yaml(self, filename)

Extract toy results from a yaml file.

values(self)

Returns values of ToysManager instance that are ToyResult instances.

qalt(self, poinull, poialt, onesided, onesideddiscovery, qtilde=False)[source]

Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic.

Args:
  • poinull (POIarray): parameters of interest for the null hypothesis

  • poialt (POIarray): parameters of interest for the alternative hypothesis

  • onesided (bool): if True computes onesided pvalues

  • onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

  • ** qtilde** (bool): if True use the \(\widetilde{q}\) test statistics else use the \(q\) test statistic

Returns:

numpy.array: observed values of q

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> q = calc.qalt(poinull, poialt)
qnull(self, poinull, poialt, onesided, onesideddiscovery, qtilde=False)[source]

Computes null hypothesis values of the \(\Delta\) log-likelihood test statistic.

Args:
  • poinull (POIarray): parameters of interest for the null hypothesis

  • poialt (POIarray): parameters of interest for the alternative hypothesis

  • onesided (bool): if True computes onesided pvalues

  • onesideddiscovery (bool): if True computes onesided pvalues for a discovery test

  • qtilde (bool): if True use the \(\widetilde{q}\) test statistics else use the \(q\) test statistic

Returns:

numpy.array: observed values of q

Example with zfit:
>>> mean = zfit.Parameter("mu", 1.2)
>>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
>>> poialt = POI(mean, 1.2)
>>> q = calc.qnull(poinull, poialt)

Discovery test

class hepstats.hypotests.core.discovery.Discovery(calculator, poinull)[source]

Bases: hepstats.hypotests.core.basetest.BaseTest

Class for discovery test.

Args:
  • calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

  • poinull (POI): parameter of interest for the null hypothesis

Example with zfit:
>>> 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, 25)
>>> 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 Discovery
>>> from hepstats.hypotests.parameters import POI
>>> calculator = AsymptoticCalculator(loss, Minuit())
>>> poinull = POI(Nsig, 0)
>>> discovery_test = Discovery(calculator, poinull)
>>> discovery_test.result()
p_value for the Null hypothesis = 0.0007571045424956679
Significance (in units of sigma) = 3.1719464825102244
Attributes
calculator

Returns the calculator.

poialt

Returns the POI for the alternative hypothesis.

poinull

Returns the POI for the null hypothesis.

Methods

result(self[, printlevel])

Returns the result of the discovery hypothesis test.

result(self, printlevel=1)[source]

Returns the result of the discovery hypothesis test.

Args:
  • printlevel (int, default=1): if > 0 print the result

Returns:

Tuple(float, float): pnull, significance

Upper limit

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

Bases: hepstats.hypotests.core.basetest.BaseTest

Class for upper limit calculation.

Args:
  • calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

  • poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

  • poialt (List[hypotests.POI]): parameters of interest for the alternative hypothesis

  • qtilde (bool, optional): 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
Attributes
calculator

Returns the calculator.

poialt

Returns the POI for the alternative hypothesis.

poinull

Returns the POI for the null hypothesis.

qtilde

Returns True if qtilde test statistic is used, else False.

Methods

pvalues(self[, CLs])

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

upperlimit(self[, alpha, CLs, printlevel])

Returns the upper limit of the parameter of interest.

pvalues(self, CLs=True)[source]

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

Args:
  • CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

Returns:

pvalues (Dict): CLsb, CLs, expected (+/- sigma bands) p-values

property qtilde

Returns True if qtilde test statistic is used, else False.

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

Returns the upper limit of the parameter of interest.

Args:
  • alpha (float, default=0.05): significance level

  • CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

  • printlevel (int, default=1): if > 0 print the result

Returns:

limits (Dict): observed, expected (+/- sigma bands) upper limits

Confidence interval

class hepstats.hypotests.core.confidence_interval.ConfidenceInterval(calculator, poinull, qtilde=False)[source]

Bases: hepstats.hypotests.core.basetest.BaseTest

Class for confidence interval calculation.

Args:
  • calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

  • poinull (POIarray): parameters of interest for the null hypothesis

  • qtilde (bool, optional): 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, 80)
>>> 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)
>>> mean = zfit.Parameter("mean", 1.2, 0.5, 2.0)
>>> sigma = zfit.Parameter("sigma", 0.1, 0.02, 0.2)
>>> 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=mean, sigma=sigma)
>>> 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 ConfidenceInterval
>>> from hepstats.hypotests.parameters import POI, POIarray
>>> calculator = AsymptoticCalculator(loss, Minuit())
>>> poinull = POIarray(mean, np.linspace(1.15, 1.26, 100))
>>> ci = ConfidenceInterval(calculator, poinull)
>>> ci.interval()
Confidence interval on mean:
    1.1810371356602791 < mean < 1.2156701172321935 at 68.0% C.L.
Attributes
calculator

Returns the calculator.

poialt

Returns the POI for the alternative hypothesis.

poinull

Returns the POI for the null hypothesis.

qtilde

Returns True if qtilde test statistic is used, else False.

Methods

interval(self[, alpha, printlevel])

Returns the confidence level on the parameter of interest.

pvalues(self)

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

interval(self, alpha=0.32, printlevel=1)[source]

Returns the confidence level on the parameter of interest.

Args:
  • alpha (float, default=0.32/1 sigma): significance level,

  • printlevel (int, default=1): if > 0 print the result

Returns:

limits (Dict): central, upper and lower bounds on the parameter of interest

pvalues(self)[source]

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

Returns:

pvalues (np.array): CLsb, CLs, expected (+/- sigma bands) p-values

property qtilde

Returns True if qtilde test statistic is used, else False.

Hypotests objects

class hepstats.hypotests.hypotests_object.HypotestsObject(input, minimizer)[source]

Bases: object

Base object in hepstats.hypotests to manipulate a loss function and a minimizer.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

property bestfit

Returns the best fit values of the model parameters.

property constraints

Returns the constraints on the loss / likehood function.

property data

Returns the data.

get_parameter(self, name)[source]

Returns the parameter in loss function with given input name.

Args:

name (str): name of the parameter to return

property loss

Returns the loss / likelihood function.

lossbuilder(self, model, data, weights=None)[source]

Method to build a new loss function.

Args:
  • model (List): The model or models to evaluate the data on

  • data (List): Data to use

  • weights (optional, List): the data weights

Example with zfit:
>>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
>>> mean = zfit.Parameter("mu", 1.2)
>>> sigma = zfit.Parameter("sigma", 0.1)
>>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> loss = calc.lossbuilder(model, data)
Returns:

Loss function

property minimizer

Returns the minimizer.

property model

Returns the model.

set_params_to_bestfit(self)[source]

Set the values of the parameters in the models to the best fit values

class hepstats.hypotests.hypotests_object.ToysObject(input, minimizer, sampler, sample)[source]

Bases: hepstats.hypotests.hypotests_object.HypotestsObject

Base object in hepstats.hypotests to manipulate a loss function, a minimizer and sample a model (within the loss function) to do toy experiments.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

  • sampler : function used to create sampler with models, number of events and floating parameters in the sample.

  • sample : function used to get samples from the sampler.

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

sample(self, sampler, ntoys[, poi])

Returns the samples generated from the sampler for a given value of a parameter of interest

sampler(self[, floating_params])

Create sampler with models.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

toys_loss(self, parameter_name)

Construct a loss function constructed with a sampler for a given floating parameter

sample(self, sampler, ntoys, poi=None)[source]

Returns the samples generated from the sampler for a given value of a parameter of interest

Args:
  • sampler (list): generator of samples

  • ntoys (int): number of samples to generate

  • poi (POI, optional): in the sampler

Example with zfit:
>>> mean = zfit.Parameter("mean")
>>> sampler = calc.sampler(floating_params=[mean])
>>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))
sampler(self, floating_params=None)[source]

Create sampler with models.

Args:
  • floating_params (list): floating parameters in the sampler

Example with zfit:
>>> sampler = calc.sampler(floating_params=[zfit.Parameter("mean")])
toys_loss(self, parameter_name)[source]

Construct a loss function constructed with a sampler for a given floating parameter

Args:
  • parameter_name: name floating parameter in the sampler

Returns:

Loss function

Example with zfit:
>>> loss = calc.toys_loss(zfit.Parameter("mean"))

Toy utilities

class hepstats.hypotests.hypotests_object.HypotestsObject(input, minimizer)[source]

Bases: object

Base object in hepstats.hypotests to manipulate a loss function and a minimizer.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

property bestfit

Returns the best fit values of the model parameters.

property constraints

Returns the constraints on the loss / likehood function.

property data

Returns the data.

get_parameter(self, name)[source]

Returns the parameter in loss function with given input name.

Args:

name (str): name of the parameter to return

property loss

Returns the loss / likelihood function.

lossbuilder(self, model, data, weights=None)[source]

Method to build a new loss function.

Args:
  • model (List): The model or models to evaluate the data on

  • data (List): Data to use

  • weights (optional, List): the data weights

Example with zfit:
>>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
>>> mean = zfit.Parameter("mu", 1.2)
>>> sigma = zfit.Parameter("sigma", 0.1)
>>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> loss = calc.lossbuilder(model, data)
Returns:

Loss function

property minimizer

Returns the minimizer.

property model

Returns the model.

set_params_to_bestfit(self)[source]

Set the values of the parameters in the models to the best fit values

class hepstats.hypotests.hypotests_object.ToysObject(input, minimizer, sampler, sample)[source]

Bases: hepstats.hypotests.hypotests_object.HypotestsObject

Base object in hepstats.hypotests to manipulate a loss function, a minimizer and sample a model (within the loss function) to do toy experiments.

Args:
  • input : loss or fit result

  • minimizer : minimizer to use to find the minimum of the loss function

  • sampler : function used to create sampler with models, number of events and floating parameters in the sample.

  • sample : function used to get samples from the sampler.

Attributes
bestfit

Returns the best fit values of the model parameters.

constraints

Returns the constraints on the loss / likehood function.

data

Returns the data.

loss

Returns the loss / likelihood function.

minimizer

Returns the minimizer.

model

Returns the model.

Methods

get_parameter(self, name)

Returns the parameter in loss function with given input name.

lossbuilder(self, model, data[, weights])

Method to build a new loss function.

sample(self, sampler, ntoys[, poi])

Returns the samples generated from the sampler for a given value of a parameter of interest

sampler(self[, floating_params])

Create sampler with models.

set_params_to_bestfit(self)

Set the values of the parameters in the models to the best fit values

toys_loss(self, parameter_name)

Construct a loss function constructed with a sampler for a given floating parameter

sample(self, sampler, ntoys, poi=None)[source]

Returns the samples generated from the sampler for a given value of a parameter of interest

Args:
  • sampler (list): generator of samples

  • ntoys (int): number of samples to generate

  • poi (POI, optional): in the sampler

Example with zfit:
>>> mean = zfit.Parameter("mean")
>>> sampler = calc.sampler(floating_params=[mean])
>>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))
sampler(self, floating_params=None)[source]

Create sampler with models.

Args:
  • floating_params (list): floating parameters in the sampler

Example with zfit:
>>> sampler = calc.sampler(floating_params=[zfit.Parameter("mean")])
toys_loss(self, parameter_name)[source]

Construct a loss function constructed with a sampler for a given floating parameter

Args:
  • parameter_name: name floating parameter in the sampler

Returns:

Loss function

Example with zfit:
>>> loss = calc.toys_loss(zfit.Parameter("mean"))

hepstats.splot module

Module implementing the sPlot algorithm, see [PLD05].

sWeights

hepstats.splot.sweights.compute_sweights(model, x)[source]

Computes sWeights from probability density functions for different components/species in a fit model (for instance signal and background) fitted on some data x.

i.e. model = Nsig * pdf_signal + Nbkg * pdf_bkg

Args:
  • model: sum of extended pdfs.

  • x (np.array): data on which model is fitted

Returns:
  • dict(`yield, np.array)`: dictionary with yield parameters as keys, and sWeights for correspoind species as values.

Example with zfit:
>>> import numpy as np
>>> import zfit
>>> from zfit.loss import ExtendedUnbinnedNLL
>>> from zfit.minimize import Minuit
>>> bounds = (0.0, 3.0)
>>> nbkg = 10000
>>> nsig = 5000
>>> zfit.Space('x', limits=bounds)
>>> bkg = np.random.exponential(0.5, nbkg)
>>> peak = np.random.normal(1.2, 0.1, nsig)
>>> 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)
>>> mean = zfit.Parameter("mean", 1.2, 0.5, 2.0)
>>> sigma = zfit.Parameter("sigma", 0.1, 0.02, 0.2)
>>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
>>> Nsig = zfit.Parameter("Nsig", nsig, 0., N)
>>> Nbkg = zfit.Parameter("Nbkg", nbkg, 0., N)
>>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
>>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
>>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)
>>> minimizer = Minuit()
>>> minimum = minimizer.minimize(loss)
>>> from hepstats.splot import compute_sweights
>>> sweights = compute_sweights(tot_model, data)
hepstats.splot.sweights.is_sum_of_extended_pdfs(model)[source]