echidna.limit package

Submodules

echidna.limit.limit module

class echidna.limit.limit.Limit(signal, fitter, shrink=True, per_bin=False)

Bases: object

Class to handle main limit setting.

Parameters:

• signal (echidna.core.spectra.Spectra) – signal spectrum you wish to obtain a limit for.
• fitter (echidna.limit.fit.Fit) – The fitter used to set a a limit with.
• shrink (bool, optional) – If set to True, shrink() method is called on the signal spectrum before limit setting, shrinking to ROI.
• per_bin (bool, optional) – If set to True, the values of the test statistic over spectral dimensions (per bin) will be stored.

Variables:

• _signal (echidna.core.spectra.Spectra) – signal spectrum you wish to obtain a limit for.
• _fitter (echidna.limit.fit.Fit) – The fitter used to set a a limit with.
• _stats (numpy.ndarray) – Data container for test statistic values.
• _per_bin (bool) – If set to True, the values of the test statistic over spectral dimensions (per bin) will be stored.

get_array_limit(array, limit=2.71)

Get the limit from an array containing statisics

Parameters:

• array (numpy.array) – The array you want to set a limit for.
• limit (float, optional) – The value of the test statisic which corresponds to the limit you want to set. The default is 2.71 which corresponds to 90% CL when using a chi-squared test statistic.

Raises:

• CompatibilityError – If the length of the array is not equal to the number of signal scalings.
• LimitError – If all values in the array are below limit.

Returns:

The signal scaling at the limit you are setting.

Return type:

float

get_limit(limit=2.71, stat_zero=None, store_summary=True)

Get the limit using the signal spectrum.

Parameters:

• limit (float, optional) – The value of the test statisic which corresponds to the limit you want to set. The default is 2.71 which corresponds to 90% CL when using a chi-squared test statistic.
• stat_zero (float or numpy.ndarray, optional) – Enables calculation of e.g. delta chi-squared. Include values of test statistic for zero signal contribution, so these can be subtracted from the values of the test statistic, with signal.
• store_summary (bool, optional) – If True (default) then a hdf5 file is produced containing best fit values for systematics, total delta chi-squared and penalty chi_squared of each systematic as a function of signal scaling. The prior and sigma values used are also stored. A log file is also produced for the values of best fits and penalty chi_squared of each systematic, total chi_squared, number of degrees of freedom and signal scaling at the requested limit.

Raises:

• TypeError – If stat_zero is not a numpy array, when per_bin is enabled.
• LimitError – If all values in the array are below limit.

Returns:

The signal scaling at the limit you are setting.

Return type:

float

get_statistics()

Get the test statistics for all signal scalings.

Returns:numpy.array: Of test statisics for all signal scalings.

sum_entries(array)

Sums entries of an array which contains arrays as entries.

Parameters:array (numpy.array) – The array you want to sum the elements of. Returns:numpy.array: The input array with its entries summed.

echidna.limit.summary module

class echidna.limit.summary.ReducedSummary(name, num_scales, spectra_config, fit_config)

Bases: echidna.limit.summary.Summary

This class provides similar functionality to the Summary class, but is slightly reduced by the fact that test-statistic values for the spectral dimensions (per-bin) are not stored.

Warning

This class assumes that any test statistic values set in the 1-D stats array, already have the correct penalty term contributions added.

Parameters:

• name (string) – Name of the summary object.
• num_scales (int) – Number of signal scales used in the limit setting.
• spectra_config (echidna.core.spectra.SpectraConfig) – Config for the signal spectrum.
• fit_config (echidna.core.spectra.GlobalFitConfig) – Fit config used during limit setting.

Variables:

• _name (string) – Name of the summary object.
• _num_scales (int) – Number of signal scales used in the limit setting.
• _spectra_config (echidna.core.spectra.SpectraConfig) – Config for the signal spectrum.
• _fit_config (echidna.core.spectra.GlobalFitConfig) – Fit config used during limit setting.
• _best_fits (numpy.ndarray) – The best fit values of the fit parameter for each corresponding signal scale.
• _penalty_terms (numpy.ndarray) – The penalty term values of the fit parameter for each corresponding signal scale.
• _scales (numpy.ndarray) – The signal scales used in the limit setting.
• _stats (numpy.ndarray) – The total test statistic values for each corresponding signal scale.
• _priors (float) – The prior values of each fit parameter
• _sigma (float) – The systematic uncertainty value of the fit parameter
• _limit (float) – Signal determined to be the limit
• _limit_idx (int) – Position in _scales array corresponding to limit.

