echidna.core package

Submodules

echidna.core.config module

Echidna’s config module.

Contains the Config class and all classes that inherit from it.

class echidna.core.config.Config(name, parameters)

Bases: object

The base class for creating config classes.

Parameters:

name (string) – The name of the config.

Variables:

• _name (string) – The name of the config.
• _type (string) – The type of the config, this affects it’s parameter types
• _parameters (collections.OrderedDict) – Dictionary of parameters.

add_par(par)

Add parameter to the config.

Parameters:par (echidna.core.spectra.Parameter) – The parameter you want to add.

dump()

Abstract base class method to override.

Dumps the config to a config dictionary, containing all parameters. The dictionary has the form specified in the Config.load() method.

Returns:Dictionary containing all the information on the parameters. Return type:dict

dump_to_file(path='', filename=None)

Abstract base class method to override.

Write config to YAML file.

Parameters:

• path (string, optional) – Location to save yaml file to, default is the current directory.
• filename (string, optional) – Filename for yaml file. If no filename is supplied, the default is “spectra_config.yml”. If a blank filename “” is given the config’s name is used.

get_index(parameter)

Return the index of a parameter within the existing set

Parameters:parameter (string) – Name of the parameter. Raises:IndexError – parameter is not in the config. Returns:Index of the parameter Return type:int

get_name()

Returns:Name of Config class instance - stored in _name. Return type:string

get_par(name)

Get a named FitParameter.

Parameters:name (string) – Name of the parameter. Returns:echidna.core.spectra.Parameter: Named parameter.

get_par_by_index(index)

Get parameter corresponding to given index

Parameters:index (int) – Index of parameter. Returns:echidna.core.spectra.Parameter: Corresponding parameter.

get_pars()

Get list of all parameter names in the config.

Returns:List of parameter names Return type:list

get_shape()

Get the shape of the parameter space.

Returns:A tuple constructed of the number of bins for each parameter in the config - this can be thought of as the full shape of the parameter space, whether it is the shape of the parameter space for the fit, or the shape of the spectral dimensions. Return type:tuple

get_type()

Returns:Type of Config class instance - stored in _name. Return type:string

classmethod load(config, name='config')

Abstract base class method to override.

Initialise Config class from a config dictionary (classmethod).

Parameters:

• config (dict) – Dictionary to create config out of.
• name (string, optional) – Name to assign to the Config. If no name is supplied the default ‘spectra_config’ will be used.

Returns:

(Config): A config object containing the parameters from the config dictionary.

Raises:

KeyError – If the config dictionary has the wrong format.

Warning

config dict must have valid format.

Valid format is:

{"parameters": {
    "<parameter>": {
        "low": <low>,
        "high": <high>,
        "bins": <bins>}}}

classmethod load_from_file(filename, name=None)

Abstract base class method to override.

Initialise Config class from a config file (classmethod).

Parameters:

• filename (str) – path to config file
• name (string, optional) – Assign a name to the Config created. If no name is supplied, the default is ‘config’. If a blank string is supplied, the name of the file will be used.

Returns:

(Config): A config object containing the parameters in the file.

class echidna.core.config.GlobalFitConfig(config_name, parameters)

Bases: echidna.core.config.Config

Configuration container for floating systematics and fitting Spectra

objects. Able to load directly with a set list of FitParameters or from yaml configuration files.

Parameters:

• config_name (string) – Name of config
• parameters (collections.OrderedDict) – List of FitParameter objects

add_config(config)

Add pars from a echidna.core.spectra.Config to this

echidna.core.spectra.GlobalFitConfig

Parameters:config (echidna.core.spectra.Config) – Config to be added.

add_par(par, par_type)

Add parameter to the global fit config.

Parameters:

• par (echidna.core.spectra.FitParameter) – Parameter you want to add.
• par_type (string) – The type of parameter (global or spectra).

dump(basic=False)

Dumps the config to a global fit config dictionary, containing all the ‘global’ parameters, and a spectral fit comfig dictionary (if required), containing any ‘spectral’ parameters that have been added. The dictionaries have, respectively, the forms specified in the GlobalFitConfig.load() and echidna.core.spectra.SpectralFitConfig.load() methods.

Returns:

Dictionary containing all the information on the

‘global’ parameters.

dict: Dictionary containing all the information on the

‘spectral’ parameters.

Return type:dict

dump_to_file(path='', global_fname=None, spectral_fname=None, basic=False)

Write config(s) to YAML file. Separate files are created for global and spectral parameters.

Parameters:

• path (string, optional) – Location to save yaml file(s) to, default is the current directory.
• global_fname (string, optional) – Filename for global parameters yaml file. If no filename is supplied, the default is “global_fit_config.yml”. If a blank filename “” is given the config’s name is used (+ “_global”).
• spectral_fname (string, optional) – Filename for spectral parameters yaml file. If no filename is supplied, the default is “spectral_fit_config.yml”. If a blank filename “” is given the config’s name is used (+ “_spectral”).
• basic (bool, optional) – If True, only the basic properties: prior, sigma, low, high and bins are included.

get_global_pars()

Gets the parameters which are applied to all spectra

simultaneously.

Returns:Of echidna.core.spectra.FitParameter objects. Return type:list

get_par(name)

Get requested parameter:

Parameters:name (string) – Name of the parameter Returns:echidna.core.spectra.FitParameter: The requested parameter.

get_spectra_pars()

Gets the parameters that are applied to individual spectra.

Returns:Of echidna.core.spectra.FitParameter objects. Return type:list

classmethod load(global_config, spectral_config=None, name='global_fit_config')

Initialise GlobalFitConfig class from a config dictionary (classmethod).

Parameters:

• config (dict) – Dictionary to create config out of.
• spectral_config (dict) – Dictionary of spectral fit parameters to create config out of.
• name (string, optional) – Name to assign to the GlobalFitConfig. If no name is supplied the default ‘global_fit_config’ will be used.

Returns:

(echidna.core.spectra.GlobalFitConfig): A config object containing the parameters in the file called filename.

Raises:

• KeyError – If the global_config dictionary does not start with the key ‘global_fit_parameters’ as this suggests the dictionary has the wrong format.
• IndexError – If an invalid global fit parameter name is encountered.
• KeyError – If the spectral_config dictionary does not start with the key ‘spectral_fit_parameters’ as this suggests the dictionary has the wrong format.
• IndexError – If an invalid spectral fit parameter name is encountered.

Warning

config dict must have valid format.

Valid format is:

{"gloabal_fit_parameters": {
    "<spectral_dimension>": {
        "<parameter_name>": {
            "prior": <prior>,
            "sigma": <sigma>,
            "low": <low>,
            "high": <high>,
            "bins": <bins>}}}}

For spectral config see SpectralFitConfig.load().

classmethod load_from_file(filename, sf_filename=None, name=None)

Initialise GlobalFitConfig class from a config file (classmethod).

Parameters:

• filename (string) – path to config file
• sf_filename (string, optional) – path to a separate spectral fit config file, to include.
• name (string, optional) – Assign a name to the GlobalFitConfig created. If no name is supplied, the default is ‘global_fit_config’. If a blank string is supplied, the name of the file will be used.

