hepstats.hypotests.toyutils module#

Module defining the classes to perform and store the results of toy experiments.

Acronyms used in the code:

nll = negative log-likehood, which is the value of the loss attribute of a calculator;

class hepstats.hypotests.toyutils.ToyResult(poigen, poieval)[source]#

Bases: object

Class to store the results of toys generated for a given value of a POI. The best fit value of the POI, the NLL evaluate at the best fit, and the NLL evaluated at several values of the POI are stored. The results can serialized using the to_dict method.

Parameters:

poigen (POI) – POI used to generate the toys.
poieval (POIarray) – POI values to evaluate the loss function.

Raises:

TypeError – if poigen is not a POI instance.
TypeError – if poieval is not a POIarray instance.

property poigen#: Returns the POI used to generate the toys.

property bestfit#: Returns the best fitted values of the POI for each toys.

property poieval#: Returns the scanned POIarray.

property nll_bestfit#: Returns the NLL evaluated at the best fitted values of the POI for each toys.

property nlls#: Returns the NLL evaluated at the poigeval values of the POI for each toys.

property ntoys#: Returns the number of toys.

add_entries(bestfit, nll_bestfit, nlls)[source]#

Add new result entries.

Parameters:

bestfit (ndarray) – best fitted values of the POI
nll_bestfit (ndarray) – NLL evaluated at the best fitted values of the POI
nlls (dict[POI, ndarray]) – NLL evaluated at the best fitted values of the POI

to_dict()[source]#

Returns dictionary of the toy results.

Return type:: dict

Keys:: poi: name of the parameter of interest genvalues: fixed vale of the poi used to generate the toys evalvalues: values to evaluate the NLL bestfit: array of best fitted values of the poi for each toy nlls: dictionary of NLL values for each value in evalvalues and best fit

exception hepstats.hypotests.toyutils.FitFailuresWarning[source]#

Bases: UserWarning

add_note()#: Exception.add_note(note) – add a note to the exception

args#

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class hepstats.hypotests.toyutils.ToysManager(input, minimizer, sampler=<function base_sampler>, sample=<function base_sample>)[source]#

Bases: ToysObject

Class handling the toy generation and fit, results are stored in ToyResult instances stored themselves in a dictionary.

Parameters:

input – loss or fit result
minimizer – minimizer to use to find the minimum of the loss function
sampler (Callable) – function used to create sampler with models, number of events and floating parameters in the sample. Default is hepstats.utils.fit.sampling.base_sampler().
sample (Callable) – function used to get samples from the sampler. Default is hepstats.utils.fit.sampling.base_sample().

get_toyresult(poigen, poieval)[source]#

Getter function.

Parameters:

poigen (POI) – POI used to generate the toys
poieval (POIarray) – POI values to evaluate the loss function

Return type:

ToyResult

add_toyresult(toy)[source]#

Add ToyResult to the manager.

Parameters:: toy (ToyResult) – the toy result to add

ntoys(poigen, poieval)[source]#

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

Parameters:

poigen (POI) – POI used to generate the toys
poieval (POIarray) – POI values to evaluate the loss function

Return type:

int

generate_and_fit_toys(ntoys, poigen, poieval)[source]#

Generate and fit toys for at a given POI (poigen). The toys are then fitted, and the likelihood is profiled at the values of poigen and poieval.

Parameters:

ntoys (int) – number of toys to generate
poigen (POI) – POI used to generate the toys
poieval (POIarray) – POI values to evaluate the loss function

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

values()[source]#: Returns values of ToysManager instance that are ToyResult instances.

toyresults_to_dict()[source]#

Returns a list of all the toy results converted into dictionaries.

Return type:: list[dict]

to_yaml(filename)[source]#

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

Parameters:: filename (str) – the yaml file name.

toysresults_from_yaml(filename)[source]#

Extract toy results from a yaml file.

Parameters:: filename (str) – the yaml file name.
Return type:: list[ToyResult]

classmethod from_yaml(filename, input, minimizer, sampler=<function base_sampler>, sample=<function base_sample>)[source]#

Read the toys from a yaml file.

Parameters:

filename (str) – the yaml file name.
input – loss or fit result
minimizer – minimizer to use to find the minimum of the loss function
sampler (Callable) – function used to create sampler with models, number of events and floating parameters in the sample. Default is hepstats.utils.fit.sampling.base_sampler().
sample (Callable) – function used to get samples from the sampler. Default is hepstats.utils.fit.sampling.base_sample().

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(name)#

Returns the parameter in loss function with given input name.

Parameters:: name (str) – name of the parameter to return

property loss#: Returns the loss / likelihood function.

lossbuilder(model, data, weights=None, oldloss=None)#

Method to build a new loss function.

Parameters:

model (*) – The model or models to evaluate the data on
data (*) – Data to use
weights (*) – the data weights
oldloss (*) – Previous loss that has data, models, type

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.

property parameters#: Returns the list of free parameters in loss / likelihood function.

sample(sampler, ntoys, poi, constraints=None)#

Generator function of samples from the sampler for a given value of a parameter of interest. Returns a dictionnary of samples constraints in any.

Parameters:

sampler (list) – generator of samples
ntoys (int) – number of samples to generate
poi (POI) – in the sampler
constraints (list, optional) – list of constraints to sample

Example with zfit:

>>> mean = zfit.Parameter("mean")
>>> sampler = calc.sampler()
>>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))

Returns:: dictionnary of sampled values of the constraints at each iteration

sampler()#

Create sampler with models.

>>> sampler = calc.sampler()

set_params_to_bestfit()#: Set the values of the parameters in the models to the best fit values

toys_loss(parameter_name)#

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

Parameters:: parameter_name (str) – name floating parameter in the sampler
Returns:: Loss function

Example with zfit:

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