get_stat(idx)

Gets the total test statistic from array at idx

Warning

Assumes penalty term contributions are already included.

Parameters:idx (int) – Index in the array. Returns:The total stat at idx. Return type:float

get_stats()

Gets the total test statistics array.

Warning

Assumes penalty term contributions are already included.

Returns:numpy.array: The total test statistics at the corresponding signal scales.

nd_project_stat(idx, *parameters)

* NOT VALID IN THIS CLASS * Projects the raw test statistic values at the given index onto the axes specified by the spectral parameters.

This allows you to see the values of the test statistic per-bin in a given dimension.

Warning

No penalty term contributions are included here.

Parameters:

• idx (int) – The index of the array.
• parameters (string) – Names of a valid spectal parameters onto which to project the test statistic values.

Raises:

AttributeError – If used from this class

nd_project_stats(*parameters)

* NOT VALID IN THIS CLASS * Projects the raw test statistic values (at each signal scale) onto the axes specified by the spectral parameters.

This allows you to see the values of the test statistic per-bin in a given dimension.

Warning

No penalty term contributions are included here.

Parameters:parameters (string) – Names of a valid spectal parameters onto which to project the test statistic values. Raises:AttributeError – If used from this class

set_stat(stat, idx)

Sets the test statistic values in array at idx

Parameters:

• stat (float) – Value of the test statistic.
• idx (int) – Index in the array.

Raises:

TypeError – If stat is not a float.

class echidna.limit.summary.Summary(name, num_scales, spectra_config, fit_config)

Bases: object

This class contains the summary data for a given fit parameter when a

limit has been set with a signal spectrum. It stores arrays of signal scales used in the limit setting and the corresponding best fits and penalty term values for the given fit parameter as well as the prior and sigma values of the fit parameter used. The total test statistic values are also stored as an array.

Parameters:

• name (string) – Name of the summary object.
• num_scales (int) – Number of signal scales used in the limit setting.
• spectra_config (echidna.core.spectra.SpectraConfig) – Config for the signal spectrum.
• fit_config (echidna.core.spectra.GlobalFitConfig) – Fit config used during limit setting.

Variables:

• _name (string) – Name of the summary object.
• _num_scales (int) – Number of signal scales used in the limit setting.
• _spectra_config (echidna.core.spectra.SpectraConfig) – Config for the signal spectrum.
• _fit_config (echidna.core.spectra.GlobalFitConfig) – Fit config used during limit setting.
• _best_fits (numpy.ndarray) – The best fit values of the fit parameter for each corresponding signal scale.
• _penalty_terms (numpy.ndarray) – The penalty term values of the fit parameter for each corresponding signal scale.
• _scales (numpy.ndarray) – The signal scales used in the limit setting.
• _stats (numpy.ndarray) – The total test statistic values for each corresponding signal scale.
• _priors (float) – The prior values of each fit parameter
• _sigma (float) – The systematic uncertainty value of the fit parameter
• _limit (float) – Signal determined to be the limit
• _limit_idx (int) – Position in _scales array corresponding to limit.

get_best_fit(idx, parameter=None)

Gets the best_fit from array at idx

If a parameter name is specified, only the best-fit value of this parameter, at the given index, will be returned. Otherwise, the best-fit value for each fit parameter, at the given index, is returned.

Parameters:

• idx (int) – Index in the array.
• parameter (string, optional) – Name of a valid fit parameter for which to get the best-fit value

Returns:

(float or numpy.ndarray): returns:

float: The best fit value of the fit parameter at idx in

the array.

numpy.ndarray: If a parameter value is supplied,

the best-fit values for each fit parameter are returned.

Raises:

IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_best_fits(parameter=None)

Gets the best_fits array.

