echidna.fit package

Submodules

echidna.fit.fit module

class echidna.fit.fit.Fit(roi, test_statistic, fit_config=None, data=None, fixed_backgrounds=None, floating_backgrounds=None, signal=None, shrink=True, per_bin=False, minimiser=None, fit_results=None, use_pre_made=False, pre_made_base_dir=None, single_bin=False)

Bases: object

Class to handle fitting.

Warning

The Fit initialisation will try to set atrributes using the values provided. If a value is not provided echidna will attempt to set the default. If this is not possible a warning will be raised and you will have to set this attribute manually before calling fit().

Parameters:

• roi (dictionary) – Region Of Interest you want to fit in. The format of roi is e.g. {“energy”: (2.4, 2.6), “radial3”: (0., 0.2)}
• test_statistic (echidna.limit.test_statistic.TestStatistic) – An appropriate class for calculating test statistics.
• fit_config (FitConfig, optional) – Config class for fit - usually loaded from file.
• data (echidna.core.spectra.Spectra) – Data spectrum you want to fit.
• fixed_background (dict, optional) – Dictionary containing all fixed backgrounds, with echidna.core.spectra.Spectra as keys and priors (float) as values.
• floating_backgrounds – one echidna.core.spectra.Spectra for each background to float.
• shrink (bool, optional) – If set to True (default), shrink() method is called on all spectra shrinking them to the ROI.
• minimiser (echidna.limit.minimiser.Minimiser, optional) – Object to handle the minimisation.
• fit_results (FitResults, optional) – Specify a separate Fit Results class.
• use_pre_made (bool, optional) – Flag whether to load a pre-made spectrum for each systematic value, or apply convolutions on the fly.
• pre_made_dir (string, optional) – Directory in which pre-made convolved spectra are stored.
• single_bin (bool, optional) – Flag for a single bin fit (e.g. simple counting experiment).
• per_bin (bool, optional) – Flag to monitor values of test statistic, per bin included in the fit (ROI)

Variables:

• _logger (loggging.Logger) – Logger for Fit class.
• _roi (dictionary) – Region Of Interest you want to fit in. The format of roi is e.g. {“energy”: (2.4, 2.6), “radial3”: (0., 0.2)}
• _test_statistic (echidna.limit.test_statistic.TestStatistic) – An appropriate class for calculating test statistics.
• _fit_config (FitConfig) – Config class for fit - usually loaded from file.
• _data – Data spectrum you want to fit.
• _floating_backgrounds – one echidna.core.spectra.Spectra for each background to float.
• _fit_results (FitResults) – Specify a separate Fit Results class.
• _checked (bool) – If True then the fit class is ready to be used.
• _use_pre_made (bool) – Flag whether to load a pre-made spectrum for each systematic value, or apply convolutions on the fly.
• _pre_made_dir (string) – Directory in which pre-made convolved spectra are stored.

_funct(*args)

Callable to pass to minimiser.

Parameters:args (list) – List of fit parameter values to test in the current iteration. Returns:containing:

numpy.ndrray: Values of the test statistic given

the current values of the fit parameters.

float: Total penalty term to be applied to the test

statistic.

Return type:tuple Raises:ValueError – If _floating_backgrounds is None. This method requires at least one floating background.

Note

This method should not be called directly, it is intended to be passed to an appropriate minimiser and called from within the minimisation algorithm.

Note

This method should not be used if there are no floating backgrounds.

append_fixed_background(spectra_dict, shrink=True)

Appends the fixed background with more spectra.

Parameters:

• spectra_dict (dict) – Dictionary containing spectra as keys and prior counts as values.
• shrink (bool, optional) – If set to True (default), shrink() method is called on the spectra shrinking it to the ROI.

check_all_spectra()

Ensures that all spectra can be used for fitting.

Raises:

• CompatibilityError – If the data spectra exists and its roi pars have not been set.
• CompatibilityError – If the data spectrum has not been set.
• CompatibilityError – If neither fixed background nor at least one floating background, has been set.
• CompatibilityError – If the fixed background spectra exists and its roi pars have not been set.
• CompatibilityError – If the signal spectra exists and its roi pars have not been set.
• CompatibilityError – If the floating backgrounds spectra exists and their roi pars have not been set.
• CompatibilityError – If the floating backgrounds spectra exists and their roi pars have not been set.
• CompatibilityError – If the floating backgrounds spectra exists and length of their roi pars is different to the number of floating backgrounds.

