hepstats.hypotests.toyutils module#

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:
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(floating_params=[mean])
>>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))
Returns:

dictionnary of sampled values of the constraints at each iteration

sampler(floating_params=None)#

Create sampler with models.

Parameters:

floating_params – floating parameters in the sampler

Example with zfit:
>>> sampler = calc.sampler(floating_params=[zfit.Parameter("mean")])
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"))