If a parameter name is specified, the array returned will contain only the best-fit value of this parameter, for each signal scale. Otherwise, the best-fit value for each fit parameter, at each signal scale, is returned.

Parameters:parameter (string, optional) – Name of a valid fit parameter for which to get best-fit values Returns:numpy.ndarray: The best fit(s) at each signal scaling for the fit parameter(s). Raises:IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_fit_config()

Gets the fit config of the summary object

Returns:echidna.core.spectra.GlobalFitConfig: The fit config of the summary object.

get_limit()

Gets the limit scaling determined.

Returns:Signal scaling corresponding to the limit. Return type:float

get_limit_idx()

Gets the position in scales corresponding to the determined limit.

Returns:Position in _scales corresponding to the limit. Return type:int

get_name()

Gets the name of the summary object

Returns:Name of the summary object Return type:string

get_num_scales()

Gets the number of scales in the summary object

Returns:Number of scales Return type:int

get_penalty_term(idx, parameter=None)

Gets the penalty_term from array at idx

If a parameter name is specified, only the penalty term value of this parameter, at the given index, will be returned. Otherwise, the penalty term value for each fit parameter, at the given index, is returned.

Parameters:

• idx (int) – Index in the array.
• parameter (string, optional) – Name of a valid fit parameter for which to get the penalty term value

Returns:

(float or numpy.ndarray: returns:

float: The penalty term value of the fit parameter at idx

in the array.

numpy.ndarray: If a parameter value is supplied,

the penalty term values for each fit parameter are returned.

Raises:

IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_penalty_terms(parameter=None)

Gets the penalty_terms array

If a parameter name is specified, the array returned will contain only the penalty term value of this parameter, for each signal scale. Otherwise, the penalty term value for each fit parameter, at each signal scale, is returned.

Parameters:parameter (string, optional) – Name of a valid fit parameter for which to get the penalty term values Returns:numpy.array: The values of the penalty terms of the fit parameter(s) at each signal scale. Raises:IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_prior(parameter)

Get the prior for the given parameter.

Parameters:parameter (string, optional) – Name of a valid fit parameter for which to get the penalty term value Returns:The prior for the given parameter Return type:float Raises:IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_priors()

Get the priors array.

Returns:numpy.ndarray: The priors

get_raw_stat(idx)

Gets the raw test statistic(s) from array at idx.

Warning

This has no penalty term contributions added.

Parameters:idx (int) – Index in the array. Returns:(float or numpy.ndarray): The raw test statistic(s) at idx.

get_raw_stats()

Gets the raw test statistics array.

Warning

This has no penalty term contributions added.

Returns:numpy.array: The raw test statistics at the corresponding signal scales.

get_scale(idx)

Gets the signal scale from array at idx

Parameters:idx (int) – Index in the array. Returns:The signal scale at idx in the array. Return type:float

get_scales()

Gets the signal scales array

Returns:numpy.array: The signal scales used in the limit setting.

get_sigma(parameter)

Get the sigma for the given parameter.

Parameters:parameter (string, optional) – Name of a valid fit parameter for which to get the penalty term value Returns:The systematic uncertainty for the given parameter Return type:float Raises:IndexError – If the parameter name supplied does not match any of those stored in the fit config.

get_sigmas()

Get the sigmas array.

Returns:numpy.ndarray: The systematic uncertainty for each fit parameter.

get_spectra_config()

Gets the spectra config of the summary object

Returns:echidna.core.spectra.SpectraConfig: The spectra config of the summary object.

get_stat(idx)

Gets the total test statistic from array at idx

Warning

Penalty term contributions are added here.

Parameters:idx (int) – Index in the array. Returns:The total stat at idx. Return type:float

get_stats()

Gets the total test statistics array.

Warning

Penalty term contributions are added here.

Returns:numpy.array: The total test statistics at the corresponding signal scales.

nd_project_stat(idx, *parameters)

Projects the raw test statistic values at the given index onto the axes specified by the spectral parameters.

This allows you to see the values of the test statistic per-bin in a given dimension.

Warning

No penalty term contributions are included here.

Parameters:

• idx (int) – The index of the array.
• parameters (string) – Names of a valid spectal parameters onto which to project the test statistic values.

Returns:

numpy.ndarray: Projection of the _stat array, at idx, onto the given spectral parameter axes.

nd_project_stats(*parameters)

Projects the raw test statistic values (at each signal scale) onto the axes specified by the spectral parameters.

This allows you to see the values of the test statistic per-bin in a given dimension.

Warning

No penalty term contributions are included here.

Parameters:parameters (string) – Names of a valid spectal parameters onto which to project the test statistic values. Returns:numpy.ndarray: Projection of the _stat array onto the given spectral parameter axes.

set_best_fit(best_fit, idx, parameter)

Sets the best fit value of the fit parameter in array at idx

Parameters:

• best_fit (float) – Best fit value of a fit parameter.
• idx (int) – Index in the array.
• parameter (string) – Name of a valid fit parameter for which to set the best-fit value

Raises:

TypeError – If best_fit is not a float.

set_best_fits(best_fits)

Sets the array containing best fit values of the fit parameter.

Parameters:

best_fits (numpy.ndarray) – The best fits array.

Raises:

• TypeError – If best_fits is not an numpy.ndarray
• ValueError – If the best_fits array does not have the required shape.

set_limit(limit)

Sets the limit scaling determined.

Parameters:limit (float) – Signal scaling corresponding to the limit.

set_limit_idx(limit_idx)

Sets the position in scales corresponding to the determined limit.

Parameters:limit_idx (int) – Position in _scales corresponding to the limit.

set_name(name)

Sets the name of the summary object

Parameters:name (string) – Name of the summary object Raises:TypeError – If name is not a string.

set_penalty_term(penalty_term, idx, parameter)

Sets the penalty term value of the fit parameter in array at idx

Parameters:

• penalty_term (float) – Best fit value of a fit parameter.
• idx (int) – Index in the array.
• parameter (string) – Name of a valid fit parameter for which to set the penalty term value

Raises:

TypeError – If penalty_term is not a float.

set_penalty_terms(penalty_terms)

Sets the array containing penalty term values.

Parameters:

penalty_terms (numpy.ndarray) – The array of penalty term values

Raises:

• TypeError – If penalty_terms is not an numpy.ndarray
• ValueError – If the penalty_terms array does not have the required shape.

set_prior(prior, parameter)

Set the prior value of fit parameter to store.

Parameters:

• prior (float) – Prior values for given fit parameter
• parameter (string) – Name of a valid fit parameter for which to set the prior value

Raises:

TypeError – If prior is not a float.

set_priors(priors)

Set the priors array.

Parameters:

priors (numpy.ndarray) – Array of prior values to set.

Raises:

• TypeError – If priors is not a numpy array.
• ValueError – If the priors array does not have the required shape.

set_scale(scale, idx)

Sets the signal scale in array at idx

Parameters:

• scale (float) – The signal scale.
• idx (int) – Index in the array.

Raises:

TypeError – If scale is not a float.

set_scales(scales)

Sets the signal scales array

Parameters:

scales (numpy.ndarray) – The signal scales array.

Raises:

• TypeError – If scales is not a numpy.ndarray.
• ValueError – If length of scales array is not equal to the number of signal scales.

set_sigma(sigma, parameter)

Set the systematic uncertainty value of the fit parameter to store.

Parameters:sigma (float) – The systematic uncertainty value. Raises:TypeError – If sigma is not a float.

set_sigmas(sigmas)

Set the sigmas array.

Parameters:

sigmas (numpy.ndarray) – Array of sigma values to set.

Raises:

• TypeError – If sigmas is not a numpy array.
• ValueError – If the sigmas array does not have the required shape.

set_stat(stat, idx)

Sets the test statistic values in array at idx

Parameters:

• stat (numpy.ndarray) – Values of the test statistic.
• idx (int) – Index in the array.

Raises:

• TypeError – If stat is not a numpy.ndarray.
• ValueError – If the stats array has incorrect shape.

set_stats(stats)

Sets the total test statistics array.

Parameters:

stats (numpy.ndarray) – The total test statistics array.

Raises:

• TypeError – If stats is not a numpy.ndarray.
• ValueError – If the stats array has incorrect shape.

Module contents