check_fit_config(spectra)

Checks that a spectra has a fit config.

Parameters:spectra (echidna.core.spectra.Spectra) – Spectra you want to check. Raises:CompatibilityError – If spectra has no fit config

check_fitter()

Checks that the Fit class is ready to be used for fitting.

Raises:

• IndexError – If fit config contains no parameters
• ValueError – If number of floating backgrounds and number of spectral fit parameters do not match.
• AttributeError – If _minimiser has not been set.
• AttributeError – If _fit_results has not been set.
• ValueError – If (un)expected per_bin flag in minimiser.
• ValueError – If (un)expected integer value for num_bins, in fit_results.
• ValueError – If (un)expected per_bin flag in test_statistic.

check_roi(roi)

Checks the ROI used to fit.

Parameters:

roi (dict) – roi you want to check.

Raises:

• TypeError – If roi is not a dict
• TypeError – If value in roi dict is not a list or a tuple
• CompatibilityError – If the length of a value in the roi dict is not 2.

check_spectra(spectra)

Checks the spectra you want to fit.

Parameters:

spectra (echidna.core.spectra.Spectra) – Spectra you want to check.

Raises:

• ValueError – If roi low value and spectra low value are not equal.
• ValueError – If roi high value and spectra high value are not equal.

fit()

Gets the value of the test statistic used for fitting.

Returns:float or numpy.array: The resulting test statisic(s) dependent upon what method is used to compute the statistic.

get_data()

Gets the data you are fitting.

Returns:echidna.core.spectra.Spectra: The data you are fitting.

get_fit_config()

get_fit_results()

Gets the fit results object for the fit.

Returns:echidna.core.fit.FitResults: FitResults for the fit.

get_fixed_background()

Gets the fixed background you are fitting.

Returns:echidna.core.spectra.Spectra: The fixed background you are fitting.

get_floating_backgrounds()

Gets the floating backgrounds you are fitting.

Returns:The floating backgrounds you are fitting. Return type:list

get_minimiser()

Gets the minimiser you are using.

Returns:echidna.limit.minimise.Minimiser: The minimiser

get_roi()

Gets the region of interest (roi)

Returns:The region of interest Return type:dict

get_roi_pars(spectra)

Get the parameters of a spectra that contain the roi.

the roi parameters for.

Returns:Of the names of the spectra parameters which contain the roi. Return type:list

get_signal()

Gets the signal you are fitting.

Returns:echidna.core.spectra.Spectra: The fixed background you are fitting.

get_test_statistic()

Gets the class instance you are using to calculate the test statistic used in the fit.

Returns:(echidna.limit.test_statistic.TestStatistic): The class instance used to calculate test statistics.

load_pre_made(spectrum, global_pars)

Load pre-made convolved spectra.

This method is used to load a pre-made spectra convolved with certain resolution, energy-scale or shift values, or a combination of two or more at given values.

The method loads the loads the correct spectra from HDF5s, stored in the given directory.

Parameters:spectrum (echidna.core.spectra.Spectra) – Spectrum to convolve. Returns:(echidna.core.spectra.Spectra): Convolved spectrum, ready for applying further systematics or fitting.

make_fixed_background(spectra_dict, shrink=True)

Makes a spectrum for fixed backgrounds and stores it in the class.

Parameters:

• spectra_dict (dict) – Dictionary containing spectra as keys and prior counts as values.
• shrink (bool, optional) – If set to True (default), shrink() method is called on the spectra shrinking it to the ROI.

remove_signal()

Removes the signal spectra from the class.

set_data(data, shrink=True)

Sets the data you want to fit.

Parameters:

• data (echidna.core.spectra.Spectra) – Data spectrum you want to fit.
• shrink (bool, optional) – If set to True (default), shrink() method is called on the spectra shrinking it to the ROI.

set_fit_config(fit_config)

Parameters:fit_config (echidna.core.spectra.FitConfig) – Config for fit. Raises:TypeError – If fit_config is not of type FitConfig.

set_fit_results(fit_results=None)

Parameters:fit_results (FitResults, optional) – The fit results instance. Raises:IndexError – If fit config contains no parameters.

set_fixed_background(fixed_background, shrink=True)