Returns:

(echidna.core.spectra.GlobalFitConfig): A config object containing the parameters in the file called filename.

class echidna.core.config.SpectraConfig(config_name, parameters)

Bases: echidna.core.config.Config

Configuration container for Spectra objects. Able to load directly with a set list of SpectraParameters or from yaml configuration files.

Parameters:parameters (collections.OrderedDict) – List of SpectraParameter objects

dump()

Dumps the spectra config to a config dictionary, containing all spectra parameters. The dictionary has the form specified in the SpectraConfig.load() method.

Returns:Dictionary containing all the information on the spectra parameters. Return type:dict

dump_to_file(path='', filename=None)

Write spectra config to YAML file.

Parameters:

• path (string, optional) – Location to save yaml file to, default is the current directory.
• filename (string, optional) – Filename for yaml file. If no filename is supplied, the default is “spectra_config.yml”. If a blank filename “” is given the config’s name is used.

get_dim(par)

Get the dimension of par. The _mc, _reco and _truth suffixes are removed.

Parameters:par (string) – Name of the parameter Returns:The dimension of par

get_dim_type(dim)

Returns the type of the dimension i.e. mc, reco or truth.

Parameters:dim (string) – The name of the dimension Raises:IndexError – dim is not in the spectra. Returns:The type of the dimension (mc, reco or truth) Return type:string

get_dims()

Get list of dimension names. The _mc, _reco and _truth suffixes are removed.

Returns:List of the dimensions names of the config. Return type:list

classmethod load(config, name='config')

Initialise SpectraConfig class from a config dictionary (classmethod).

Parameters:

• config (dict) – Dictionary to create spectra config out of.
• name (string, optional) – Name to assign to the SpectraConfig. If no name is supplied the default ‘spectra_config’ will be used.

Returns:

(SpectraConfig): A config object containing the spectra parameters from the config dictionary.

Raises:

KeyError – If the config dictionary does not start with the key ‘parameters’ as this suggests the dictionary has the wrong format.

Warning

config must have valid format.

Valid format is:

{"parameters": {
    "<spectral_parameter>": {
        "low": <low>,
        "high": <high>.
        "bins": <bins>}}}

classmethod load_from_file(filename, name=None)

Initialise SpectraConfig class from a config file (classmethod).

Parameters:

• filename (str) – path to config file
• name (string, optional) – Assign a name to the SpectraConfig created. If no name is supplied, the default is ‘spectra_config’. If a blank string is supplied, the name of the file will be used.

Returns:

(SpectraConfig): A config object containing the parameters in the file.

class echidna.core.config.SpectraFitConfig(config_name, parameters, spectra_name)

Bases: echidna.core.config.Config

Configuration container for floating systematics and fitting Spectra

objects. Able to load directly with a set list of FitParameters or from yaml configuration files.

Parameters:

• config_name (string) – Name of config
• parameters (collections.OrderedDict) – List of FitParameter objects
• spectra_name (string) – Name of the spectra associated with the echidna.core.spectra.SpectraFitConfig

Variables:

_spectra_name (string) – Name of the spectra associated with the echidna.core.spectra.SpectraFitConfig

dump(basic=False)

Dumps the config to a spectral fit comfig dictionary, containing all ‘spectral’ fit parameters. The dictionary has the form specified in the SpectralFitConfig.load() method.

Returns:Dictionary containing all the information on the ‘spectral’ parameters. Return type:dict

dump_to_file(path='', spectral_fname=None, basic=False)

Write config(s) to YAML file. Separate files are created for global and spectral parameters.

Parameters:

• path (string, optional) – Location to save yaml file(s) to, default is the current directory.
• spectral_fname (string, optional) – Filename for spectral parameters yaml file. If no filename is supplied, the default is “spectral_fit_config.yml”. If a blank filename “” is given the config’s name is used (+ “_spectral”).
• basic (bool, optional) – If True, only the basic properties: prior, sigma, low, high and bins are included.

classmethod load(config, spectra_name, name='spectral_fit_config')

Initialise SpectraFitConfig class from a config dictionary (classmethod).

Parameters:

• config (dict) – Dictionary to create config out of.
• name (string, optional) – Name to assign to the SpectraFitConfig. If no name is supplied the default ‘spectral_fit_config’ will be used.

Returns:

(SpectraFitConfig): A config object containing the parameters from the config dictionary.

Raises:

• KeyError – If the config dictionary does not start with the key ‘spectral_fit_parameters’ as this suggests the dictionary has the wrong format.
• IndexError – If an invalid spectral fit parameter name is encountered.

Warning

config dict must have valid format.

Valid format is:

{"spectral_fit_parameters": {
    "<parameter_name>": {
        "prior": <prior>,
        "sigma": <sigma>,
        "low": <low>,
        "high": <high>,
        "bins": <bins>}}}

classmethod load_from_file(filename, spectra_name, name=None)

Initialise SpectraFitConfig class from a config file (classmethod).

Parameters:

• filename (str) – path to config file
• spectra_name (string) – Name of the spectra associated with the echidna.core.spectra.SpectraFitConfig
• name (string, optional) – Assign a name to the SpectraFitConfig created. If no name is supplied, the default is ‘spectral_fit_config’. If a blank string is supplied, the name of the file will be used.

Returns:

(SpectraFitConfig): A config object containing the parameters in the file.

echidna.core.dsextract module

class echidna.core.dsextract.EnergyExtractMC(fv_radius=None, reco_pos=False)

Bases: echidna.core.dsextract.Extractor

Quenched energy extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• reco_pos (bool, optional) – If true then position cuts will be made on reconstructed position. If False (default) then MC position is used for cuts.

Variables:

_reco_pos (bool) – If true then position cuts will be made on

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(mc, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• mc (RAT.DS.MC) – Monte Carlo entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether energy of an ntuple MC is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(mc, ds)

Check whether energy of a DS::MC is valid

Parameters:

• mc (RAT.DS.MC) – entry
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get energy value from an ntuple MC

Parameters:entry (ROOT.TChain) – chain entry Returns:True quenched energy Return type:float

get_value_root(mc)

Get energy value from a DS::MC

Parameters:mc (RAT.DS.MC) – entry Returns:True quenched energy Return type:float

class echidna.core.dsextract.EnergyExtractReco(fv_radius=None, mc_pos=False)

Bases: echidna.core.dsextract.Extractor

Reconstructed energy extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• mc_pos (bool, optional) – If true then MC position is used for cuts. If False (default) then position cuts will be made on reconstructed position.

Variables:

_mc_pos (bool) – If true then MC position is used for cuts. If False then position cuts will be made on reconstructed position.

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(ev, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• ev (RAT.DS.EV) – Event entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether energy of an ntuple EV is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(ev, ds)

Check whether energy of a DS::EV is valid

Parameters:

• ev (RAT.DS.EV) – event
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get energy value from an ntuple EV

Parameters:entry (ROOT.TChain) – chain entry Returns:Reconstructed energy Return type:float

get_value_root(ev)

Get energy value from a DS::EV

Parameters:ev (RAT.DS.EV) – event Returns:Reconstructed energy Return type:float

class echidna.core.dsextract.EnergyExtractTruth(fv_radius=None, reco_pos=False)

Bases: echidna.core.dsextract.Extractor

True MC energy extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• reco_pos (bool, optional) – If true then position cuts will be made on reconstructed position. If False (default) then MC position is used for cuts.

Variables:

_reco_pos (bool) – If true then position cuts will be made on

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(mc, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• mc (RAT.DS.MC) – Monte Carlo entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether energy of an ntuple MC is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(mc, ds)

Check whether energy of a DS::MC is valid

Parameters:

• mc (RAT.DS.MC) – entry
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get energy value from an ntuple MC

Parameters:entry (ROOT.TChain) – chain entry Returns:True energy Return type:float

get_value_root(mc)

Get energy value from a DS::MC

Parameters:mc (RAT.DS.MC) – entry Returns:True energy Return type:float

class echidna.core.dsextract.Extractor(name, fv_radius)

Bases: object

Base class for extractor classes.

Parameters:

• name (str) – of the dimension
• fv_radius (float) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.

Variables:

• _name (str) – of the dimension
• _fv_radius (float) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.

class echidna.core.dsextract.Radial3ExtractMC(fv_radius=None, outer_radius=None, reco_pos=False)

Bases: echidna.core.dsextract.Extractor

True \((radius/outer\_radius)^3\) radial extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• outer_radius (float, optional) – The fixed radius used in calculating \((radius/outer\_radius)^3\). If None then the av_radius in echidna.calc.constants is used in the calculation.

Variables:

• _outer_radius (float) – The fixed radius used in calculating \((radius/outer\_radius)^3\).
• _reco_pos (bool) – If true then position cuts will be made on

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(mc, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• mc (RAT.DS.MC) – Monte Carlo entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether energy of an ntuple MC is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(mc, ds)

Check whether radius of a DS::MC is valid

Parameters:

• mc (RAT.DS.MC) – event
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get radius value from an ntuple MC

Parameters:entry (ROOT.TChain) – chain entry Returns:True \((radius/outer\_radius)^3\) Return type:float

get_value_root(mc)

Get radius value from a DS::MC

Parameters:mc (RAT.DS.MC) – event Returns:True \((radius/outer\_radius)^3\) Return type:float

class echidna.core.dsextract.Radial3ExtractReco(fv_radius=None, outer_radius=None, mc_pos=False)

Bases: echidna.core.dsextract.Extractor

Reconstructed \((radius/outer_radius)^3\) radial extraction

methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• outer_radius (float, optional) – The fixed radius used in calculating \((radius/outer\_radius)^3\). If None then the av_radius in echidna.calc.constants is used in the calculation.
• mc_pos – If true then MC position is used for cuts. If False (default) then position cuts will be made on reconstructed position.

Variables:

_mc_pos (bool) – If true then MC position is used for cuts. If False then position cuts will be made on reconstructed position.

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(ev, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• ev (RAT.DS.EV) – Event entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether radius of an ntuple EV is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(ev, ds)

Check whether radius of a DS::EV is valid

Parameters:

• ev (RAT.DS.EV) – event
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get radius value from an ntuple EV

Parameters:entry (ROOT.TChain) – chain entry Returns:Reconstructed \((radius/outer\_radius)^3\) Return type:float

get_value_root(ev)

Get radius value from a DS::EV

Parameters:ev (RAT.DS.EV) – event Returns:Reconstructed \((radius/outer\_radius)^3\) Return type:float

class echidna.core.dsextract.RadialExtractMC(fv_radius=None, reco_pos=False)

Bases: echidna.core.dsextract.Extractor

True radial extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• reco_pos (bool, optional) – If true then position cuts will be made on reconstructed position. If False (default) then MC position is used for cuts.

Variables:

_reco_pos (bool) – If true then position cuts will be made on

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(mc, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• mc (RAT.DS.MC) – Monte Carlo entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether energy of an ntuple MC is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(mc, ds)

Check whether radius of a DS::MC is valid

Parameters:

• mc (RAT.DS.MC) – event
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get radius value from an ntuple MC

Parameters:entry (ROOT.TChain) – chain entry Returns:True radius Return type:float

get_value_root(mc)

Get radius value from a DS::MC

Parameters:mc (RAT.DS.MC) – event Returns:True radius Return type:float

class echidna.core.dsextract.RadialExtractReco(fv_radius=None, mc_pos=False)

Bases: echidna.core.dsextract.Extractor

Reconstructed radial extraction methods.

Parameters:

• fv_radius (float, optional) – Fiducial radius. Applies a cut to remove events which have a radial position greater than the radius of the fiducial volume. If None no cut is applied.
• mc_pos (bool, optional) – If true then MC position is used for cuts. If False (default) then position cuts will be made on reconstructed position.

Variables:

_mc_pos (bool) – If true then MC position is used for cuts. If False then position cuts will be made on reconstructed position.

fv_cut_ntuple(entry)

Applies the fiducial volume (fv) cut to an ntuple entry.

Parameters:entry (ROOT.TChain) – chain entry Returns:Indicates pass or fail of cut Return type:bool

fv_cut_root(ev, ds)

Applies the fiducial volume (fv) cut to a root entry.

Parameters:

• ev (RAT.DS.EV) – Event entry
• ds (RAT.DS) – Data Structure entry

Raises:

ValueError – If reconstruced position cut is used on an mc event which has multiple evs.

Returns:

Indicates pass or fail of cut

Return type:

bool

get_valid_ntuple(entry)

Check whether radius of an ntuple EV is valid

Parameters:entry (ROOT.TChain) – chain entry Returns:Validity boolean Return type:bool

get_valid_root(ev, ds)

Check whether radius of a DS::EV is valid

Parameters:

• ev (RAT.DS.EV) – event
• ds (RAT.DS) – Data Structure entry

Returns:

Validity boolean

Return type:

bool

get_value_ntuple(entry)

Get radius value from an ntuple EV

Parameters:entry (ROOT.TChain) – chain entry Returns:Reconstructed radius Return type:float

get_value_root(ev)

Get radius value from a DS::EV

Parameters:ev (RAT.DS.EV) – event Returns:Reconstructed radius Return type:float

echidna.core.dsextract.function_factory(dimension, **kwargs)

Factory function that returns a dsextract class corresponding to the dimension (i.e. DS parameter) that is being extracted.

Parameters:

• dimension (str) – to extract from a RAT DS/ntuple file.
• kwargs (dict) – to be passed to and checked by the extractor.

Raises:

IndexError – dimension is an unknown parameter

Retuns:

echidna.core.dsextract.Extractor: Extractor object.

echidna.core.fill_spectrum module

Provides code for creating echidna spectra and populating with data from RAT Root files/ntuples.

echidna.core.fill_spectrum._bipo_ntuple(spectrum, chain, extractors)

Because ROOT is crap, we have to loop through the entries first

before using the LoadTree() method required for the bipo checks. If the chain is not looped first then all parameters return 0. This function will apply the bipo cuts to a chain from an ntuple and fill a spectrum.

Parameters:

• spectrum (spectra.Spectra) – The spectrum which is being filled.
• chain (ROOT.TChain) – Chain containing the events.
• extractors (dict) – Keys are the variable names and the values are their respective extractors.

Returns:

spectra.Spectra: The filled spectrum.

echidna.core.fill_spectrum._root_ev(spectrum, dsreader, extractors, bipo)

Internal function for filling a spectrum whose config only has

reco paremeters.

Parameters:

• spectrum (spectra.Spectra) – The spectrum which is being filled.
• dsreder (ROOT.RAT.DU.DSReader) – rat’s data structure reader for the root file.
• extractors (dict) – Keys are the variable names and the values are their respective extractors.
• bipo (bool) – Applies the bipo cut if set to True.

echidna.core.fill_spectrum._root_mc(spectrum, dsreader, extractors, bipo)

Internal function for filling a spectrum whose config only has

mc or truth paremeters.

Parameters:

• spectrum (spectra.Spectra) – The spectrum which is being filled.
• dsreder (ROOT.RAT.DU.DSReader) – rat’s data structure reader for the root file.
• extractors (dict) – Keys are the variable names and the values are their respective extractors.
• bipo (bool) – Applies the bipo cut if set to True.

echidna.core.fill_spectrum._root_mix(spectrum, dsreader, extractors, bipo)

Internal function for filling a spectrum whose config has a mixture of

mc (and/or truth) and reco paremeters.

Parameters:

• spectrum (spectra.Spectra) – The spectrum which is being filled.
• dsreder (ROOT.RAT.DU.DSReader) – rat’s data structure reader for the root file.
• extractors (dict) – Keys are the variable names and the values are their respective extractors.
• bipo (bool) – Applies the bipo cut if set to True.

echidna.core.fill_spectrum.fill_from_ntuple(filename, spectrum_name='', config=None, spectrum=None, bipo=False, **kwargs)

This function fills in the ndarray (dimensions specified in the config) with weights. It takes the parameters specified in the config from the events in the ntuple.

Parameters:

• filename (str) – The ntuple to study
• spectrum_name (str, optional) – A name of future spectrum. Not required when appending a spectrum.
• config (SpectraConfig or string, optional) – The config or directory to the config for the spectrum
• spectrum (spectra.Spectra, optional) – Spectrum you wish to append. Not required when creating a new spectrum.
• bipo (bool, optional) – Applies the bipo cut if set to True. Default is False.
• kwargs (dict) – Passed to and checked by the dsextractor.

Raises:

ValueError – If spectrum_name is not set when creating a new spectrum.

Returns:

echidna.core.spectra.Spectra: The filled spectrum.

echidna.core.fill_spectrum.fill_from_root(filename, spectrum_name='', config=None, spectrum=None, bipo=False, **kwargs)

This function fills in the ndarray (dimensions specified in the config) with weights. It takes the parameter specified in the config from the events in the root file.

Parameters:

• filename (str) – A root file to study
• spectrum_name (str, optional) – A name of future spectrum. Not required when appending a spectrum.
• config (SpectraConfig or string, optional) – The config or directory to the config for the spectrum. Not requried when appending a spectrum.
• spectrum (spectra.Spectra, optional) – Spectrum you wish to append. Not required when creating a new spectrum.
• bipo (bool, optional) – Applies the bipo cut if set to True. Default is False.
• kwargs (dict) – Passed to and checked by the dsextractor.

Raises:

• ValueError – If spectrum_name is not set when creating a new spectrum.
• IndexError – Unknown dimension type (not mc, truth or reco).

Returns:

spectra.Spectra: The filled spectrum.

echidna.core.parameter module

Echidna’s parameter module.

Contains Parameter and all classes that inherit from it.

class echidna.core.parameter.FitParameter(name, prior, sigma, low, high, bins, dimension=None, values=None, current_value=None, penalty_term=None, best_fit=None, logscale=None, base=2.718281828459045, logscale_deviation=None)

Bases: echidna.core.parameter.Parameter

Simple data container that holds information for a fit parameter (i.e. a systematic to float).

Warning

The sigma value can be explicitly set as None. This is so that you disable a penalty term for a floating parameter. If a parameter is being floated, but sigma is None, then no penalty term will be added for the parameter.

Note

The FitParameter class offers three different scales for constructing the array of values for the parameter.

These are:

• linear: A standard linear scale is the default option. This creates an array of equally spaced values, starting at low and ending at high (includive). The array will contain bins values.
• logscale: This creates an array of values that are equally spaced in log-space, but increase exponentially in linear-space, starting at low and ending at high (includive). The array will contain bins values.
• logscale_deviation: This creates an array of values - centred around the prior - whose absolute deviations from the prior are equally spaced in log-space, but increase exponentially in linear-space. The values start at low and end at high (includive). The array will contain bins values.

Parameters:

• name (str) – The name of this parameter
• prior (float) – The prior of the parameter
• sigma (float) – The sigma of the parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values
• dimension (string, optional) – The spectral dimension to which the fit parameter applies.
• values (numpy.array, optional) – Array of parameter values to test in fit.
• best_fit (float, optional) – Best-fit value calculated by fit.
• penalty_term (float, optional) – Penalty term value at best fit.
• logscale (bool, optional) – Flag to create an logscale array of values, rather than a linear array.
• base (float, optional) – Base to use when creating an logscale array. Default is base-e.
• logscale_deviation (bool, optional) – Flag to create a logscale deviation array of values rather than a linear or logscale array.

Variables:

• _prior (float) – The prior of the parameter
• _sigma (float) – The sigma of the parameter
• _dimension (string) – The spectral dimension to which the fit parameter applies.
• _values (numpy.array) – Array of parameter values to test in fit.
• _best_fit (float) – Best-fit value calculated by fit.
• _penalty_term (float) – Penalty term value at best fit.
• _logscale (bool) – Flag to create an logscale array of values, rather than a linear array.
• _base (float) – Base to use when creating an logscale array. Default is base-e
• _logscale_deviation (bool) – Flag to create a logscale deviation array of values rather than a linear or logscale array.
• _bin_boundaries (numpy.array) – Array of bin boundaries corresponding to _values.

apply_to(spectrum)

Applies current value of fit parameter to spectrum.

Parameters:spectrum (Spectra) – Spectrum to which current value of parameter should be applied. Returns:(Spectra): Modified spectrum. Raises:ValueError – If _current_value is not set.

check_values()

For symmetric arrays, check that the prior is in the values.

Raises:ValueError – If prior is not in the values array.

get_best_fit()

Returns:Best fit value of parameter - stored in _best_fit. Return type:float Raises:ValueError – If the value of _best_fit has not yet been set.

get_bin_boundaries()

Returns an array of bin boundaries, based on the _low, _high and _bins parameters, and any flags (_logscale or _logscale_deviation) that have been applied.

Returns:(numpy.array): Array of bin_baoundaries for the parameter values stored in _values.

get_current_value()

Returns:Current value of fit parameter - stored in _current_value Return type:float

get_dimension()

Returns:Dimension to which fit parameter is applied. Return type:string

get_penalty_term()

Gets the value of the penalty term at the best fit.

Returns:Penalty term value of parameter at best fit - stored in _penalty_term. Return type:float Raises:ValueError – If the value of _penalty_term has not yet been set.

get_pre_convolved(directory, filename)

Appends the name and current value of a the FitParameter

Note

Before any calls to this function, the base directory should be of the form:

../hyphen-separated-dimensions/spectrum_name/

and a base filename of the form spectrum_name.

Note

Each call to this method, then appends the name of the FitParamter to the directory and its current value to the filename. So for three FitParameters`, after three calls to this method, the directory should be e.g.:

../energy_mc-radial3_mc/Te130_0n2b/syst1/syst2/syst3/

and the filename might be:

Te130_0n2b_250.0_0.012_1.07

Note

To construct the full path to pass to echidna.output.store.load(), the directory and filename returned by the last call to this method, should be added together, and appended with ".hdf5".

path = director + filename + ”.hdf5”

Parameters:

• directory (string) – Current or base directory containing pre-convolved Spectra object
• name (string) – Current or base name of Spectra object

Returns:

Directory containing pre-convolved Spectra,

appended with name of this FitParameter

string: Name of pre-convolved Spectra, appended with

current value of this FitParameter

Return type:

string

Raises:

ValueError – If _current_value is not set.

get_prior()

Returns:Prior value of fit parameter - stored in _prior Return type:float

get_sigma()

Returns:Sigma of fit parameter - stored in _sigma Return type:float

get_value_at(index)

Access the parameter value at a given index in the array.

Parameters:index (int) – Index of parameter value requested. Returns:Parameter value at the given index. Return type:float

get_value_index(value)

Get the index corresponding to a given parameter value.

Parameters:value (float) – Parameter value for which to get corresponding index. Returns:Index of corresponding to the given parameter value. Return type:int

Warning

If there are multiple occurences of value in the array of parameter values, only the index of the first occurence will be returned.

get_values()

Returns an array of values, based on the _low, _high and _bins parameters, and any flags (_logscale or _logscale_deviation) that have been applied.

Warning

Calling this method with the logscale_deviation flag enabled, may alter the value of _low, as this scale must be symmetric about the prior.

Returns:(numpy.array): Array of parameter values to test in fit. Stored in _values.

set_best_fit(best_fit)

Set value for _best_fit.

Parameters:best_fit (float) – Best fit value for parameter

set_current_value(value)

Set value for _current_value.

Parameters:value (float) – Current value of fit parameter

set_par(**kwargs)

Set a fitting parameter’s values after initialisation.

Parameters:kwargs (dict) – keyword arguments

Note

Keyword arguments include:

• prior (float): Value to set the prior to of the parameter
• sigma (float): Value to set the sigma to of the parameter
• low (float): Value to set the lower limit to of the parameter
• high (float): Value to set the higher limit to of the parameter
• bins (float): Value to set the size of the bins between low and high of the parameter
• logscale (bool): Flag to create an logscale array of values, rather than a linear array.
• base (float): Base to use when creating an logscale array.

Raises:TypeError – Unknown variable type passed as a kwarg.

set_penalty_term(penalty_term)

Set value for _penalty_term.

Parameters:penalty_term (float) – Value for penalty term of parameter at best fit.

to_dict(basic=False)

Represent the properties of the parameter in a dictionary.

Parameters:basic (bool, optional) – If True, only the basic properties: prior, sigma, low, high and bins are included.

Note

The attributes _name, _dimension, _values and _logger are never included in the dictionary. For the first two this is because it is expected that the dictionary returned here will usually be used as part of a larger dictionary where dimension and parameter_name are keys. The values attribute is not included because this is a lrge numpy array. The logger is not included as this is for internal use only.

Returns:Representation of the parameter in the form of a dictionary. Return type:dict

class echidna.core.parameter.Parameter(type_name, name, low, high, bins)

Bases: object

The base class for creating parameter classes.

Parameters:

• type_name (string) – The type of the parameter.
• name (str) – The name of this parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values

Variables:

• _type (string) – The type of the parameter.
• _name (str) – The name of this parameter
• _low (float) – The lower limit to float the parameter from
• _high (float) – The higher limit to float the parameter from
• _bins (int) – The number of steps between low and high values

get_bins()

Get the number of bins.

Returns:Number of bins for this parameter. Return type:int

get_high()

Get the high value of the parameter

Returns:The high value of the parameter. Return type:float

get_low()

Get the low value of the parameter.

Returns:The low value the parameter. Return type:float

get_name()

Get the name of the parameter.

Returns:The name of the parameter. Return type:float

get_type()

Get the type of the parameter.

Returns:The type of the parameter. Return type:float

get_width()

Get the width of the binning for the parameter

Returns:Bin width. Return type:float

to_dict(basic=False)

Represent the properties of the parameter in a dictionary.

Note

The attributes _name, _type are never included in the dictionary. This is because it is expected that the dictionary returned here will usually be used as part of a larger dictionary where type and/or parameter_name are keys.

Returns:Representation of the parameter in the form of a dictionary. Return type:dict

class echidna.core.parameter.RateParameter(name, prior, sigma, low, high, bins, logscale=None, base=2.718281828459045, logscale_deviation=None, **kwargs)

Bases: echidna.core.parameter.FitParameter

Data container that holds information for a rate parameter that is included in the fit.

Parameters:

• name (str) – The name of this parameter
• prior (float) – The prior of the parameter
• sigma (float) – The sigma of the parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values
• logscale (bool, optional) – Flag to create an logscale array of values, rather than a linear array.
• base (float, optional) – Base to use when creating an logscale array.
• kwargs (dict) – Other keyword arguments to pass to FitParameter

Variables:

• _logscale (bool) – Flag to create an logscale array of values, rather than a linear array.
• _base (float) – Base to use when creating an logscale array.

apply_to(spectrum)

Scales spectrum to current value of rate parameter.

Parameters:spectrum (Spectra) – Spectrum which should be scaled to current rate value. Returns:(Spectra): Scaled spectrum. Raises:ValueError – If _current_value is not set.

class echidna.core.parameter.ResolutionParameter(name, prior, sigma, low, high, bins, dimension, **kwargs)

Bases: echidna.core.parameter.FitParameter

Data container that holds information for a resulution parameter that is included in the fit.

Parameters:

• name (str) – The name of this parameter
• prior (float) – The prior of the parameter
• sigma (float) – The sigma of the parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values
• dimension (string) – The spectral dimension to which the resolution parameter applies.
• kwargs (dict) – Other keyword arguments to pass to FitParameter

apply_to(spectrum)

Smears spectrum to current value of resolution.

Parameters:spectrum (Spectra) – Spectrum which should be smeared. Returns:(Spectra): Smeared spectrum. Raises:ValueError – If _current_value is not set.

class echidna.core.parameter.ScaleParameter(name, prior, sigma, low, high, bins, dimension, **kwargs)

Bases: echidna.core.parameter.FitParameter

Data container that holds information for a scale parameter that is included in the fit.

Parameters:

• name (str) – The name of this parameter
• prior (float) – The prior of the parameter
• sigma (float) – The sigma of the parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values
• dimension (string) – The spectral dimension to which the scale parameter applies.
• kwargs (dict) – Other keyword arguments to pass to FitParameter

apply_to(spectrum)

Convolves spectrum with current value of scale parameter.

Parameters:spectrum (Spectra) – Spectrum to be convolved. Returns:(Spectra): Convolved spectrum. Raises:ValueError – If _current_value is not set.

class echidna.core.parameter.ShiftParameter(name, prior, sigma, low, high, bins, dimension, **kwargs)

Bases: echidna.core.parameter.FitParameter

Data container that holds information for a shift parameter that is included in the fit.

Parameters:

• name (str) – The name of this parameter
• prior (float) – The prior of the parameter
• sigma (float) – The sigma of the parameter
• low (float) – The lower limit to float the parameter from
• high (float) – The higher limit to float the parameter from
• bins (int) – The number of steps between low and high values
• dimension (string) – The spectral dimension to which the shift parameter applies.
• kwargs (dict) – Other keyword arguments to pass to FitParameter

apply_to(spectrum)

Convolves spectrum with current value of shift parameter.

Parameters:spectrum (Spectra) – Spectrum to be convolved. Returns:(Spectra): Convolved spectrum. Raises:ValueError – If _current_value is not set.

class echidna.core.parameter.SpectraParameter(name, low, high, bins)

Bases: echidna.core.parameter.Parameter

Simple data container that holds information for a Spectra parameter (i.e. axis of the spectrum).

Parameters:

• name (str) – The name of this parameter
• low (float) – The lower limit of this parameter
• high (float) – The upper limit of this parameter
• bins (int) – The number of bins for this parameter

get_bin(x)

Gets the bin index which contains value x.

Parameters:

x (float) – Value you wish to find the bin index for.

Raises:

• ValueError – If x is less than parameter lower bounds
• ValueError – If x is more than parameter upper bounds

Returns:

Bin index

Return type:

int

get_bin_boundaries()

Returns the bin boundaries for the parameter

Returns:numpy.ndarray: Bin boundaries for the parameter.

get_bin_centre(bin)

Calculates the central value of a given bin

Parameters:

bin (int) – Bin number.

Raises:

• TypeError – If bin is not int
• ValueError – If bin is less than zero
• ValueError – If bin is greater than the number of bins - 1

Returns:

value of bin centre

Return type:

float

get_bin_centres()

Returns the bin centres of the parameter

Returns:numpy.ndarray: Bin centres of parameter.

get_unit()

Get the default unit for a given parameter

Raises:Exception – Unknown parameter. Returns:Unit of the parameter Return type:string

round(x)

Round the value to nearest bin edge

Parameters:x (float) – Value to round. Returns:The value of the closest bin edge to x Return type:float

set_par(**kwargs)

Set a limit / binning parameter after initialisation.

Parameters:kwargs (dict) – keyword arguments

Note

Keyword arguments include:

• low (float): Value to set the lower limit to of the parameter
• high (float): Value to set the higher limit to of the parameter
• bins (int): Value to set the number of bins of the parameter

Raises:TypeError – Unknown variable type passed as a kwarg.

echidna.core.scale module

class echidna.core.scale.Scale

Bases: object

A class for scaling the parameter space of a spectra.

Variables:_scale_factor (float) – The factor you want to scale a parameter by.

get_scale_factor()

Returns the scale factor.

Returns:The scale factor. Return type:float

scale(spectrum, dimension, **kwargs)

Scales a given spectrum’s dimension.

Parameters:

• spectrum (float) – The spectrum you want to scale.
• dimension (string) – The dimension of the spectrum you want to scale.
• kwargs (dict) – To be passed to spectra.Spectra.interpolate1d().

Returns:

spectra.Spectra: The scaled spectrum.

set_scale_factor(scale_factor)

Sets the scale factor.

Args:

scale_factor (float): Value you wish to set the scale factor to.

Raises:ValueError – If scale_factor is zero or below.

echidna.core.shift module

class echidna.core.shift.Shift

Bases: object

A class for shifting the parameter space of a spectra.

Variables:_shift (float) – The factor you want to shift a parameter by.

get_shift()

Returns the shift factor.

Returns:The shift factor. Return type:float

set_shift(shift)

Sets the shift factor.

Parameters:shift (float) – Value you wish to set the shift factor to.

shift(spectrum, dimension, **kwargs)

Shifts a given spectrum’s dimension using interpolation.

Parameters:

• spectrum (float) – The spectrum you want to shift.
• dimension (string) – The dimension of the spectrum you want to shift.
• kwargs (dict) – To passed to spectra.Spectra.interpolation1d()

Returns:

spectra.Spectra: The shifted spectrum.

shift_by_bin(spectrum, dimension)

Shifts a given spectrum’s dimension by shifting bins.

Parameters:

• spectrum (float) – The spectrum you want to shift.
• dimension (string) – The dimension of the spectrum you want to shift.
• kwargs (dict) – To passed to spectra.Spectra.interpolation1d()

Returns:

spectra.Spectra: The shifted spectrum.

echidna.core.smear module

Examples

To smear an already smeared spectrum with a light yield of 200 to a a light yield of 190 then the following lines are required:

>>> smearer = smear.SmearEnergySmearLY()
>>> ly = smearer.calc_smear_ly(190., cur_ly=200.)
>>> smearer.set_resolution(ly)
>>> smeared_spec = smearer.weighted_smear(spectrum)

Note

Similar methods are available in all other smearing classes.

class echidna.core.smear.EnergySmearLY(poisson=True)

Bases: echidna.core.smear.Smear

The class which smears energy. It accepts resolution in terms of light

yield (LY) in units of NHit per MeV.

Parameters:

poisson (bool) – If True, use poisson smearing.

Variables:

• _light_yield (float) – The light yield of the scintillator in NHits per MeV.
• _poisson_smear (Bool) – True if poisson smearing is to be applied. False if gaussian smearing is to be applied.

calc_poisson_energy(x, lamb)

Calculates the value of a poisson whose integral is equal to one at position x with a given lambda value.

Parameters:

• x – Number of events
• lamb – Lambda of the poisson

Returns:

The value of the poisson at the given position

Return type:

float

calc_smear_ly(new_ly, cur_ly=None)

Calculates the value of light yield (ly) required to smear a

data set which has already been smeared with a light yield of cur_ly to achieve a smeared data set with a new light yield of new_ly.

Parameters:

• new_ly (float) – The value of light yield wanted for the smeared PDF.
• cur_ly (float, optional) – Current value of light yield the PDF has been convolved with from the true value PDF.

Raises:

ValueError – If new_ly is smaller than cur_sigma. Can’t smear to higher light yields (smaller sigmas)

Returns:

The value of light yield needed to smear the current PDF to obtain a new light yield: new_ly.

Return type:

float

get_resolution()

Returns the light yield.

Returns:The light yield. Return type:float

get_sigma(energy)

Calculates sigma at a given energy.

Parameters:energy (float) – Energy value of data point(s) Returns:Sigma equivalent to sqrt(energy/_light_yield) Return type:float

random_smear(spectrum, par='energy_mc')

Smears the energy of a spectra.Spectra by generating a number of random points from Gaussian PDF generated from that bins mean value and the corresponding sigma. The number of points generated is equivalent to the number of entries in that bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is energy_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

set_resolution(light_yield)

Sets the light yield

Parameters:light_yield (float) – The value you wish to set the light yield to. Raises:ValueError – If the light yield is zero or negative.

weighted_smear(spectrum, par='energy_mc')

Smears the energy of a spectra.Spectra by calculating a Gaussian PDF for each bin. Weights are then applied to a window of width specified by the number of sigma depending on the value of the Gaussian PDF at the mean of the bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is energy_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

class echidna.core.smear.EnergySmearRes(poisson=True)

Bases: echidna.core.smear.Smear

Allows you to smear directly by supplied energy resolution

(in \(\sqrt{MeV}\)).

Inherits from Smear

Parameters:

poisson (bool) – If True, use poisson smearing.

Variables:

• _energy_resolution (float) – Energy resolution in \(\sqrt{MeV}\) e.g. 0.05 for \(\sigma = 5\%/\sqrt{E[MeV]}\).
• _poisson_smear (Bool) – True if poisson smearing is to be applied. False if gaussian smearing is to be applied.

calc_poisson_energy(x, lamb)

Calculates the value of a poisson whose integral is equal to one at position x with a given lambda value.

Parameters:

• x – Number of events
• lamb – Lambda of the poisson

Returns:

The value of the poisson at the given position

Return type:

float

calc_smear_resoluton(new_res, cur_res=None)

Calculates the value of resolution required to smear a data set

which has already been smeared with a resolution of cur_res to achieve a new resolution of new_res.

Parameters:

• new_res (float) – The value of resolution wanted for the smeared PDF.
• cur_res (float, optional) – Current value of resolution the PDF has been convolved with from the true value PDF.

Raises:

ValueError – If new_res is smaller than cur_sigma. Can’t smear to higher resolutions (smaller sigmas)

Returns:

The value of resolution needed to smear the current PDF to obtain a new resolution with sigma value new_res.

Return type:

float

get_resolution()

Get the energy resolution

Returns:Energy resolution in \(\sqrt{MeV}\) e.g. 0.05 for \(\sigma = 5\%/\sqrt{E[MeV]}\) Return type:float

get_sigma(energy)

Calculates sigma at a given energy.

Parameters:energy (float) – Energy value of data point(s) Returns:Sigma (MeV) equivalent to energy_resolution * \(\sqrt{energy}\) Return type:float

random_smear(spectrum, par='energy_mc')

Smears the energy of a spectra.Spectra by generating a number of random points from Gaussian PDF generated from that bins mean value and the corresponding sigma. The number of points generated is equivalent to the number of entries in that bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is energy_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

set_resolution(resolution)

Set the energy resolution in \(\sqrt{MeV}\) e.g. 0.05 for \(\sigma = 5\%/\sqrt{E[MeV]}\).

Parameters:resolution (float) – Energy resolution in \(\sqrt{MeV}\) e.g. 0.05 for \(\sigma = 5\%/\sqrt{E[MeV]}\). Raises:ValueError – If the resolution is not between 0 and 1.

weighted_smear(spectrum, par='energy_mc')

Smears the energy of a spectra.Spectra by calculating a Gaussian PDF for each bin. Weights are then applied to a window of width specified by the number of sigma depending on the value of the Gaussian PDF at the mean of the bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is energy_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

class echidna.core.smear.RadialSmear

Bases: echidna.core.smear.Smear

The class which smears the radius. It accepts resolution in terms of

sigma in units of mm.

Parameters:

poisson (bool) – If True, use poisson smearing.

Variables:

• _resolution (float) – The position resolution (mm).
• _poisson_smear (Bool) – True if poisson smearing is to be applied. False if gaussian smearing is to be applied.

calc_smear_resoluton(new_res, cur_res=None)

Calculates the value of resolution required to smear a data set

which has already been smeared with a resolution of cur_res to achieve a new resolution of new_res.

Parameters:

• new_res (float) – The value of resolution wanted for the smeared PDF.
• cur_res (float, optional) – Current value of resolution the PDF has been convolved with from the true value PDF.

Raises:

ValueError – If new_res is smaller than cur_sigma. Can’t smear to higher resolutions (smaller sigmas)

Returns:

The value of resolution needed to smear the current PDF to obtain a new resolution: new_res.

Return type:

float

get_resolution()

Gets the position resolution.

Returns:Position resolution. Return type:float

get_sigma()

Sigma and resolution are equivalent for radial dimensions currently. This function calls self.get_resolution()

Returns:Sigma in mm equivalent to resolution Return type:float

random_smear(spectrum, par='radial_mc')

Smears the radius of a spectra.Spectra by generating a number of random points from Gaussian PDF generated from that bins mean value and the corresponding sigma. The number of points generated is equivalent to the number of entries in that bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is radial_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

set_resolution(resolution)

Sets the position resolution:

Raises:ValueError – If resolution is zero or less. Parameters:resolution (float) – Position resolution in mm.

weighted_smear(spectrum, par='radial_mc')

Smears the radius of a spectra.Spectra by calculating a Gaussian PDF for each bin. Weights are then applied to a window of width specified by the number of sigma depending on the value of the Gaussian PDF at the mean of the bin.

Parameters:

• spectrum (spectra.Spectra) – Spectrum you wish to smear.
• par (string, optional) – The name of the parameter you wish to smear. The default is radial_mc.

Raises:

IndexError – If par is not in the specta config.

Returns:

spectra.Spectra: The smeared spectrum

class echidna.core.smear.Smear(name)

Bases: object

The base class for smearing spectra.

Parameters:

name (string) – The name of the smearing class.

Variables:

• _name (string) – name of the smeaing class.
• _num_sigma (float) – The width of the window in terms of number of sigma you wish to apply weights to.

calc_gaussian(x, mean, sigma)

Calculates the value of a gaussian whose integral is equal to one at position x with a given mean and sigma.

Parameters:

• x – Position to calculate the gaussian
• mean – Mean of the gaussian
• sigma – Sigma of the gaussian

Returns:

Value of the gaussian at the given position

Return type:

float

get_bin_mean(low, bin, width)

Calculates the mean value of a bin.

Parameters:

• low (float) – The lower bound value of the parameter.
• bin (int) – The number of the bin you wish to calculate the mean of.
• width (float) – The width of the bin.

Returns:

The mean value of the bin.

Return type:

float

get_bounds(mean, sigma)

Calculates the boundaries you wish to apply the smearing

weights to.

Parameters:

• mean (float) – The mean value you are smearing.
• sigma (float) – The sigma of the gaussian you are using to smear.

Returns:

First value of the tuple is the lower bound. The second is the upper bound.

Return type:

tuple

get_num_sigma()

Returns the width of the window in terms of number of sigma

you wish to apply weights to.

Returns:The number of sigma. Return type:float

set_num_sigma(num_sigma)

Sets the width of the window in terms of number of sigma

you wish to apply weights to.

Parameters:num_sigma (float) – The number of sigma you wish to apply weights to. Raises:ValueError – If the number of sigma is zero or negative.

echidna.core.spectra module

class echidna.core.spectra.Spectra(name, num_decays, spectra_config, fit_config=None)

Bases: object

This class contains a spectra as a function of energy, radius and time.

The spectra is stored as histogram binned in energy, x, radius, y, and time, z. This histogram can be flattened to 2d (energy, radius) or 1d (energy).

Parameters:

• name (str) – The name of this spectra
• num_decays (float) – The number of decays this spectra is created to represent.
• spectra_config (SpectraConfig) – The configuration object

Variables:

• _data (numpy.ndarray) – The histogram of data
• _name (str) – The name of this spectra
• _config (SpectraConfig) – The configuration object
• _num_decays (float) – The number of decays this spectra currently represents.
• _raw_events (int) – The number of raw events used to generate the spectra. Increments by one with each fill independent of weight.
• _bipo (int) – Flag to indicate whether the bipo cut was applied to the spectra. 0 is No Cut. 1 is Cut. Int type as HDF5 does not support bool.
• _style (string) – Pyplot-style plotting style e.g. “b-” or {“color”: “blue”}.
• _rois (dict) – Dictionary containing the details of any ROI, along any axis, which has been defined.

add(spectrum)

Adds a spectrum to current spectra object.

Parameters:

spectrum (Spectra) – Spectrum to add.

Raises:

• ValueError – spectrum has different dimenstions to the current spectra.
• IndexError – spectrum does not contain a dimension(s) that is in the current spectra config.
• IndexError – The current spectra does not contain a dimension(s) that is in the spectrum config.
• ValueError – The upper bounds of a parameter in the current spectra and spectra are not equal.
• ValueError – The lower bounds of a parameter in the current spectra and spectra are not equal.
• ValueError – The number of bins of a parameter in the current spectra and spectra are not equal.

cut(**kwargs)

Similar to shrink(), but updates scaling information.

If a spectrum is cut using shrink(), subsequent calls to scale() the spectrum must still scale the full spectrum i.e. before any cuts. The user supplies the number of decays the full spectrum should now represent.

However, sometimes it is more useful to be able specify the number of events the revised spectrum should represent. This method updates the scaling information, so that it becomes the new full spectrum.

Parameters:kwargs (float) – Named parameters to slice on; note that these must be of the form [name]_low or [name]_high where [name] is a dimension present in the SpectraConfig.

fill(weight=1.0, **kwargs)

Fill the bin with weight. Note that values for all named parameters in the spectra’s config (e.g. energy, radial) must be passed.

Parameters:

• weight (float, optional) – Defaults to 1.0, weight to fill the bin with.
• kwargs (float) – Named values (e.g. for energy_mc, radial_mc)

Raises:

• Exception – Parameter in kwargs is not in config.
• Exception – Parameter in config is not in kwargs.
• ValueError – If the energy, radius or time is beyond the bin limits.

get_bipo()

Get the BiPo flag value of the spectra (no BiPo cut = 0, BiPo cut = 1)

Returns:The BiPo flag value of the spectra. Return type:int

get_config()

Get the config of the spectra.

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

get_data()

Returns:(numpy.ndarray): The spectral data.

get_fit_config()

Get the config of the spectra.

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

get_name()

Returns:The name of the spectra. Return type:string

get_num_decays()

Returns:The number of decays the spectrum represents (copy). Return type:float

get_roi(dimension)

Access information about a predefined ROI for a given dimension

Returns:Dictionary containing parameters defining the ROI, on the given dimension. Return type:dict

get_style()

Returns:string/dict: _style - pyplot-style plotting style.

interpolate1d(dimension, kind='cubic')

Interpolates a given dimension of a spectra.

Parameters:

• dimension (string) – Dimension you want to interpolate.
• kind (string) – Method of interpolation. See scipy.interpolate.interp1d for available methods.

Returns:

scipy.interpolate.interp1d: Interpolation function.

nd_project(dimensions)

Project the histogram along an arbitary number of axes.

Parameters:dimensions (str) – List of axes to project onto Returns:numpy.ndarray: The nd projection of the histogram.

project(dimension)

Project the histogram along an axis for a given dimension. Note that the dimension must be one of the named parameters in the SpectraConfig.

Parameters:dimension (str) – parameter to project onto Returns:numpy.ndarray: The projection of the histogram onto the given axis

rebin(new_bins)

Rebin spectra data into a smaller spectra of the same rank whose dimensions are factors of the original dimensions.

Parameters:

new_bins (tuple) – new binning, this must match both the number and ordering of dimensions in the spectra config. For example if the old data shape is made of bins (1000, 10) and you would like to increase the bin width of both by 2 then you must pass the tuple (500, 5)

Raises:

• ValueError – Shape mismatch. Number of dimenesions are different.
• ValueError – Old bins/ New bins must be integer

scale(num_decays)

Scale THIS spectra to represent num_decays worth of decays over the entire unshrunken spectra.

This rescales each bin by the ratio of num_decays to self._num_decays, i.e. it changes the spectra from representing self._num_decays to num_decays. self._num_decays is updated to equal num_decays after.

Parameters:num_decays (float) – Number of decays this spectra should represent.

set_fit_config(config)

Get the config of the spectra.

Parameters:config (echidna.core.spectra.SpectraFitConfig) – The fit config to assign to the spectra.

set_style(style)

Sets plotting style.

Styles should be valid pyplot style strings e.g. “b-”, for a blue line, or dictionaries of strings e.g. {“color”: “red”}.

Parameters:style (string, dict) – Pyplot-style plotting style.

shrink(**kwargs)

Shrink the data such that it only contains values between low and high for a given dimension by slicing. This updates the internal bin information as well as the data.

Parameters:kwargs (float) – Named parameters to slice on; note that these must be of the form [name]_low or [name]_high where [name] is a dimension present in the SpectraConfig.

Raises:

• IndexError – Parameter which is being shrank does not exist in the config file.
• ValueError – [parameter]_low value is lower than the parameters lower bound.
• ValueError – [parameter]_high value is lower than the parameters higher bound.
• IndexError – Suffix to [parameter] is not _high or _low.

shrink_to_roi(lower_limit, upper_limit, dimension)

Shrink spectrum to a defined Region of Interest (ROI)

Shrinks spectrum to given ROI and saves ROI parameters.

Parameters:

• lower_limit (float) – Lower bound of ROI, along given axis.
• upper_limit (float) – Upper bound of ROI, along given axis.
• dimension (str) – Name of the dimension to shrink.

sum()

Calculate and return the sum of the _data values.

Returns:The sum of the values in the _data histogram. Return type:float

surface(dimension1, dimension2)

Project the histogram along two axes for the given dimensions. Note that the dimensions must be one of the named parameters in the SpectraConfig.

Parameters:

• dimension1 (str) – first parameter to project onto
• dimension1 – second parameter to project onto

Raises:

• IndexError – Axis of dimension1 is out of range
• IndexError – Axis of dimension2 is out of range

Returns:

numpy.ndarray: The 2d surface of the histogram.

Module contents