Sets the fixed background you want to fit.

Parameters:

• fixed_background (echidna.core.spectra.Spectra) – The fixed background spectrum you want to fit.
• shrink (bool, optional) – If set to True (default) shrink() method is called on the spectra shrinking it to the ROI.

set_floating_backgrounds(floating_backgrounds, shrink=True)

Sets the floating backgrounds you want to fit.

Parameters:

• floating_backgrounds (list) – List of backgrounds you want to float in the fit.
• shrink (bool, optional) – If set to True (default), shrink() method is called on the spectra shrinking it to the ROI.

set_minimiser(minimiser=None)

Sets the minimiser to use in fitting.

Parameters:minimiser (echidna.limit.minimise.Minimiser, optional) – The minimiser to use in the fit. Raises:IndexError – If fit config contains no parameters.

set_pre_made_dir(directory)

Sets the directory in which pre-made convolved spectra are stored.

Parameters:directory (string) – Directory in which pre-made spectra are located.

set_roi(roi)

Sets the region of interest you want to fit in.

Parameters:roi (dictionary) – The Region Of Interest you want to fit in. The format of roi is e.g. {“energy”: (2.4, 2.6), “radial3”: (0., 0.2)}

set_signal(signal, shrink=True)

Sets the signal you want to fit.

Parameters:

• signal (echidna.core.spectra.Spectra) – The signal spectrum you want to fit.
• shrink (bool, optional) – If set to True (default) shrink() method is called on the spectra shrinking it to the ROI.

set_test_statistic(test_statistic)

Sets the method you want to use to calculate test statistics in

the fit.

An appropriate class for calculating test statistics.

shrink_all()

Shrinks all the spectra used in the fit to the roi.

shrink_spectra(spectra)

Shrinks the spectra used in the fit to the roi.

Parameters:spectra (echidna.core.spectra.Spectra) – Spectra you want to shrink to the roi.

echidna.fit.fit_results module

Fit results module, containing FitResults class.

class echidna.fit.fit_results.FitResults(fit_config, spectra_config, name=None)

Bases: object

Base class for handling results of the fit.

Parameters:

• fit_config (echidna.core.spectra.GlobalFitConfig) – The configuration for fit. This should be a direct copy of the FitConfig in echidna.limit.fit.Fit.
• spectra_config (echidna.core.spectra.SpectraConfig) – The for spectra configuration. The recommended spectrum config to include here is the one from the data spectrum, to which you are fitting.
• name (str, optional) – Name of this FitResults class instance. If no name is supplied, name from fit_results will be taken and appended with “_results”.

Variables:

• _fit_config (echidna.core.spectra.GlobalFitConfig) – The configuration for fit. This should be a direct copy of the FitConfig in echidna.limit.fit.Fit.
• _spectra_config (echidna.core.spectra.SpectraConfig) – The for spectra configuration. The recommended spectrum config to include here is the one from the data spectrum, to which you are fitting.
• _name (string) – Name of this FitResults class instance.
• _stats (numpy.ndarray) – Array of values of the test statistic calculated during the fit.
• _penalty_terms (numpy.ndarray) – Array of values of the penalty terms calculated during the fit.
• _minimum_value (float) – Minimum value of the array returned by get_fit_data().
• _minimum_position (tuple) – Position of the test statistic minimum value. The tuple contains the indices along each fit parameter (dimension), acting as coordinates of the position of the minimum.
• _resets (int) – Number of times the grid has been reset.

Examples

>>> fit_results = FitResults(fitter.get_config(), data.get_config())

get_fit_config()

Returns:(echidna.limit.fit.FitConfig): Configuration of fit.

get_minimum_position()

Returns:(float): Position of the minimum value in the array returned by get_fit_data(), stored in _minimum_position.

get_minimum_value()

Returns:(float): Minimum value of the array returned by get_fit_data(), stored in _minimum_value.

get_name()

Returns:Name of fit results object. Return type:string

get_penalty_term(indices)

Gets the array of penalty terms.

Note

Unlike the echidna.fit.summary.Summary class individual penalty contributions from each fit parameter are not stored here, only the total penalty term value.

Parameters:

indices (tuple) – The index along each fit parameter dimension specifying the coordinates from which to retrieve the total penalty term value.

Returns:

(numpy.ndarray): Array stored in _penalty_terms. Values of the penalty term calculated during the fit.

Raises:

• TypeError – If the indices supplied are not at tuple
• IndexError – If the number of indices supplied does not match the dimensions of the fit
• IndexError – If the indices supplied are out of bounds for the fit dimensions

get_penalty_terms()

Gets the array of penalty terms.

Note

Unlike the echidna.fit.summary.Summary class individual penalty contributions from each fit parameter are not stored here, only the total penalty term value.

Returns:(numpy.ndarray): Array stored in _penalty_terms. Values of the penalty term calculated during the fit.

get_raw_stat(indices)

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

Warning

This has no penalty term contributions added.

Note

Unlike get_stat(), here you can specify indices for any number of fit parameters dimensions, so to get a slice of the raw array.

Parameters:indices (tuple) – Index along each fit parameter (dimension) specifiying the coordinates in the array. Returns:(float or numpy.ndarray): The raw test statistic(s) at the given indices. Raises:TypeError – If the indices supplied are not at tuple

get_raw_stats()

Gets the raw test statistics array.

Warning

This has no penalty term contributions added.

Returns:numpy.array: The raw test statistics values at each combination of fit parameter values.

get_resets()

Returns:Number of times the grid has been reset (_resets). Return type:int

get_stat(indices)

Combines the test-statistic array (collapsed to the parameter values grid - i.e. summed over spectral bins) with the penalty term grid of the same shape, for a single bin, specified by indices.

Warning

Penalty term contributions are included here.

Parameters:

indices (tuple) – The index along each fit parameter dimension specifying the coordinates from which to retrieve the test statistic value.

Returns:

(float): Combination of the value of the test statistic calculated during the fit and the penalty term value.

Raises:

• TypeError – If the indices supplied are not at tuple
• IndexError – If the number of indices supplied does not match the dimensions of the fit
• IndexError – If the indices supplied are out of bounds for the fit dimensions

get_stats()

Combines the test-statistic array (collapsed to the parameter values grid - i.e. summed over spectral bins) with the penalty term grid of the same shape.

Warning

Penalty term contributions are included here.

Returns:(numpy.ndarray): Array combining the values of the test statistic calculated during the fit and the penalty term values.

get_summary()

Get a summary of the fit parameters.

Returns:Results of fit. Dictionary with fit parameter names as keys and a nested dictionary as values containing the keys best_fit and penalty_term with the corresponding values for the parameter. Return type:dict

nd_project_stat(indices, *parameters)

Projects the test statistic values, at given the given indices, onto the axes specified by fit and spectral parameters.

Warning

If only fit parameters are specified all spectral dimensions are collapsed and penalty term contributions are included. If any spectral parameters are provided penalty term contributions are not included.

Parameters:

indices – The index along each fit parameter dimension specifying the coordinates from which to retrieve the test statistic value.

Returns:

numpy.ndarray: Projection of _stats array, at the given indices, onto the given parameter axes.

Raises:

• TypeError – If the indices supplied are not at tuple
• IndexError – If the parameter names supplied do not match any of those stored in the fit or spectra configs.

nd_project_stats(*parameters)

Projects the test statistic values onto the axes specified by fit and spectral parameters.

Warning

If only fit parameters are specified all spectral dimensions are collapsed and penalty term contributions are included. If any spectral parameters are provided penalty term contributions are not included.

parameters onto which to project the test statistic values.

Returns:numpy.ndarray: Projection of _stats array onto the given parameter axes. Raises:IndexError – If the parameter names supplied do not match any of those stored in the fit or spectra configs.

reset_grids()

Resets the grids stored in _stats and

_penalty_terms, including shape.

Warning

If fit parameters have been added/removed, calling this method will increase/decrease the dimensions of the grid to compensate for this change.

set_fit_config(fit_config)

Set the fit config.

Warning

This will automatically call reset_grid() to update the grid based on the new fit config

Parameters:fit_config (echidna.core.spectra.GlobalFitConfig) – The configuration for fit. This should be a direct copy of the echidna.core.spectra.GlobalFitConfig object in echidna.limit.fit.Fit.

set_minimum_position(minimum_position)

Parameters:minimum_position (float) – Position of the minimum value of the array returned by get_fit_data().

set_minimum_value(minimum_value)

Parameters:minimum_value (float) – Minimum value of the array returned by get_fit_data().

set_penalty_term(penalty_term, indices)

Sets the total penalty term value at the point in the array specified by indices.

Parameters:

• penalty_term (float) – Best fit value of a fit parameter.
• indices (tuple) – The index along each fit parameter dimension specifying the coordinates from which to set the total penalty term value.

Raises:

• TypeError – If penalty_term is not a float.
• TypeError – If the indices supplied are not at tuple
• IndexError – If the number of indices supplied does not match the dimensions of the fit
• IndexError – If the indices supplied are out of bounds for the fit dimensions

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_spectra_config(spectra_config)

Set the spectra config.

Warning

This will automatically call reset_grid() to update the grid based on the new fit config

Parameters:spectra_config (echidna.core.spectra.SpectraConfig) – The configuration for the spectra. This should usually be a direct copy of the echidna.core.spectra.SpectraConfig in the data spectrum.

set_stat(stat, indices)

Sets the test statistic values in array at the point specified by indices

Parameters:

• stat (numpy.ndarray) – Values of the test statistic.
• indices (tuple) – Position in the array.

Raises:

• TypeError – If the indices supplied are not at tuple
• IndexError – If the number of indices supplied does not match the dimensions of the fit
• IndexError – If the indices supplied are out of bounds for the fit dimensions
• 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.

echidna.fit.minimise module

Module containing classes that act as minimisers in a fit.

class echidna.fit.minimise.GridSearch(fit_config, spectra_config, name=None, per_bin=False, use_numpy=True)

Bases: echidna.fit.fit_results.FitResults, echidna.fit.minimise.Minimiser

A grid-search minimisation algorithm.

Although this is minimisation, it makes more sense for the class to inherit from FitResults, as the _stats attribute is the same in both classes, as is the _fit_config.

Parameters:

• fit_config (echidna.core.spectra.GlobalFitConfig) – Configuration for fit. This should be a direct copy of the FitConfig in echidna.limit.fit.Fit.
• spectra_config (echidna.core.spectra.SpectraConfig) – The for spectra configuration. The recommended spectrum config to include here is the one from the data spectrum, to which you are fitting.
• name (str, optional) – Name of this FitResults class instance. If no name is supplied, name from fit_results will be taken and appended with “_results”.
• per_bin (bool, optional) – Flag if minimiser should expect a test statistic value per-bin.
• use_numpy (bool, optional) – Flag to indicate whether to use the built-in numpy functions for minimisation and locating the minimum, or use the find_minimum() method. Default is to use numpy.

Variables:

• _fit_config (echidna.core.spectra.GlobalFitConfig) – The configuration for fit. This should be a direct copy of the FitConfig in echidna.limit.fit.Fit.
• _spectra_config (echidna.core.spectra.SpectraConfig) – The for spectra configuration. The recommended spectrum config to include here is the one from the data spectrum, to which you are fitting.
• _name (string) – Name of this GridSearch class instance.
• _stats (numpy.ndarray) – Array of values of the test statistic calculated during the fit.
• _penalties (numpy.ndarray) – Array of values of the penalty terms calculated during the fit.
• _minimum_value (float) – Minimum value of the array returned by get_fit_data().
• _minimum_position (tuple) – Position of the test statistic minimum value. The tuple contains the indices along each fit parameter (dimension), acting as coordinates of the position of the minimum.
• _resets (int) – Number of times the grid has been reset.
• _type (string) – Type of minimiser, e.g. GridSearch
• _per_bin (bool, optional) – Flag if minimiser should expect a test statistic value per-bin.
• _use_numpy (bool, optional) – Flag to indicate whether to use the built-in numpy functions for minimisation and locating the minimum, or use the find_minimum() method. Default is to use numpy.

_get_fit_par_values()

Internal method. Gets next array of parameter values to test in fit.

Yields:

• (numpy.array): Next array of parameter values to –

  test in fit.

• (numpy.array): Indices of these parameter values.

_get_values(index, values, indices)

Internal method. Called recursively to populate the array of current parameter values.

Yields:

• (numpy.array): Next array of parameter values to –

  test in fit.

• (numpy.array): Indices of these parameter values.

_update_coords(coords, new_coords)

Internal method called by find_minimum() to update the stored co-ordinates of minima.

This method takes the new co-ordinates in new_coords and works out the indices to select the correct (previously- calculated) co-ordinates for the positions of minima, in the inner dimensions.

Parameters:

• coords (numpy.ndarray) – 2D array containing the previously calculated co-ordinates for the inner dimensions.
• new_coords (numpy.ndarray) – Array containing the co-ordinates of each minima calculated for the current dimension.

Returns:

(numpy.ndarray): 2D array containing the updated arrays of co-ordinates, for all dimensions processed so far.

find_minimum(array)

Alternative method for finding the minimum.

Starting from the innermost dimension, locates the minima along the axis - effectively minimising over lots of 1D arrays. Once the minima are located, this axis is collapsed down to next innermost, storing just the values at the minima. The position of each minima is also stored in the coords array.

This process is then repeated for the next innermost array. However now when we locate the position of each minima, we also wish to get the corresponding position calculated at the previous dimension - the _update_coords() does this, concatenating the current locations with the previous ones so we start to build up an array of co-ordinates.

As the code works outwards through the dimensions, the number of co-ordinates are added, but the choice of co-ordinates is reduced. Until the outermost dimension is processed and then ideally only one minimum value and one set of co-ordinates remains.

Parameters:array (numpy.ndarray) – Array to minimise. Returns:Minimum value in array. tuple: Location (co-ordinates) of minimum. Return type:float

Warning

If the exact minimum value is repeated more than once in the array, the location with the lowest coordinate values (starting from the outermost dimension) will be returned. E.g. if two equal minima are at (4, 10, 15) and (41, 2, 12), the location (4, 10, 15) would be returned

minimise(funct, test_statistic)

Method to perform the minimisation.

Parameters:

• funct (callable) – Callable function to calculate the value of the test statistic you wish to minimise, for each combination of parameter values tested. The function must only accept, as arguments, a variable-sized array of parameter values. E.g. def funct(*args). Within the echidna framework, the echidna.limit.fit.Fit.funct() method is the recommened callable to use here.
• test_statistic (echidna.limit.test_statistic) – The test_statistic object used to calcualte the test statistics.

Variables:

• _minimum_value (float) – Minimum value of test statistic found.
• _minimum_position (tuple) – Position of minimum.

Returns:

Minimum value found during minimisation.

Return type:

float

class echidna.fit.minimise.Minimiser(name, per_bin=False)

Bases: object

Base class for minimiser objects.

Parameters:

• name (string) – Name of minimiser.
• per_bin (bool, optional) – Flag if minimiser should expect a test statistic value per-bin.

Variables:

• _name (string) – Name of minimiser.
• _per_bin (bool, optional) – Flag if minimiser should expect a test statistic value per-bin.
• _type (string) – Type of minimiser, e.g. GridSearch

minimise(funct, test_statistic)

Abstract base class method to override.

Parameters:

• funct (callable) – Callable function to calculate the value of the test statistic you wish to minimise, for each combination of parameter values tested. The function must only accept, as arguments, a variable-sized array of parameter values. E.g. def funct(*args). Within the echidna framework, the echidna.limit.fit.Fit.funct() method is the recommened callable to use here.
• test_statistic (echidna.limit.test_statistic) – The test_statistic object used to calcualte the test statistics.

Returns:

Minimum value found during minimisation.

Return type:

float

echidna.fit.test_statistic module

Module to hold classes for various test statistics that can be used for fitting.

Note

All forms of chi-squared are as defined in:

• S. Baker & R. D. Cousins, Nucl. Inst. and Meth. in Phys. Res. 211, 437-442 (1984)

class echidna.fit.test_statistic.BakerCousinsChi(per_bin=True)

Bases: echidna.fit.test_statistic.TestStatistic

Test statistic class for calculating the Baker-Cousins chi-squared (poisson likelihood) test statistic.

Parameters:

• name (string) – Name of test statistic.
• per_bin (bool) – If True (default) the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

Variables:

• _name (string) – Name of test statistic.
• _per_bin (bool) – If True the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

classmethod get_penalty_term(current_value, prior, sigma)

Calculates a penalty term value, for a given fit parameter, for the BakerCousinsChi test statistic.

Parameters:

• current_value (float) – current value of a given fit parameter
• prior (float) – Prior value of a given fit parameter
• sigma (float) – Sigma value of a given fit parameter

Returns:

Value of the penalty term

Return type:

float

class echidna.fit.test_statistic.BakerCousinsLL(per_bin=True)

Bases: echidna.fit.test_statistic.TestStatistic

Test statistic class for calculating the Baker-Cousins log likelihood

ratio test statistic.

Parameters:

• name (string) – Name of test statistic.
• per_bin (bool) – If True (default) the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

Variables:

• _name (string) – Name of test statistic.
• _per_bin (bool) – If True the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

classmethod get_penalty_term(current_value, prior, sigma)

Calculates a penalty term value, for a given fit parameter, for the BakerCousinsLL test statistic.

Parameters:

• current_value (float) – current value of a given fit parameter
• prior (float) – Prior value of a given fit parameter
• sigma (float) – Sigma value of a given fit parameter

Returns:

Value of the penalty term

Return type:

float

class echidna.fit.test_statistic.Neyman(per_bin=True)

Bases: echidna.fit.test_statistic.TestStatistic

Test statistic class for calculating the Neyman chi-squared test statistic.

Parameters:

• name (string) – Name of test statistic.
• per_bin (bool) – If True (default) the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

Variables:

• _name (string) – Name of test statistic.
• _per_bin (bool) – If True the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

classmethod get_penalty_term(current_value, prior, sigma)

Calculates a penalty term value, for a given fit parameter, for the Neyman chi squared test statistic.

Parameters:

• current_value (float) – current value of a given fit parameter
• prior (float) – Prior value of a given fit parameter
• sigma (float) – Sigma value of a given fit parameter

Returns:

Value of the penalty term

Return type:

float

class echidna.fit.test_statistic.Pearson(per_bin=True)

Bases: echidna.fit.test_statistic.TestStatistic

Test statistic class for calculating the Pearson chi-squared test statistic.

Parameters:

• name (string) – Name of test statistic.
• per_bin (bool) – If True (default) the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

Variables:

• _name (string) – Name of test statistic.
• _per_bin (bool) – If True the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

classmethod get_penalty_term(current_value, prior, sigma)

Calculates a penalty term value, for a given fit parameter, for the Pearson chi squared test statistic.

Parameters:

• current_value (float) – current value of a given fit parameter
• prior (float) – Prior value of a given fit parameter
• sigma (float) – Sigma value of a given fit parameter

Returns:

Value of the penalty term

Return type:

float

class echidna.fit.test_statistic.TestStatistic(name, per_bin=True)

Bases: object

Base class for the calculation of a test statistic.

The calculation of any test statistic is based on one spectrum containing observed events and one containing expected events. It is assumed that the observed events form the “data” spectrum and the expected events form the spectrum predicted by the model.

Parameters:

• name (string) – Name of test statistic.
• per_bin (bool) – If True (default) the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

Variables:

• _name (string) – Name of test statistic.
• _per_bin (bool) – If True the statistic in each bin is returned as a numpy.array. If False one value for the statistic is returned for the entire array.

_compute(observed, expected)

Calculates the test statistic.

Parameters:

• observed (numpy.array or float) – Number of observed events
• expected (numpy.array or float) – Number of expected events

Returns:

Calculated test statistic.

Return type:

float

_get_stats(observed, expected)

Gets the test statistic for each bin.

Parameters:

• observed (numpy.array or float) – Number of observed events
• expected (numpy.array or float) – Number of expected events

Raises:

ValueError – If arrays are different lengths.

Returns:

numpy.array: Calculated chi squared for each bin.

compute_statistic(observed, expected)

Compute the value of the test statistic.

Parameters:

• observed (numpy.ndarray) – 1D array containing the observed data points.
• expected (numpy.ndarray) – 1D array containing the expected values predicted by the model.

Returns:

(float or numpy.array): Computed value(s) of test statistic. A float is returned if _per_bin is False. Otherwise an array of computed test statistic values, for each bin, is returned.

get_name()

Returns:Name of test statistic, stored in _name Return type:string

get_penalty_term(current_value, prior, sigma)

Calculates a penalty term value, for a given fit parameter, for this test statistic.

Parameters:

• current_value (float) – current value of a given fit parameter
• prior (float) – Prior value of a given fit parameter
• sigma (float) – Sigma value of a given fit parameter

Returns:

Value of the penalty term

Return type:

float

Module contents