skyllh.core package

Subpackages

skyllh.core.minimizers package
- Submodules
- skyllh.core.minimizers.iminuit module
  - FuncWithGradsFunctor
    - FuncWithGradsFunctor.get_f()
    - FuncWithGradsFunctor.get_grads()
  - IMinuitMinimizerImpl
skyllh.core.utils package

Submodules

skyllh.core.analysis module

The analysis module provides classes for pre-defined analyses.

class skyllh.core.analysis.Analysis(shg_mgr, pmm, test_statistic, bkg_generator_cls=None, sig_generator_cls=None, **kwargs)

Bases: HasConfig

This is the abstract base class for all analysis classes. It contains common properties required by all analyses and defines the overall analysis interface how to setup and run an analysis.

Constructor of the analysis base class.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal yield implementation method.
pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance managing the global set of parameters and their relation to individual models, e.g. sources.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_generator_cls (class of MultiDatasetBackgroundGenerator | None) – The background generator class used to create the background generator instance for multiple datasets. If set to None, the skyllh.core.background_generator.MultiDatasetBackgroundGenerator class is used.
sig_generator_cls (class of MultiDatasetSignalGenerator | None) – The signal generator class used to create the signal generator instance for multiple datasets. If set to None, the MultiDatasetSignalGenerator class is used.

property shg_mgr: The SourceHypoGroupManager instance, which defines the groups of source hypothesis, their flux model, and their detector signal yield implementation method.

property pmm: The ParameterModelMapper instance that manages the global set of parameters and their relation to individual models, e.g. sources.

property test_statistic: The TestStatistic instance that defines the test-statistic function of the analysis.

property bkg_generator_list: (read-only) The list of instance of BackgroundGenerator, one for each dataset.

property bkg_generator_cls: The background generator class that should be used to construct the background generator instance.

property dataset_list: The list of Dataset instances.

property data_list: The list of DatasetData instances holding the original data of the dataset.

property n_datasets: (read-only) The number of datasets used in this analysis.

property bkg_generator: (read-only) The background generator instance. Is None of the background generator has not been constructed via the construct_background_generator method.

property detsigyield_service: The instance of DetSigYieldService for the analysis.

property src_detsigyield_weights_service: The instance of SrcDetSigYieldWeightsService for the analysis.

property ds_sig_weight_factors_service: The instance of DatasetSignalWeightFactorsService for the analysis.

property sig_generator_list: (read-only) The list of instance of SignalGenerator, one for each dataset.

property sig_generator_cls: The signal generator class that should be used to construct the signal generator instance handling all datasets.

property sig_generator: (read-only) The signal generator instance. Is None if the signal generator has not been constructed via the construct_signal_generator method.

property tdm_list: The list of instance of TrialDataManager. One for each dataset.

property total_livetime: (read-only) The total live-time in days of the loaded data.

construct_services(ppbar=None)

Constructs the following services:

detector signal yield service

source detector signal yield weights service

dataset signal weight factors service

Parameters:: ppbar (instance of ProgressBar | None) – The instance of ProgressBar of the optional parent progress bar.

add_dataset(dataset, data, tdm=None, event_selection_method=None, bkg_generator=None, sig_generator=None)

Adds the given dataset to the list of datasets for this analysis.

Parameters:

dataset (instance of Dataset) – The Dataset instance that should get added.
data (instance of DatasetData) – The DatasetData instance holding the original (prepared) data of the dataset.
tdm (instance of TrialDataManager | None) – The TrialDataManager instance managing the trial data and additional data fields of the data set. If set to None, it means that no additional data fields are defined.
event_selection_method (instance of EventSelectionMethod | None) – The instance of EventSelectionMethod to use to select only signal-like events from the data. All other events will be treated as pure background events. This reduces the amount of log-likelihood-ratio function evaluations. If set to None, all events will be evaluated.
bkg_generator (instance of BackgroundGenerator | None) – The optional instance of BackgroundGenerator, which should be used to generate background events for this particular dataset.
sig_generator (instance of SignalGenerator | None) – The optional instance of SignalGenerator, which should be used to generate signal events for this particular dataset.

get_livetime(dataset_key=None, unit=None)

Retrieves the numeric livetime of the given dataset in the specified unit. The dataset can be specified either through its index or its name. If no dataset is specified, the total livetime, i.e. the sum of the livetime of all datasets, is returned.

Parameters:

dataset_key (int | str | None) – The index or name of the dataset for which the livetime should get retrieved. If set to None, the total livetime of all datasets will be returned.
unit (instance of astropy.units.Unit | None) – The time unit in which the livetime should be returned. If set to None, astropy.units.day will be used.

calculate_test_statistic(log_lambda, fitparam_values, **kwargs)

Calculates the test statistic value by calling the evaluate method of the TestStatistic class with the given log_lambda value and fit parameter values.

Parameters:

log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D ndarray holding the global fit parameter values of the log-likelihood ratio function for the given log_lambda value.
**kwargs – Any additional keyword arguments are passed to the __call__ method of the TestStatistic instance.

Returns:

TS (float) – The calculated test-statistic value.

construct_background_generator(**kwargs): Constructs the background generator for all added datasets. This method must be called after all the datasets were added via the add_dataset method. It sets the bkg_generator property of this Analysis class instance.

construct_signal_generator(**kwargs): Constructs the signal generator for all added datasets. This method must be called after all the datasets were added via the add_dataset method. It sets the sig_generator property of this Analysis class instance. The signal generation method has to be set through the source hypothesis group.

abstract initialize_trial(events_list, n_events_list=None)

This method is supposed to initialize the log-likelihood ratio function with a new set of given trial data. This is a low-level method. For convenient methods see the unblind and do_trial methods.

Parameters:

events_list (list of numpy record ndarray) – The list of data events to use for the log-likelihood function evaluation. The data arrays for the datasets must be in the same order than the added datasets.
n_events_list (list of int | None) – The list of the number of events of each data set. These numbers can be larger than the number of events given by the events_list argument in cases where an event selection method was already used. If set to None, the number of events is taken from the given events_list argument.

abstract unblind(rss, tl=None)

This method is supposed to run the analysis on the experimental data, i.e. unblinds the data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used draw random numbers from. It can be used to generate random initial values for fit parameters.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time the maximization of the LLH ratio function.

Returns:

TS (float) – The test-statistic value.
global_params_dict (dict) – The dictionary holding the global parameter names and their best fit values. It includes fixed and floating parameters.
status (dict) – The status dictionary with information about the performed minimization process of the analysis.

abstract do_trial_with_given_pseudo_data(rss, mean_n_sig, n_sig, n_events_list, events_list, minimizer_status_dict=None, tl=None, **kwargs)

This method is supposed to perform an analysis trial on a given pseudo data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to use for generating random numbers.
mean_n_sig (float) – The mean number of signal events the pseudo data was generated with.
n_sig (int) – The total number of actual signal events in the pseudo data.
n_events_list (list of int) – The total number of events for each data set of the pseudo data.
events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray containing the pseudo data events for each data sample. The number of events for each data sample can be less than the number of events given by n_events_list if an event selection method was already utilized when generating background events.
minimizer_status_dict (dict | None) – If a dictionary is provided, it will be updated with the minimizer status dictionary.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks.

Returns:

recarray (instance of numpy record ndarray) – The numpy record ndarray holding the result of the trial. It must contain the following data fields:

rss_seedint: The RandomStateService seed.
mean_n_sigfloat: The mean number of signal events.
n_sigint: The actual number of injected signal events.
tsfloat: The test-statistic value.
[<global_param_name>float ]: Any additional parameters of the analysis.

change_shg_mgr(shg_mgr)

If the SourceHypoGroupManager instance changed, this method needs to be called to propagate the change to all components of the analysis.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

do_trial_with_given_bkg_and_sig_pseudo_data(rss, mean_n_sig, n_sig, n_bkg_events_list, n_sig_events_list, bkg_events_list, sig_events_list, minimizer_status_dict=None, tl=None, **kwargs)

Performs an analysis trial on the given background and signal pseudo data. This method merges the background and signal pseudo events and calls the do_trial_with_given_pseudo_data method of this class.

Note

This method alters the DataFieldRecordArray instances of the bkg_events_list argument!

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService instance to use for generating random numbers.
mean_n_sig (float) – The mean number of signal events the pseudo data was generated with.
n_sig (int) – The total number of actual signal events in the pseudo data.
n_bkg_events_list (list of int) – The total number of background events for each data set of the pseudo data.
n_sig_events_list (list of int) – The total number of signal events for each data set of the pseudo data.
bkg_events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray containing the background pseudo data events for each data set.
sig_events_list (list of instance of DataFieldRecordArray | None) – The list of instance of DataFieldRecordArray containing the signal pseudo data events for each data set. If a particular dataset has no signal events, the entry for that dataset can be None.
minimizer_status_dict (dict | None) – If a dictionary is provided, it will be updated with the minimizer status dictionary.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to time individual tasks.
**kwargs (dict) – Additional keyword arguments are passed to the do_trial_with_given_pseudo_data() method.

Returns:

recarray (instance of numpy record ndarray) – The numpy record ndarray holding the result of the trial. See the documentation of the do_trial_with_given_pseudo_data() method for further information.

generate_background_events(rss, mean_n_bkg_list=None, bkg_kwargs=None, tl=None)

Generates background events utilizing the background generator.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to use for generating random numbers.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. If set to None (the default), the background generation method needs to obtain this number itself.
bkg_kwargs (dict | None) – Optional keyword arguments for the generate_background_events method of the background generator.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks of this method.

Returns:

n_events_list (list of int) – The list of the number of events that have been generated for each pseudo data set.
events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray containing the pseudo data events for each data sample. The number of events for each data set can be less than the number of events given by n_events_list if an event selection method was already utilized when generating background events.

generate_signal_events(rss, mean_n_sig, sig_kwargs=None, n_events_list=None, events_list=None, tl=None)

Generates signal events utilizing the signal generator.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to use for generating random numbers.
mean_n_sig (float) – The mean number of signal events that should be generated for the trial. The actual number of generated events will be drawn from a Poisson distribution with this given signal mean as mean.
sig_kwargs (dict | None) – Additional keyword arguments for the generate_signal_events method of the sig_generator_cls class. An usual keyword argument is poisson.
n_events_list (list of int | None) – If given, it specifies the number of events of each data set already present and the number of signal events will be added.
events_list (list of instance of DataFieldRecordArray | None) – If given, it specifies the events of each data set already present and the signal events will be added.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to time individual tasks of this method.

Returns:

n_sig (int) – The actual number of injected signal events.
n_events_list (list of int) – The list of the number of signal events that have been generated for each data set.
events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray containing the signal data events for each data set. An entry is None, if no signal events were generated for this particular data set.

generate_pseudo_data(rss, mean_n_bkg_list=None, mean_n_sig=0, bkg_kwargs=None, sig_kwargs=None, tl=None)

Generates pseudo data with background and possible signal events for each data set using the background and signal generation methods of the analysis.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to use for generating random numbers.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. If set to None (the default), the background generation method needs to obtain this number itself.
mean_n_sig (float) – The mean number of signal events that should be generated for the trial. The actual number of generated events will be drawn from a Poisson distribution with this given signal mean as mean.
bkg_kwargs (dict | None) – Additional keyword arguments for the generate_events method of the background generation method class. An usual keyword argument is poisson.
sig_kwargs (dict | None) – Additional keyword arguments for the generate_signal_events method of the SignalGenerator class. An usual keyword argument is poisson.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks of this method.

Returns:

n_sig (int) – The actual number of injected signal events.
n_events_list (list of int) – The list of the number of events that have been generated for each pseudo data set.
events_list (list of instance of DataFieldRecordArray) – The list of DataFieldRecordArray instances containing the pseudo data events for each data sample. The number of events for each data set can be less than the number of events given by n_events_list if an event selection method was already utilized when generating background events.

do_trial(rss, mean_n_bkg_list=None, mean_n_sig=0, bkg_kwargs=None, sig_kwargs=None, minimizer_status_dict=None, tl=None, **kwargs)

This method performs an analysis trial by generating a pseudo data sample with background events and possible signal events via the generate_pseudo_data() method, and performs the analysis on that random pseudo data sample by calling the do_trial_with_given_pseudo_data() method.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService instance to use for generating random numbers.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. If set to None (the default), the background generation method needs to obtain this number itself.
mean_n_sig (float) – The mean number of signal events that should be generated for the trial.
bkg_kwargs (dict | None) – Additional keyword arguments for the generate_events method of the background generation method class. An usual keyword argument is poisson.
sig_kwargs (dict | None) – Additional keyword arguments for the generate_signal_events method of the SignalGenerator class. An usual keyword argument is poisson.
minimizer_status_dict (dict | None) – If a dictionary is provided, it will be updated with the minimizer status dictionary.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks.
**kwargs (dict) – Additional keyword arguments are passed to the do_trial_with_given_pseudo_data() method.

Returns:

recarray (instance of numpy record ndarray) – The numpy record ndarray holding the result of the trial. See the documentation of the do_trial_with_given_pseudo_data() method for further information.

do_trials(rss, n, ncpu=None, tl=None, ppbar=None, **kwargs)

Executes the do_trial() method n times with possible multi-processing.

Parameters:

rss (instance of RandomStateService) – The RandomStateService instance to use for generating random numbers.
n (int) – Number of trials to generate using the do_trial method.
ncpu (int | None) – The number of CPUs to use, i.e. the number of subprocesses to spawn. If set to None, the global setting will be used.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.
**kwargs – Additional keyword arguments are passed to the do_trial() method. See the documentation of that method for allowed keyword arguments.

Returns:

recarray (numpy record ndarray) – The numpy record ndarray holding the result of all trials. See the documentation of the do_trial() method for the list of data fields.

class skyllh.core.analysis.LLHRatioAnalysis(shg_mgr, pmm, test_statistic, bkg_generator_cls=None, sig_generator_cls=None, **kwargs)

Bases: Analysis

This is the abstract base class for all log-likelihood ratio analysis classes. It requires a mathematical log-likelihood ratio function.

To set-up and run an analysis the following procedure applies:

Create an Analysis instance.

Add the datasets and their PDF ratio instances via the skyllh.core.analysis.Analysis.add_dataset() method.

Construct the log-likelihood ratio function via the construct_llhratio() method.

Initialize a trial via the initialize_trial() method.

Fit the global fit parameters to the trial data via the maximize() method of the llhratio property.

Alternatively, one can use the convenient methods do_trial() or unblind() to perform a random trial or to unblind the data, respectively. Both methods will fit the global fit parameters using the set up data. Finally, the test statistic is calculated via the calculate_test_statistic() method.

In order to calculate sensitivities and discovery potentials, analysis trials have to be performed on random data samples with injected signal events. To perform a trial with injected signal events, the signal generator has to be constructed via the construct_signal_generator() method before any random trial data can be generated.

Constructs a new instance of LLHRatioAnalysis.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal yield implementation method.
pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance managing the global set of parameters and their relation to individual models, e.g. sources.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_generator_cls (class of BackgroundGeneratorBase | None) – The background generator class used to create the background generator instance. If set to None, the skyllh.core.background_generator.BackgroundGenerator class is used.
sig_generator_cls (class of SignalGenerator | None) – The signal generator class used to create the signal generator instance. If set to None, the MultiDatasetSignalGenerator class is used.

property llhratio: The log-likelihood ratio function instance. It is None, if it has not been constructed yet.

abstract construct_llhratio(minimizer, ppbar=None)

This method is supposed to construct the LLH ratio function.

Returns:: llhratio (instance of LLHRatio) – The instance of LLHRatio that implements the log-likelihood-ratio function of this LLH ratio analysis.

add_dataset(dataset, data, pdfratio, tdm=None, event_selection_method=None, bkg_generator=None, sig_generator=None)

Adds a dataset with its PDF ratio instances to the analysis.

Parameters:

dataset (instance of Dataset) – The instance of Dataset that should get added.
data (instance of DatasetData) – The instance of DatasetData holding the original (prepared) data of the dataset.
pdfratio (instance of PDFRatio) – The instance of PDFRatio for the to-be-added data set.
tdm (instance of TrialDataManager | None) – The TrialDataManager instance that manages the trial data and additional data fields for this data set.
event_selection_method (instance of EventSelectionMethod | None) – The instance of EventSelectionMethod to use to select only signal-like events from the trial data. All other events will be treated as pure background events. This reduces the amount of log-likelihood-ratio function evaluations. If set to None, all events will be evaluated.
bkg_generator (instance of BackgroundGenerator | None) – The optional instance of BackgroundGenerator, which should be used to generate background events for this particular dataset.
sig_generator (instance of SignalGenerator | None) – The optional instance of SignalGenerator, which should be used to generate signal events for this particular dataset.

change_shg_mgr(shg_mgr)

If the SourceHypoGroupManager instance changed, this method needs to be called to propagate the change to all components of the analysis.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

initialize_trial(events_list, n_events_list=None, tl=None)

This method initializes the log-likelihood ratio function with a new set of given trial data. This is a low-level method. For convenient methods see the unblind and do_trial methods.

Parameters:

events_list (list of DataFieldRecordArray instances) – The list of DataFieldRecordArray instances holding the data events to use for the log-likelihood function evaluation. The data arrays for the datasets must be in the same order than the added datasets.
n_events_list (list of int | None) – The list of the number of events of each data set. If set to None, the number of events is taken from the size of the given events arrays.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

unblind(rss, tl=None)

Evaluates the unscrambled data, i.e. unblinds the data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used draw random numbers from.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time the maximization of the LLH ratio function.

Returns:

TS (float) – The test-statistic value.
global_params_dict (dict) – The dictionary holding the global parameter names and their best fit values. It includes fixed and floating parameters.
status (dict) – The status dictionary with information about the performed minimization process of the negative of the log-likelihood ratio function.

do_trial_with_given_pseudo_data(rss, mean_n_sig, n_sig, n_events_list, events_list, minimizer_status_dict=None, tl=None, mean_n_sig_0=None)

Performs an analysis trial on the given pseudo data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to use for generating random numbers.
mean_n_sig (float) – The mean number of signal events the pseudo data was generated with.
n_sig (int) – The total number of actual signal events in the pseudo data.
n_events_list (list of int) – The total number of events for each data set of the pseudo data.
events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray containing the pseudo data events for each data sample. The number of events for each data sample can be less than the number of events given by n_events_list if an event selection method was already utilized when generating background events.
minimizer_status_dict (dict | None) – If a dictionary is provided, it will be updated with the minimizer status dictionary.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time individual tasks.
mean_n_sig_0 (float | None) – The fixed mean number of signal events for the null-hypothesis, when using a ns-profile log-likelihood-ratio function. If set to None, this argument is interpreted as 0.

Returns:

recarray (instance of numpy record ndarray) – The numpy record ndarray holding the result of the trial. It contains the following data fields:

rss_seedint: The RandomStateService seed.
mean_n_sigfloat: The mean number of signal events.
n_sigint: The actual number of injected signal events.
mean_n_sig_0float: The fixed mean number of signal events for the null-hypothesis.
tsfloat: The test-statistic value.
[<global_param_name>float ]: Any additional parameters of the LLH ratio function.

class skyllh.core.analysis.SingleSourceMultiDatasetLLHRatioAnalysis(shg_mgr, pmm, test_statistic, bkg_generator_cls=None, sig_generator_cls=None, **kwargs)

Bases: LLHRatioAnalysis

This is an analysis class that implements a log-likelihood ratio analysis for multiple datasets assuming a single source. It is a special case of the multi-source analysis.

For more information how to construct and run the analysis see the documentation of the LLHRatioAnalysis class.

Creates a new time-integrated point-like source analysis assuming a single source.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal efficiency implementation method.
pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance managing the global set of parameters and their relation to individual models, e.g. sources.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_generator_cls (class of BackgroundGeneratorBase | None) – The background generator class used to create the background generator instance. If set to None, the skyllh.core.background_generator.BackgroundGenerator class is used.
sig_generator_cls (SignalGenerator class | None) – The signal generator class that should be used to create the signal generator instance for multiple datasets. If set to None, the MultiDatasetSignalGenerator class is used.

construct_llhratio(minimizer, ppbar=None)

Constructs the log-likelihood (LLH) ratio function of the analysis. This setups all the necessary analysis objects like detector signal yields and dataset signal weights, constructs the log-likelihood ratio functions for each dataset and the final composite LLH ratio function.

Parameters:

minimizer (instance of Minimizer) – The instance of Minimizer that should be used to minimize the negative of the log-likelihood ratio function.
ppbar (instance of ProgressBar | None) – The instance of ProgressBar of the optional parent progress bar.

Returns:

llhratio (instance of MultiDatasetTCLLHRatio) – The instance of MultiDatasetTCLLHRatio that implements the log-likelihood-ratio function of the analysis.

change_source(source)

Changes the source of the analysis to the given source. It makes the necessary changes to all the objects of the analysis.

Parameters:: source (instance of SourceModel) – The instance of SourceModel describing the new source.

calculate_fluxmodel_scaling_factor(mean_ns, fitparam_values)

Calculates the factor the source’s fluxmodel has to be scaled in order to obtain the given mean number of signal events in the detector.

Parameters:

mean_ns (float) – The mean number of signal events in the detector for which the scaling factor is calculated.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D ndarray holding the values of the global fit parameters, that should be used for the flux calculation. The order of the values must match the order the fit parameters were defined in the parameter model mapper.

Returns:

factor (float) – The factor the source’s fluxmodel needs to be scaled in order to obtain the given mean number of signal events in the detector.

class skyllh.core.analysis.MultiSourceMultiDatasetLLHRatioAnalysis(shg_mgr, pmm, test_statistic, bkg_generator_cls=None, sig_generator_cls=None, **kwargs)

Bases: LLHRatioAnalysis

This is an analysis class that implements a log-likelihood ratio analysis for multiple datasets assuming a multiple sources.

For more information how to construct and run the analysis see the documentation of the LLHRatioAnalysis class.

Constructs a new instance of MultiDatasetLLHRatioAnalysis.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal yield implementation method.
pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance managing the global set of parameters and their relation to individual models, e.g. sources.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_generator_cls (class of BackgroundGeneratorBase | None) – The background generator class used to create the background generator instance. If set to None, the skyllh.core.background_generator.BackgroundGenerator class is used.
sig_generator_cls (subclass of SignalGenerator| None) – The signal generator class that should be used to create the signal generator instance handling multiple datasets. If set to None, the MultiDatasetSignalGenerator class is used.

construct_llhratio(minimizer, ppbar=None)

Constructs the log-likelihood (LLH) ratio function of the analysis. This setups all the necessary analysis objects like detector signal yields and dataset signal weights, constructs the log-likelihood ratio functions for each dataset and the final composite LLH ratio function.

Parameters:

minimizer (instance of Minimizer) – The instance of Minimizer that should be used to minimize the negative of the log-likelihood ratio function.
ppbar (instance of ProgressBar | None) – The instance of ProgressBar of the optional parent progress bar.

Returns:

llhratio (instance of MultiDatasetTCLLHRatio) – The instance of MultiDatasetTCLLHRatio that implements the log-likelihood-ratio function of the analysis.

calculate_fluxmodel_scaling_factors(mean_ns, fitparam_values)

Calculates the factors the source’s fluxmodel has to be scaled in order to obtain the given mean number of signal events in the detector.

Parameters:

mean_ns (float) – The mean number of signal events in the detector for which the scaling factors will be calculated.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D ndarray holding the values of the global fit parameters, which should be used for the flux calculation. The order of the values must match the order the fit parameters were defined in the parameter model mapper.

Returns:

factors (instance of numpy ndarray) – The (N_sources,)-shaped numpy ndarray of float holding the factors the flux models of the sources need to be scaled in order to obtain the given mean number of signal events in the detector.

skyllh.core.background_generation module

class skyllh.core.background_generation.BackgroundGenerationMethod(**kwargs)

Bases: HasConfig

This is the abstract base class for a detector specific background generation method.

Constructs a new background generation method instance.

change_shg_mgr(shg_mgr)

Notifies the background generation method about an updated SourceHypoGroupManager instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

abstract generate_events(rss, dataset, data, mean, tl=None, **kwargs)

This method is supposed to generate a mean number of background events for the given dataset and its data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
dataset (instance of Dataset) – The Dataset instance describing the dataset for which background events should get generated.
data (instance of DatasetData) – The DatasetData instance holding the data of the dataset for which background events should get generated.
mean (float) – The mean number of background events to generate.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.
**kwargs – Additional keyword arguments, which might be required for a particular background generation method.

Returns:

n_bkg (int) – The number of generated background events.
bkg_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the generated background events. The number of events in this array might be less than n_bkg if an event selection method was used for optimization purposes. The difference n_bkg - len(bkg_events) is then the number of pure background events in the generated background event sample.

class skyllh.core.background_generation.MCDataSamplingBkgGenMethod(get_event_prob_func, get_mean_func=None, data_scrambler=None, mc_inplace_scrambling=False, keep_mc_data_fields=None, pre_event_selection_method=None, **kwargs)

Bases: BackgroundGenerationMethod

This class implements the method to generate background events from monte-carlo (MC) data by sampling events from the MC data set according to a probability value given for each event. Functions can be provided to get the mean number of background events and the probability of each monte-carlo event.

Creates a new instance of the MCDataSamplingBkgGenMethod class.

Parameters:

get_event_prob_func (callable) –
The function to get the background probability of each monte-carlo event. The call signature of this function must be

__call__(dataset, data, events)

where dataset is an instance of Dataset and data is an instance of DatasetData of the data set for which background events needs to get generated. The events argument holds the actual set of events, for which the background event probabilities need to get calculated.
get_mean_func (callable | None) –
The function to get the mean number of background events. The call signature of this function must be

__call__(dataset, data, events)

where dataset is an instance of Dataset and data is an instance of DatasetData of the data set for which background events needs to get generated. The events argument holds the actual set of events, for which the mean number of background events should get calculated. This argument can be None, which means that the mean number of background events to generate needs to get specified through the generate_events method. However, if a pre event selection method is provided, this argument cannot be None!
data_scrambler (instance of DataScrambler | None) – If set to an instance of DataScrambler, the drawn monte-carlo background events will get scrambled. This can ensure more independent data trials. It is especially important when monte-carlo statistics are low.
mc_inplace_scrambling (bool) – Flag if the scrambling of the monte-carlo data should be done inplace, i.e. without creating a copy of the MC data first. Default is False.
keep_mc_data_fields (str | list of str | None) – The MC data field names that should be kept in order to be able to calculate the background events rates by the functions get_event_prob_func and get_mean_func. All other MC fields will get dropped due to computational efficiency reasons.
pre_event_selection_method (instance of EventSelectionMethod | None) – If set to an instance of EventSelectionMethod, this method will pre-select the MC events that will be used for later background event generation. Using this pre-selection a large portion of the MC data can be reduced prior to background event generation.

property get_event_prob_func: The function to obtain the background probability for each monte-carlo event of the data set.

property get_mean_func: The function to obtain the mean number of background events for the data set. This can be None, which means that the mean number of background events to generate needs to be specified through the generate_events method.

property data_scrambler: The DataScrambler instance that should be used to scramble the drawn monte-carlo background events to ensure more independent data trials. This is especially important when monte-carlo statistics are low. It is None, if no data scrambling should be used.

property mc_inplace_scrambling: Flag if the scrambling of the monte-carlo data should be done inplace, i.e. without creating a copy of the MC data first.

property keep_mc_data_field_names: The MC data field names that should be kept in order to be able to calculate the background events rates by the functions get_event_prob_func and get_mean_func. All other MC fields will get dropped due to computational efficiency reasons.

property pre_event_selection_method: The instance of EventSelectionMethod that pre-selects the MC events, which can be considered for background event generation.

change_shg_mgr(shg_mgr)

Changes the instance of SourceHypoGroupManager of the pre-event-selection method. Also it invalidates the data cache of this background generation method.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

generate_events(rss, dataset, data, mean=None, poisson=True, tl=None)

Generates a mean number of background events for the given dataset and its data.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
dataset (instance of Dataset) – The Dataset instance describing the dataset for which background events should get generated.
data (instance of DatasetData) – The DatasetData instance holding the data of the dataset for which background events should get generated.
mean (float | None) – The mean number of background events to generate. Can be None. In that case the mean number of background events is obtained through the get_mean_func function.
poisson (bool) – If set to True (default), the actual number of generated background events will be drawn from a Poisson distribution with the given mean number of background events. If set to False, the argument mean specifies the actual number of generated background events.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

n_bkg (int) – The number of generated background events for the data set.
bkg_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the generated background events. The number of events can be less than n_bkg if an event selection method is used.

skyllh.core.background_generator module

class skyllh.core.background_generator.BackgroundGenerator(**kwargs)

Bases: HasConfig

This is the abstract base class for all background generator classes in SkyLLH. It defines the interface for a background generator.

Constructs a new instance of BackgroundGenerator.

Parameters:: bkg_gen_method (instance of BackgroundGenerationMethod) – The optional background event generation method, which should be used to generate events.

change_shg_mgr(shg_mgr)

This method should be reimplemented when the background generator depends on the sources.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

abstract generate_background_events(rss, tl=None, **kwargs)

This method is supposed to generate a mean number of background events for the datasets of this background generator.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.
**kwargs – Additional keyword arguments, which will be passed to the generate_events method of the background generation method instance. Usual keyword arguments are mean, the mean number of background events to generate, and poisson, the flag if the number of background events should get drawn from a Poisson distribution with the given mean number of background events as mean.

Returns:

n_bkg_list (list of int) – The number of generated background events.
bkg_events_list (list of instance of DataFieldRecordArray) – The list of instance of DataFieldRecordArray holding the generated background events. The number of events can be less than stated in n_bkg_list if an event selection method is used.

class skyllh.core.background_generator.DatasetBackgroundGenerator(dataset, data, bkg_gen_method, **kwargs)

Bases: BackgroundGenerator

This class provides a background generator for a particular dataset. It holds a background generation method which is used to generate the background events.

Constructs a new instance of BackgroundGenerator.

Parameters:: bkg_gen_method (instance of BackgroundGenerationMethod) – The optional background event generation method, which should be used to generate events.

property dataset: The instance of Dataset for which background events should get generated.

property data: The instance of DatasetData holding the experimental and simulation data of the dataset.

property bkg_gen_method: The instance of BackgroundGenerationMethod which should be used to generate background events. This can be None.

change_shg_mgr(shg_mgr)

Changes the SourceHypoGroupManager instance of the background generation method.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

generate_background_events(rss, tl=None, **kwargs)

Generates a mean number of background events for the dataset of this background generator.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.
**kwargs – Additional keyword arguments, which will be passed to the generate_events method of the background generation method instance. Usual keyword arguments are mean, the mean number of background events to generate, and poisson, the flag if the number of background events should get drawn from a Poisson distribution with the given mean number of background events as mean.

Returns:

n_bkg_list (list of int) – The list of length 1 holding the number of generated background events for the dataset.
bkg_events_list (list of instance of DataFieldRecordArray) – The list of length 1 holding the instance of DataFieldRecordArray holding the generated background events. The number of events can be less than stated in n_bkg_list if an event selection method is used.

class skyllh.core.background_generator.MultiDatasetBackgroundGenerator(dataset_list, data_list, bkg_generator_list, **kwargs)

Bases: BackgroundGenerator

This is a background generator class handling multiple datasets by using the individual background generator instances for each dataset. This is the most general way to support multiple datasets of different formats and background generation.

Constructs a new instance of MultiDatasetBackgroundGenerator.

Parameters:

dataset_list (list of instance of Dataset) – The list of Dataset instances for which background events should get generated for.
data_list (list of instance of DatasetData) – The list of DatasetData instances holding the actual data of each dataset. The order must match the order of dataset_list.
bkg_generator_list (list of instance of BackgroundGenerator) – The list of BackgroundGenerator instances, one for each dataset. The order must match the order of dataset_list.

property dataset_list: The list of Dataset instances for which background events should get generated for.

property data_list: The list of DatasetData instances holding the actual data of each dataset. The order must match the order of the dataset_list property.

property bkg_generator_list: The list of instance of BackgroundGenerator, one for each dataset. The order must match the order of the dataset_list property.

generate_background_events(rss, mean_n_bkg_list=None, tl=None, **kwargs)

Generates a mean number of background events for each individual dataset of this multi-dataset background generator.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. If set to None (the default), the individual background generator instance needs to obtain this number itself.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.
**kwargs – Additional keyword arguments, which will be passed to the generate_background_events method of the individual background generator instance.

Returns:

n_bkg_events_list (list of int) – The list holding the number of generated background events for each dataset.
bkg_events_list (list of instance of DataFieldRecordArray) – The list holding the instance of DataFieldRecordArray holding the generated background events of each dataset. The number of events can be less than stated in n_bkg_list if an event selection method is used.

skyllh.core.backgroundpdf module

The backgroundpdf module contains background PDF classes for the likelihood function.

class skyllh.core.backgroundpdf.BackgroundMultiDimGridPDF(*args, **kwargs)

Bases: MultiDimGridPDF, IsBackgroundPDF

This class provides a multi-dimensional background PDF defined on a grid. The PDF is created from pre-calculated PDF data on a grid. The grid data is interpolated using a scipy.interpolate.RegularGridInterpolator instance.

Creates a new MultiDimGridPDF instance that is also derived from IsBackgroundPDF.

For the documentation of arguments see the documentation of the __init__() method.

class skyllh.core.backgroundpdf.BackgroundTimePDF(livetime, time_flux_profile, **kwargs)

Bases: TimePDF, IsBackgroundPDF

This class provides a background time PDF class.

Creates a new signal time PDF instance for a given time flux profile and detector live time.

Parameters:

livetime (instance of Livetime) – An instance of Livetime, which provides the detector live-time information.
time_flux_profile (instance of TimeFluxProfile) – The signal’s time flux profile.

initialize_for_new_trial(tdm, tl=None, **kwargs)

Initializes the background time PDF with new trial data. Because this PDF does not depend on any parameters, the probability density values can be pre-computed here.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial event data for which to calculate the PDF value. The following data fields must exist:

'time'float
The MJD time of the event.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

get_pd(tdm, params_recarray=None, tl=None)

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial event data for which to calculate the PDF value. The following data fields must exist:

'time'float
The MJD time of the event.
params_recarray (None) – Unused interface argument.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

pd (instance of numpy ndarray) – The (N_events,)-shaped numpy ndarray holding the background probability density value for each event.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter. The background PDF does not depend on any global fit parameter, hence, this is an empty dictionary.

skyllh.core.binning module

skyllh.core.binning.get_bincenters_from_binedges(edges)

Calculates the bin center values from the given bin edge values.

Parameters:: edges (1D numpy ndarray) – The (n+1,)-shaped 1D ndarray holding the bin edge values.
Returns:: bincenters (1D numpy ndarray) – The (n,)-shaped 1D ndarray holding the bin center values.

skyllh.core.binning.get_binedges_from_bincenters(centers)

Calculates the bin edges from the given bin center values. The bin center values must be evenly spaced.

Parameters:: centers (1D numpy ndarray) – The (n,)-shaped 1D ndarray holding the bin center values.
Returns:: edges (1D numpy ndarray) – The (n+1,)-shaped 1D ndarray holding the bin edge values.

skyllh.core.binning.get_bin_indices_from_lower_and_upper_binedges(le, ue, values)

Returns the bin indices for the given values which must fall into bins defined by the given lower and upper bin edges.

Note: The upper edge is not included in the bin.

Parameters:

le ((m,)-shaped 1D numpy ndarray) – The lower bin edges.
ue ((m,)-shaped 1D numpy ndarray) – The upper bin edges.
values ((n,)-shaped 1D numpy ndarray) – The values for which to get the bin indices.

Returns:

idxs ((n,)-shaped 1D numpy ndarray) – The bin indices of the given values.

class skyllh.core.binning.BinningDefinition(name, binedges)

Bases: object

The BinningDefinition class provides a structure to hold histogram binning definitions for an analysis.

Creates a new binning definition object.

Parameters:

name (str) – The name of the binning definition.
binedges (sequence of float) – The sequence of the bin edges, which should be used for the binning.

__eq__(other): Checks if object other is equal to this BinningDefinition object.

property name: The name of the binning setting. This must be an unique name for all the different binning settings used within a season.

property binedges: The numpy.ndarray holding the bin edges.

property nbins: The number of bins, based on the number of bin edges (minus 1).

property bincenters: The center values of the bins.

property binwidths: (read-only) The widths of the bins.

property lower_edge: The lowest bin edge of the binning.

property upper_edge: The upper most edge of the binning.

property range: The tuple (lower_edge, upper_edge) of the binning.

any_data_out_of_range(data)

Checks if any of the given data is outside the range of this binning definition.

Parameters:: data (instance of ndarray) – The 1D ndarray with the data values to check.
Returns:: outofrange (bool) – True if any data value is outside the binning range. False otherwise.

get_binwidth_from_value(value): Returns the width of the bin the given value falls into.

get_out_of_range_data(data)

Returns the data values which are outside the range of this binning definition.

Parameters:: data (instance of numpy.ndarray) – The 1D ndarray with the data values to check.
Returns:: oor_data (instance of numpy.ndarray) – The 1D ndarray with data outside the range of this binning definition.

get_subset(lower_edge, upper_edge)

Creates a new BinningDefinition instance which contains only a subset of the bins of this BinningDefinition instance. The range of the subset is given by a lower and upper edge value.

Parameters:

lower_edge (float) – The lower edge value of the subset.
upper_edge (float) – The upper edge value of the subset.

Returns:

binning (instance of BinningDefinition) – The new instance of BinningDefinition holding the binning subset.

class skyllh.core.binning.UsesBinning(*args, **kwargs)

Bases: object

This is a classifier class that can be used to define, that a class uses binning information for one or more dimensions.

This class defines the property binnings, which is a list of BinningDefinition objects.

This class provides the method has_same_binning_as(obj) to determine if a given object (that also uses binning) has the same binning.

property binnings: (read-only) The list of BinningDefinition objects, one for each dimension.

property binning_ndim: (read-only) The number of dimensions that uses binning.

has_same_binning_as(obj)

Checks if this object has the same binning as the given object.

Parameters:: obj (instance of UsesBinning) – The object that should be checked for same binning.
Returns:: check (bool) – True if obj uses the same binning, False otherwise.

add_binning(binning, name=None)

Adds the given binning definition to the list of binnings.

Parameters:

binning (instance of BinningDefinition) – The binning definition to add.
name (str | (default) None) – The name of the binning. If not None and it’s different to the name of the given binning definition, a copy of the BinningDefinition object is made and the new name is set.

get_binning(name)

Retrieves the binning definition of the given name.

Parameters:: name (str | int) – The name of the binning definition. A string specifies the name and an integer the dimension index.
Returns:: binning (instance of BinningDefinition) – The binning definition of the given name.

skyllh.core.catalog module

This module provides classes for defining source catalogs.

class skyllh.core.catalog.SourceCatalog(name, sources=None, source_type=None, **kwargs)

Bases: SourceModelCollection

This class describes a catalog of sources. It is derived from SourceModelCollection. A catalog has a name.

Creates a new source catalog.

Parameters:

name (str) – The name of the catalog.
sources (sequence of source_type | None) – The sequence of sources this catalog should be initialized with.
source_type (type | None) – The type of the source class. If set to None (default), the default type defined by SourceCollection will be used.

property name: The name of the catalog.

as_SourceModelCollection()

Creates a SourceModelCollection object for this catalog and returns it.

Returns:: source_model_collection (instance of SourceModelCollection) – The created instance of SourceModelCollection.

skyllh.core.config module

This file contains the global configuration dictionary, together with some convenience utility functions to set different configuration settings.

class skyllh.core.config.Config

Bases: dict

This class, derived from dict, holds the a local configuration state.

Initializes a new Config instance holding the base configuration.

classmethod from_yaml(*args, **kwargs)

classmethod from_dict(user_dict: Dict[str, Any])

Creates a new instance of Config holding the base configuration and updated by the given configuration dictionary using the dict.update() method.

Parameters:: user_dict (dict) – The dictionary containing the to-be-updated configuration items.
Returns:: cfg (instance of Config) – The instance of Config holding the base configuration and updated by the given configuration dictionary.

property is_tracing_enabled: True, if tracing mode is enabled, False otherwise.

disable_tracing()

Disables the tracing mode of SkyLLH.

Returns:: self (instance of Config) – The updated instance of Config.

enable_tracing()

Enables the tracing mode of SkyLLH.

Returns:: self (instance of Config) – The updated instance of Config.

get_wd()

Retrieves the absolute path to the working directory as configured in this configuration.

Returns:: wd (str) – The absolute path to the project’s working directory.

set_enable_tracing(flag)

Sets the setting for tracing.

Parameters:: flag (bool) – The flag if tracing should be enabled (True) or disabled (False).
Returns:: self (instance of Config) – The updated instance of Config.

set_internal_units(angle_unit=None, energy_unit=None, length_unit=None, time_unit=None)

Sets the units used internally to compute quantities. These units must match the units used in the monte-carlo files.

Parameters:

angle_unit (instance of astropy.units.UnitBase | None) – The internal unit that should be used for angles. If set to None, the unit is not changed.
energy_unit (instance of astropy.units.UnitBase | None) – The internal unit that should be used for energy. If set to None, the unit is not changed.
length_unit (instance of astropy.units.UnitBase | None) – The internal unit that should be used for length. If set to None, the unit is not changed.
time_unit (instance of astropy.units.UnitBase | None) – The internal unit that should be used for time. If set to None, the unit is not changed.

Returns:

self (instance of Config) – The updated instance of Config.

set_ncpu(ncpu)

Sets the global setting for the number of CPUs to use, when parallelization is available.

Parameters:: ncpu (int) – The number of CPUs.
Returns:: self (instance of Config) – The updated instance of Config.

set_wd(path=None)

Sets the project’s working directory configuration variable and adds it to the Python path variable.

Parameters:

cfg (instance of Config) – The instance of Config holding the local configuration.
path (str | None) – The path of the project’s working directory. This can be a path relative to the path given by os.path.getcwd, the current working directory of the program. If set to None, the path is taken from the working directory setting of the given configuration.

Returns:

wd (str) – The absolute path to the project’s working directory.

to_internal_time_unit(time_unit)

Calculates the conversion factor from the given time unit to the internal time unit specified by this local configuration.

Parameters:: time_unit (instance of astropy.units.UnitBase) – The time unit from which to convert to the internal time unit.

wd_filename(filename)

Generates the fully qualified file name under the project’s working directory of the given file.

Parameters:: filename (str) – The name of the file for which to generate the working directory path file name.
Returns:: pathfilename (str) – The generated fully qualified path file name of filename with the project’s working directory prefixed.

class skyllh.core.config.HasConfig(cfg, *args, **kwargs)

Bases: object

Classifier class defining the cfg property. Classes that derive from this class indicate, that they hold an instance of Config.

Creates a new instance having the property cfg.

Parameters:: cfg (instance of Config) – The instance of Config holding the local configuration.

property cfg: The instance of Config holding the local configuration.

skyllh.core.datafields module

This module provides functionality for defining which data fields of a data file is required at what stage.

class skyllh.core.datafields.DataFieldStages

Bases: object

This class provides the data field stage values, which are individual bits of an integer value to allow for multiple stages of a data field.

DATAPREPARATION_EXP = 1

DATAPREPARATION_MC = 2

ANALYSIS_EXP = 4

ANALYSIS_MC = 8

static and_check(stage, stages)

Checks if the given stage matches all of the given stages.

Parameters:

stage (int) – The stage value, which should get checked.
stages (int | sequence of int) – The stage(s) to check for.

Returns:

check (bool) – True if the given stage contains all of the given stages, False otherwise.

static or_check(stage, stages)

Checks if the given stage matches any of the given stages.

Parameters:

stage (int) – The stage value, which should get checked.
stages (int | sequence of int) – The stage(s) to check for.

Returns:

check (bool) – True if the given stage contains any of the given stages, False otherwise.

class skyllh.core.datafields.DataFields

Bases: object

static get_joint_names(datafields, stages)

Returns the list of data field names that match at least one of the given stages, i.e. the joint set of data fields given the stages.

Parameters:

datafields (dict) – The dictionary of data field names as keys and stages as values.
stages (int | sequence of int) – The stage(s) for which data field names should get returned.

Returns:

datafield_names (list of str) – The list of data field names.

skyllh.core.dataset module

class skyllh.core.dataset.DatasetOrigin(base_path, sub_path, transfer_func, filename=None, host=None, port=None, username=None, password=None, post_transfer_func=None, **kwargs)

Bases: object

The DatasetOrigin class provides information about the origin of a dataset, so the files of a dataset can be downloaded from the origin.

Creates a new instance to define the origin of a dataset.

Parameters:

base_path (str) – The dataset’s base directory at the origin.
sub_path (str) – The dataset’s sub directory at the origin.
transfer_func (callable) –
The callable object that should be used to transfer the dataset. This function requires the following call signature:
```
__call__(origin, file_list, dst_base_path, user=None, password=None)
```
where origin is an instance of DatasetOrigin, file_list is a list of str specifying the files to transfer, dst_base_path is an instance of str specifying the destination base path on the local machine, user is the user name required to connect to the remote host, and password is the password for the user name required to connect to the remote host.
filename (str | None) – If the origin is not a directory but a file, this specifies the filename.
host (str | None) – The name or IP of the remote host.
port (int | None) – The port number to use when connecting to the remote host.
username (str | None) – The user name required to connect to the remote host.
password (str | None) – The password for the user name required to connect to the remote host.
post_transfer_func (callable | None) –
The callable object that should be called after the dataset has been transferred by the ``transfer_func``function. It can be used to extract an archive file. This function requires the following call signature:
```
__call__(ds, dst_path)
```
where ds is an instance of Dataset, and dst_path is the destination path.

property base_path: The dataset’s base directory at the origin.

property sub_path: The dataset’s sub directory at the origin.

property root_dir: (read-only) The dataset’s root directory at the origin, which is the combination of base_path and sub_path.

property transfer_func: The callable object that should be used to transfer the dataset.

property filename: The file name if the origin is a file instead of a directory.

property is_directory: (read-only) Flag if the origin refers to a directory (True) or a file (False).

property host: The name or IP of the remote host.

property port: The port number to use when connecting to the remote host.

property username: The user name required to connect to the remote host.

property password: The password for the user name required to connect to the remote host.

property post_transfer_func: The callable object that should be called after the dataset has been transferred by the transfer_func callable.

is_locally_available()

Checks if the dataset origin is available locally by checking if the given path exists on the local host.

Returns:: check (bool) – True if the path specified in this dataset origin is an absolute path and exists on the local host, False otherwise.

class skyllh.core.dataset.TemporaryTextFile(pathfilename, text, mode=420)

Bases: object

This class provides a temporary text file with a given content while being within a with statement. Exiting the with statement will remove the temporary text file.

Example:

with TemporaryTextFile('myfile.txt', 'My file content'):
    # Do something that requires the text file ``myfile.txt``.
# At this point the text file is removed again.

__enter__()

__exit__(exc_type, exc_val, exc_tb)

exception skyllh.core.dataset.SystemCommandError

Bases: Exception

This custom exception will be raised when a system command failed.

exception skyllh.core.dataset.DatasetTransferError

Bases: Exception

This custom exception defines an error that should be raised when the actual transfer of the dataset files failed.

class skyllh.core.dataset.DatasetTransfer(**kwargs)

Bases: object

Base class for a dataset transfer mechanism.

static execute_system_command(cmd, logger, success_rcode=0)

Executes the given system command via a os.system call.

Parameters:

cmd (str) – The system command to execute.
logger (instance of logging.Logger) – The logger to use for debug messages.
success_rcode (int | None) – The return code that indicates success of the system command. If set to None, no return code checking is performed.

Raises:

SystemCommandError – If the system command did not return success_rcode.

static ensure_dst_path(dst_path)

Ensures the existence of the given destination path.

Parameters:: dst_path (str) – The destination path.

abstract transfer(origin, file_list, dst_base_path, username=None, password=None)

This method is supposed to transfer the dataset origin path to the given destination path.

Parameters:

origin (instance of DatasetOrigin) – The instance of DatasetOrigin defining the origin of the dataset.
file_list (list of str) – The list of files, relative to the origin base path, which should be transferred.
dst_base_path (str) – The destination base path into which the dataset files will be transferred.
username (str | None) – The user name required to connect to the remote host.
password (str | None) – The password for the user name required to connect to the remote host.

Raises:

DatasetTransferError – If the actual transfer of the dataset files failed.

static post_transfer_unzip(ds, dst_path): This is a post-transfer function. It will unzip the transferred file into the dst_path if the origin path was a zip file.

class skyllh.core.dataset.RSYNCDatasetTransfer(**kwargs)

Bases: DatasetTransfer

transfer(origin, file_list, dst_base_path, username=None, password=None)

Transfers the given dataset to the given destination path using the rsync program.

Parameters:

ds (instance of Dataset) – The instance of Dataset containing the origin property specifying the origin of the dataset.
file_list (list of str) – The list of files, relative to the origin base path, which should be transferred.
dst_base_path (str) – The destination base path into which the dataset files will be transferred.
username (str | None) – The user name required to connect to the remote host.
password (str | None) – The password for the user name required to connect to the remote host.

class skyllh.core.dataset.WGETDatasetTransfer(protocol, **kwargs)

Bases: DatasetTransfer

property protocol: The protocol to use for the transfer.

transfer(origin, file_list, dst_base_path, username=None, password=None)

Transfers the given dataset to the given destination path using the wget program.

Parameters:

origin (instance of DatasetOrigin) – The instance of DatasetOrigin defining the origin of the dataset.
file_list (list of str) – The list of files relative to the origin’s base path, which should be transferred.
dst_base_path (str) – The destination base path into which the dataset will be transferred.
username (str | None) – The user name required to connect to the remote host.
password (str | None) – The password for the user name required to connect to the remote host.

class skyllh.core.dataset.Dataset(name, exp_pathfilenames, mc_pathfilenames, livetime, default_sub_path_fmt, version, verqualifiers=None, base_path=None, sub_path_fmt=None, origin=None, **kwargs)

Bases: HasConfig

The Dataset class describes a set of self-consistent experimental and simulated detector data. Usually this is for a certain time period, i.e. a season.

Independent data sets of the same kind, e.g. event selection, can be joined through a DatasetCollection object.

Creates a new dataset object that describes a self-consistent set of data.

Parameters:

name (str) – The name of the dataset.
exp_pathfilenames (str | sequence of str | None) – The file name(s), including paths, of the experimental data file(s). This can be None, if a MC-only study is performed.
mc_pathfilenames (str | sequence of str | None) – The file name(s), including paths, of the monte-carlo data file(s). This can be None, if a MC-less analysis is performed.
livetime (float | None) – The integrated live-time in days of the dataset. It can be None for cases where the live-time is retrieved directly from the data files upon data loading.
default_sub_path_fmt (str) – The default format of the sub path of the data set. This must be a string that can be formatted via the format method of the str class.
version (int) – The version number of the dataset. Higher version numbers indicate newer datasets.
verqualifiers (dict | None) – If specified, this dictionary specifies version qualifiers. These can be interpreted as subversions of the dataset. The format of the dictionary must be ‘qualifier (str): version (int)’.
base_path (str | None) – The user-defined base path of the data set. Usually, this is the path of the location of the data directory. If set to None the configured repository base path Config['repository']['base_path'] is used.
sub_path_fmt (str | None) – The user-defined format of the sub path of the data set. If set to None, the default_sub_path_fmt will be used.
origin (instance of DatasetOrigin | None) – The instance of DatasetOrigin defining the origin of the dataset, so the dataset can be transferred automatically to the user’s device.

static get_combined_exp_pathfilenames(datasets)

Creates the combined list of exp pathfilenames of all the given datasets.

Parameters:: datasets (sequence of Dataset) – The sequence of Dataset instances.
Returns:: exp_pathfilenames (list) – The combined list of exp pathfilenames.

static get_combined_mc_pathfilenames(datasets)

Creates the combined list of mc pathfilenames of all the given datasets.

Parameters:: datasets (sequence of Dataset) – The sequence of Dataset instances.
Returns:: mc_pathfilenames (list) – The combined list of mc pathfilenames.

static get_combined_livetime(datasets)

Sums the live-time of all the given datasets.

Parameters:: datasets (sequence of Dataset) – The sequence of Dataset instances.
Returns:: livetime (float) – The sum of all the individual live-times.

property name: The name of the dataset. This must be an unique identifier among all the different datasets.

property description: The (longer) description of the dataset.

property datafields: The dictionary holding the names and stages of required data fields specific for this dataset.

property exp_pathfilename_list: The list of file names of the data files that store the experimental data for this dataset. If a file name is given with a relative path, it will be relative to the root_dir property of this Dataset instance.

property exp_abs_pathfilename_list: (read-only) The list of absolute path file names of the experimental data files.

property mc_pathfilename_list: The list of file names of the data files that store the monte-carlo data for this dataset. If a file name is given with a relative path, it will be relative to the root_dir property of this Dataset instance.

property mc_abs_pathfilename_list: (read-only) The list of absolute path file names of the monte-carlo data files.

property livetime: The integrated live-time in days of the dataset. This can be None in cases where the livetime is retrieved directly from the data files.

property version: The main version (int) of the dataset.

property verqualifiers: The dictionary holding the version qualifiers, i.e. sub-version qualifiers. If set to None, an empty dictionary will be used. The dictionary must have the type form of str:int.

property base_path: The base path of the data set. This can be None.

property default_sub_path_fmt: The default format of the sub path of the data set. This must be a string that can be formatted via the format method of the str class.

property sub_path_fmt: The format of the sub path of the data set. This must be a string that can be formatted via the format method of the str class. If set to None, this property will return the default_sub_path_fmt property.

property origin: The instance of DatasetOrigin defining the origin of the dataset. This can be None if the dataset has no origin defined.

property root_dir: (read-only) The root directory to use when data files are specified with relative paths. It is constructed from the base_path and the sub_path_fmt properties via the generate_data_file_root_dir function.

property exp_field_name_renaming_dict: The dictionary specifying the field names of the experimental data which need to get renamed just after loading the data. The dictionary values are the new names.

property mc_field_name_renaming_dict: The dictionary specifying the field names of the monte-carlo data which need to get renamed just after loading the data. The dictionary values are the new names.

property exists: (read-only) Flag if all the data files of this dataset exists. It is True if all data files exist and False otherwise.

property version_str: The version string of the dataset. This combines all the version information about the dataset.

property data_preparation_functions: The list of callback functions that will be called to prepare the data (experimental and monte-carlo).

__gt__(ds)

Implementation to support the operation b = self > ds, where self is this Dataset object and ds an other Dataset object. The comparison is done based on the version information of both datasets. Larger version numbers for equal version qualifiers indicate newer (greater) datasets.

The two datasets must be of the same kind, i.e. have the same name, in order to make the version comparison senseful.

Returns:: bool – True, if this dataset is newer than the reference dataset. False, if this dataset is as new or older than the reference dataset.

remove_data()

Removes the data of this dataset by removing the dataset’s root directory and everything in it. If the root directory is a symbolic link, only this link will be removed.

Raises:: RuntimeError – If the dataset’s root directory is neither a symlink nor a directory.

get_abs_pathfilename_list(pathfilename_list)

Returns a list where each entry of the given pathfilename_list is an absolute path. Relative paths will be prefixed with the root_dir property of this Dataset instance.

Parameters:: pathfilename_list (sequence of str) – The sequence of file names, either with relative, or absolute paths.
Returns:: abs_pathfilename_list (list of str) – The list of file names with absolute paths.

get_missing_files()

Determines which files of the dataset are missing and returns the list of files.

Returns:: missing_files (list of str) – The list of files that are missing. The files are relative to the dataset’s root directory.

update_version_qualifiers(verqualifiers)

Updates the version qualifiers of the dataset. The update can only be done by increasing the version qualifier integer or by adding new version qualifiers.

Parameters:: verqualifiers (dict) – The dictionary with the new version qualifiers.
Raises:: ValueError – If the integer number of an existing version qualifier is not larger than the old one.

create_file_list()

Creates the list of files that are linked to this dataset. The file paths are relative to the dataset’s root directory.

Returns:: file_list (list of str) – The list of files of this dataset.

make_data_available(username=None, password=None)

Makes the data of the dataset available. If the root directory of the dataset does not exist locally, the dataset is transferred from its origin to the local host. If the origin is already available locally, only a symlink is created to the origin path.

Parameters:

username (str | None) – The user name required to connect to the remote host of the origin. If set to None, the
password (str | None) – The password of the user name required to connect to the remote host of the origin.

Returns:

success (bool) – True if the data was made available successfully, False otherwise.

load_data(livetime=None, keep_fields=None, dtc_dict=None, dtc_except_fields=None, efficiency_mode=None, tl=None)

Loads the data, which is described by the dataset.

Parameters:

livetime (instance of Livetime | float | None) – If not None, uses this livetime (if float, livetime in days) for the DatasetData instance, otherwise uses the Dataset livetime property value for the DatasetData instance.
keep_fields (list of str | None) – The list of user-defined data fields that should get loaded and kept in addition to the analysis required data fields.
dtc_dict (dict | None) – This dictionary defines how data fields of specific data types (key) should get converted into other data types (value). This can be used to use less memory. If set to None, no data conversion is performed.
dtc_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.
efficiency_mode (str | None) –
The efficiency mode the data should get loaded with. Possible values are:

'memory'
The data will be load in a memory efficient way. This will require more time, because all data records of a file will be loaded sequentially.

'time'
The data will be loaded in a time efficient way. This will require more memory, because each data file gets loaded in memory at once.

The default value is 'time'. If set to None, the default value will be used.
tl (instance of TimeLord | None) – The TimeLord instance to use to time the data loading procedure.

Returns:

data (instance of DatasetData) – A instance of DatasetData holding the experimental and monte-carlo data.

load_aux_data(name, tl=None)

Loads the auxiliary data for the given auxiliary data definition.

Parameters:

name (str) – The name of the auxiliary data.
tl (instance of TimeLord | None) – The TimeLord instance to use to time the data loading procedure.

Returns:

data (unspecified) – The loaded auxiliary data.

add_data_preparation(func)

Adds the given data preparation function to the dataset.

Parameters:: func (callable) – The object with call signature __call__(data) that will prepare the data after it was loaded. The argument ‘data’ is a DatasetData instance holding the experimental and monte-carlo data. The function must alter the properties of the DatasetData instance.

remove_data_preparation(key=-1)

Removes a data preparation function from the dataset.

Parameters:

key (str, int, optional) – The name or the index of the data preparation function that should be removed. Default value is -1, i.e. the last added function.

Raises:

TypeError – If the type of the key argument is invalid.
IndexError – If the given key is out of range.
KeyError – If the data preparation function cannot be found.

prepare_data(data, tl=None)

Prepares the data by calling the data preparation callback functions of this dataset.

Parameters:

data (instance of DatasetData) – The instance of DatasetData holding the data.
tl (instance of TimeLord | None) – The instance TimeLord that should be used to time the data preparation.

load_and_prepare_data(livetime=None, keep_fields=None, dtc_dict=None, dtc_except_fields=None, efficiency_mode=None, tl=None)

Loads and prepares the experimental and monte-carlo data of this dataset by calling its load_data and prepare_data methods. After loading the data it drops all unnecessary data fields if they are not listed in keep_fields. In the end it asserts the data format of the experimental and monte-carlo data.

Parameters:

livetime (float | None) – The user-defined livetime in days of the data set. If not set to None, livetime information from the data set will get ignored and this value of the livetime will be used.
keep_fields (sequence of str | None) – The list of additional data fields that should get kept. By default only the required data fields are kept.
dtc_dict (dict | None) – This dictionary defines how data fields of specific data types (key) should get converted into other data types (value). This can be used to use less memory. If set to None, no data conversion is performed.
dtc_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.
efficiency_mode (str | None) –
The efficiency mode the data should get loaded with. Possible values are:

'memory'
The data will be load in a memory efficient way. This will require more time, because all data records of a file will be loaded sequentially.

'time'
The data will be loaded in a time efficient way. This will require more memory, because each data file gets loaded in memory at once.

The default value is 'time'. If set to None, the default value will be used.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to time the data loading and preparation.

Returns:

data (instance of DatasetData) – The instance of DatasetData holding the experimental and monte-carlo data.

add_binning_definition(binning)

Adds a binning setting to this dataset.

Parameters:: binning (BinningDefinition) – The BinningDefinition object holding the binning information.

get_binning_definition(name)

Gets the BinningDefinition object for the given binning name.

Parameters:: name (str) – The name of the binning definition.
Returns:: binning_definition (instance of BinningDefinition) – The requested instance of BinningDefinition.

remove_binning_definition(name)

Removes the BinningDefinition object from the dataset.

Parameters:: name (str) – The name of the binning definition.

has_binning_definition(name)

Checks if the dataset has a defined binning definition with the given name.

Parameters:: name (str) – The name of the binning definition.
Returns:: check (bool) – True if the binning definition exists, False otherwise.

define_binning(name, binedges)

Defines a binning for name, and adds it as binning definition.

Parameters:

name (str) – The name of the binning setting.
binedges (sequence) – The sequence of the bin edges, which should be used for this binning definition.

Returns:

binning (instance of BinningDefinition) – The instance of BinningDefinition which was created and added to this dataset.

replace_binning_definition(binning)

Replaces an already defined binning definition of this dataset by the given binning definition.

Parameters:: binning (instance of BinningDefinition) – The instance of BinningDefinition that will replace the dataset’s BinningDefinition instance of the same name.

add_aux_data_definition(name, pathfilenames)

Adds the given data files as auxiliary data definition to the dataset.

Parameters:

name (str) – The name of the auxiliary data definition. The name is used as identifier for the data within SkyLLH.
pathfilenames (str | sequence of str) – The file name(s) (including paths) of the data file(s).

get_aux_data_definition(name)

Returns the auxiliary data definition from the dataset.

Parameters:: name (str) – The name of the auxiliary data definition.
Raises:: KeyError – If auxiliary data with the given name does not exist.
Returns:: aux_data_definition (list of str) – The locations (pathfilenames) of the files defined in the auxiliary data as auxiliary data definition.

set_aux_data_definition(name, pathfilenames)

Sets the files of the auxiliary data definition, which has the given name.

Parameters:

name (str) – The name of the auxiliary data definition.
pathfilenames (str | sequence of str) – The file name(s) (including paths) of the data file(s).

remove_aux_data_definition(name)

Removes the auxiliary data definition from the dataset.

Parameters:: name (str) – The name of the data definition that should get removed.

remove_aux_data_definitions(names)

Removes the auxiliary data definition from the dataset.

Parameters:: names (sequence of str) – The names of the data definitions that should get removed.

add_aux_data(name, data)

Adds the given data as auxiliary data to this data set.

Parameters:

name (str) – The name under which the auxiliary data will be stored.
data (unspecified) – The data that should get stored. This can be of any data type.

Raises:

KeyError – If auxiliary data is already stored under the given name.

get_aux_data(name, default=None)

Retrieves the auxiliary data that is stored in this data set under the given name.

Parameters:

name (str) – The name under which the auxiliary data is stored.
default (any | None) – If not None, it specifies the returned default value when the auxiliary data does not exists.

Returns:

data (unspecified) – The retrieved auxiliary data.

Raises:

KeyError – If no auxiliary data is stored with the given name and no default value was specified.

remove_aux_data(name)

Removes the auxiliary data that is stored in this data set under the given name.

Parameters:: name (str) – The name of the dataset that should get removed.

class skyllh.core.dataset.DatasetCollection(name, description='')

Bases: object

The DatasetCollection class describes a collection of different datasets.

New datasets can be added via the add-assign operator (+=), which calls the add_datasets method.

Creates a new DatasetCollection instance.

Parameters:

name (str) – The name of the collection.
description (str) – The (longer) description of the dataset collection.

property name: The name (str) of the dataset collection.

property description: The (longer) description of the dataset collection.

property dataset_names: The list of names of the assigned datasets.

property version: (read-only) The version number of the datasets collected by this dataset collection.

property verqualifiers: (read-only) The dictionary holding the version qualifiers of the datasets collected by this dataset collection.

__getitem__(key)

Implementation of the access operator [key].

Parameters:: key (str | sequence of str) – The name or names of the dataset(s) that should get retrieved from this dataset collection.
Returns:: datasets (instance of Dataset | list of instance of Dataset) – The dataset instance or the list of dataset instances corresponding to the given key.

__iadd__(ds): Implementation of the self += dataset and self += (dataset1, dataset2, ...) operations to add one or several Dataset objects to this dataset collection.

add_aux_data(name, data)

Adds the given data as auxiliary data to all datasets of this dataset collection.

Parameters:

name (str) – The name under which the auxiliary data will be stored.
data (unspecified) – The data that should get stored. This can be of any data type.

Raises:

ValueError – If no datasets have been added to this dataset collection yet.
KeyError – If auxiliary data is already stored under the given name.

add_datasets(datasets)

Adds the given Dataset object(s) to this dataset collection.

Parameters:: datasets (instance of Dataset | sequence of instance of Dataset) – The instance of Dataset or the sequence of instance of Dataset that should be added to the dataset collection.
Returns:: self (instance of DatasetCollection) – This instance of DatasetCollection in order to be able to chain several add_datasets calls.

remove_dataset(name)

Removes the given dataset from the collection.

Parameters:: name (str) – The name of the dataset that should get removed.

get_dataset(name)

Retrieves a Dataset object from this dataset collection.

Parameters:: name (str) – The name of the dataset.
Returns:: dataset (Dataset instance) – The Dataset object holding all the information about the dataset.
Raises:: KeyError – If the data set of the given name is not present in this data set collection.

get_datasets(names)

Retrieves a list of Dataset objects from this dataset collection.

Parameters:: names (str | sequence of str) – The name or sequence of names of the datasets to retrieve.
Returns:: datasets (list of Dataset instances) – The list of Dataset instances for the given list of data set names.
Raises:: KeyError – If one of the requested data sets is not present in this data set collection.

set_exp_field_name_renaming_dict(d)

Sets the dictionary with the data field names of the experimental data that needs to be renamed just after loading the data. The dictionary will be set to all added data sets.

Parameters:: d (dict) – The dictionary with the old field names as keys and the new field names as values.

set_mc_field_name_renaming_dict(d)

Sets the dictionary with the data field names of the monte-carlo data that needs to be renamed just after loading the data. The dictionary will be set to all added data sets.

Parameters:: d (dict) – The dictionary with the old field names as keys and the new field names as values.

set_dataset_prop(name, value)

Sets the given property to the given name for all data sets of this data set collection.

Parameters:

name (str) – The name of the property.
value (object) – The value to set for the given property.

Raises:

KeyError – If the given property does not exist in the data sets.

define_binning(name, binedges)

Defines a binning definition and adds it to all the datasets of this dataset collection.

Parameters:

name (str) – The name of the binning definition.
binedges (sequence) – The sequence of the bin edges, that should be used for the binning.

add_data_preparation(func)

Adds the data preparation function to all the datasets of this dataset collection.

Parameters:: func (callable) – The object with call signature __call__(data) that will prepare the data after it was loaded. The argument ‘data’ is the DatasetData instance holding the experimental and monte-carlo data. This function must alter the properties of the DatasetData instance.

remove_data_preparation(key=-1)

Removes data preparation function from all the datasets of this dataset collection.

Parameters:

key (str, int, optional) – The name or the index of the data preparation function that should be removed. Default value is -1, i.e. the last added function.

Raises:

TypeError – If the type of the key argument is invalid.
IndexError – If the given key is out of range.
KeyError – If the data preparation function cannot be found.

update_version_qualifiers(verqualifiers): Updates the version qualifiers of all datasets of this dataset collection.

load_data(livetime=None, tl=None, ppbar=None, **kwargs)

Loads the data of all data sets of this data set collection.

Parameters:

livetime (float | dict of str => float | None) – If not None, uses this livetime (in days) as livetime for (all) the DatasetData instances, otherwise uses the live time from the Dataset instance. If a dictionary of data set names and floats is given, it defines the livetime for the individual data sets.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to time the data load operation.
ppbar (instance of ProgressBar | None) – The optional parent progress bar.
**kwargs – Additional keyword arguments are passed to the load_data() method of the individual datasets.

Returns:

data_dict (dictionary str => instance of DatasetData) – The dictionary with the DatasetData instance holding the data of an individual data set as value and the data set’s name as key.

class skyllh.core.dataset.DatasetData(data_exp, data_mc, livetime, **kwargs)

Bases: object

This class provides the container for the actual experimental and monte-carlo data.

Creates a new DatasetData instance.

Parameters:

data_exp (instance of DataFieldRecordArray | None) – The instance of DataFieldRecordArray holding the experimental data. This can be None for a MC-only study.
data_mc (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the monte-carlo data.
livetime (float) – The integrated livetime in days of the data.

property exp: The DataFieldRecordArray instance holding the experimental data. This is None, if there is no experimental data available.

property mc: The DataFieldRecordArray instance holding the monte-carlo data. This is None, if there is no monte-carlo data available.

property livetime: The integrated livetime in days of the data. This is None, if there is no live-time provided.

property exp_field_names: (read-only) The list of field names present in the experimental data. This is an empty list if there is no experimental data available.

property mc_field_names: (read-only) The list of field names present in the monte-carlo data.

skyllh.core.dataset.assert_data_format(dataset, data)

Checks the format of the experimental and monte-carlo data.

Parameters:

dataset (instance of Dataset) – The instance of Dataset describing the dataset and holding the local configuration.
data (instance of DatasetData) – The instance of DatasetData holding the actual experimental and simulation data of the data set.

Raises:

KeyError – If a required data field is missing.

skyllh.core.dataset.remove_events(data_exp, mjds)

Utility function to remove events having the specified MJD time stamps.

Parameters:

data_exp (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the experimental data events.
mjds (float | array of floats) – The MJD time stamps of the events, that should get removed from the experimental data array.

Returns:

data_exp (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the experimental data events with the specified events removed.

skyllh.core.dataset.generate_base_path(default_base_path, base_path=None)

Generates the base path. If base_path is None, default_base_path is used.

Parameters:

default_base_path (str) – The default base path if base_path is None.
base_path (str | None) – The user-specified base path.

Returns:

base_path (str) – The generated base path.

skyllh.core.dataset.generate_sub_path(sub_path_fmt, version, verqualifiers)

Generates the sub path of the dataset based on the given sub path format.

Parameters:

sub_path_fmt (str) – The format string of the sub path.
version (int) – The version of the dataset.
verqualifiers (dict) – The dictionary holding the version qualifiers of the dataset.

Returns:

sub_path (str) – The generated sub path.

skyllh.core.dataset.generate_data_file_root_dir(default_base_path, default_sub_path_fmt, version, verqualifiers, base_path=None, sub_path_fmt=None)

Generates the root directory of the data files based on the given base path and sub path format. If base_path is None, default_base_path is used. If sub_path_fmt is None, default_sub_path_fmt is used.

The default_sub_path_fmt and sub_path_fmt arguments can contain the following wildcards:

{version:d}
The version integer number of the dataset.

{<verqualifiers_key>:d}
The integer number of the specific version qualifier 'verqualifiers_key'.

Parameters:

default_base_path (str) – The default base path if base_path is None.
default_sub_path_fmt (str) – The default sub path format if sub_path_fmt is None.
version (int) – The version of the data sample.
verqualifiers (dict) – The dictionary holding the version qualifiers of the data sample.
base_path (str | None) – The user-specified base path.
sub_path_fmt (str | None) – The user-specified sub path format.

Returns:

root_dir (str) – The generated root directory of the data files. This will have no trailing directory separator.

skyllh.core.dataset.get_data_subset(data, livetime, t_start, t_stop)

Gets instance of DatasetData and instance of Livetime with data subsets between the given time range from t_start to t_stop.

Parameters:

data (DatasetData) – The DatasetData object.
livetime (Livetime) – The Livetime object.
t_start (float) – The MJD start time of the time range to consider.
t_end (float) – The MJD end time of the time range to consider.

Returns:

data_subset (instance of DatasetData) – The instance of DatasetData with subset of the data between the given time range from t_start to t_stop.
livetime_subset (instance of Livetime) – The instance of Livetime for a subset of the data between the given time range from t_start to t_stop.

skyllh.core.debugging module

skyllh.core.debugging.get_logger(name)

Retrieves the logger with the given name from the Python logging system.

Parameters:: name (str) – The name of the logger. Logger hierarchy is defined using dots as separators.
Returns:: logger (logging.Logger) – The Logger instance.

skyllh.core.debugging.setup_logger(name, log_level)

Initializes logger with a given name and a log level.

Parameters:

name (str) – Logger name. Loggers hierarchy is defined using dots as separators.
log_level (int) – The log level. The logging module predefines levels, e.g. logging.DEBUG.

skyllh.core.debugging.setup_console_handler(cfg, name, log_level=None, log_format=None, stream=None)

Initializes StreamHandler for a logger with a given name and sets its handling level.

Parameters:

cfg (instance of Config) – The instance of Config holding the local configuration.
name (str) – Logger name. Loggers hierarchy is defined using dots as separators.
log_level (int | None) – The log level. The logging module predefines levels, e.g. logging.DEBUG. If set to None, the log level of the logger will be used.
log_format (str | None) – The format of log records in the final output. If set to None, the log format is taken from the configuration.
stream (data stream | None) – The stream that the handler should use. Default stream is sys.stderr.

skyllh.core.debugging.setup_file_handler(cfg, name, filename, log_level=None, path=None, log_format=None, mode='a')

Initializes FileHandler for a logger with a given name and sets its handling level.

Parameters:

cfg (instance of Config) – The instance of Config holding the local configuration.
name (str) – Logger name. Loggers hierarchy is defined using dots as separators.
log_level (int | None) – The log level. There are predefined levels, e.g. logging.DEBUG. If set to None, the log level of the logger will be used.
filename (str) – The filename of the specified file which is opened and used as the stream for logging.
path (str | None) – The path under which the log file should be stored. If set to None, the project’s working directory will be used.
log_format (str | None) – The format of log records in the final output. If set to None, the log format is taken from the configuration.
mode (str) – File opening mode. Default is ‘a’ for appending.

skyllh.core.detsigyield module

class skyllh.core.detsigyield.DetSigYield(param_names, dataset, fluxmodel, livetime, **kwargs)

Bases: object

This is the abstract base class for a detector signal yield.

The detector signal yield, Y_s(p_s), is defined as the expected mean number of signal events detected by the detector from a given source with source parameters p_s.

To construct a detector signal yield object, four ingredients are needed: the dataset holding the monte-carlo data events, a signal flux model, the livetime, and a builder instance that knows how to construct the actual detector yield in an efficient way. In general, the implementation method depends on the detector, the source, the flux model with its flux model’s signal parameters, and the dataset. Hence, for a given detector, source, flux model, and dataset, an appropriate implementation method needs to be chosen.

Constructs a new detector signal yield object. It takes the monte-carlo data events, a flux model of the signal, and the live time to compute the detector signal yield.

Parameters:

param_names (sequence of str) – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.
dataset (Dataset instance) – The Dataset instance holding the monte-carlo event data.
fluxmodel (FluxModel) – The flux model instance. Must be an instance of FluxModel.
livetime (float | Livetime) – The live-time in days to use for the detector signal yield.

property param_names: The tuple of parameter names this detector signal yield instance is a function of.

property dataset: The Dataset instance, for which this detector signal yield is made for.

property fluxmodel: The flux model, which should be used to calculate the detector signal yield.

property livetime: The live-time in days.

abstract sources_to_recarray(sources)

This method is supposed to convert a (list of) source model(s) into a numpy record array that is understood by the detector signal yield class. This is for efficiency reasons only. This way the user code can pre-convert the list of sources into a numpy record array and cache the array. The fields of the array are detector signal yield implementation dependent, i.e. what kind of sources: point-like source, or extended source for instance. Because the sources usually don’t change their position in the sky, this has to be done only once.

Parameters:: sources (SourceModel | sequence of SourceModel) – The source model(s) containing the information of the source(s).
Returns:: recarr (numpy record ndarray) – The generated (N_sources,)-shaped 1D numpy record ndarray holding the information for each source.

abstract __call__(src_recarray, src_params_recarray)

Abstract method to retrieve the detector signal yield for the given sources and source parameter values.

Parameters:

src_recarray ((N_sources,)-shaped numpy record ndarray) – The numpy record array containing the information of the sources. The required fields of this record array are implementation dependent. In the most generic case for a point-like source, it must contain the following three fields: ra, dec.
src_params_recarray ((N_sources,)-shaped numpy record ndarray) – The numpy record ndarray containing the parameter values of the sources. The parameter values can be different for the different sources. The record array must contain two fields for each source parameter, one named <name> with the source’s local parameter name holding the source’s local parameter value, and one named <name:gpidx> holding the global parameter index plus one for each source value. For values mapping to non-fit parameters, the index should be negative.

Returns:

detsigyield ((N_sources,)-shaped 1D ndarray of float) – The array with the mean number of signal in the detector for each given source.
grads (dict) – The dictionary holding the gradient values for each global fit parameter. The key is the global fit parameter index and the value is the (N_sources,)-shaped numpy ndarray holding the gradient value dY_k/dp_s.

class skyllh.core.detsigyield.DetSigYieldBuilder(**kwargs)

Bases: HasConfig

Abstract base class for a builder of a detector signal yield. Via the construct_detsigyield method it creates a DetSigYield instance holding the internal objects to calculate the detector signal yield.

Constructor.

assert_types_of_construct_detsigyield_arguments(dataset, data, shgs, ppbar): Checks the types of the arguments for the construct_detsigyield method. It raises errors if the arguments have the wrong type.

get_detsigyield_construction_factory()

This method is supposed to return a callable with the call-signature

__call__(
    dataset,
    data,
    shgs,
    ppbar,
)

to construct several DetSigYield instances, one for each provided source hypo group (i.e. sources and fluxmodel). The return value of this callable must be a sequence of DetSigYield instances of the same length as the sequence of shgs.

Returns:: factory (callable | None) – This default implementation returns None, indicating that a factory is not supported by this builder.

abstract construct_detsigyield(dataset, data, shg, ppbar=None)

Abstract method to construct the DetSigYield instance. This method must be called by the derived class method implementation to ensure the compatibility check of the given flux model with the supported flux models.

Parameters:

dataset (instance of Dataset) – The instance of Dataset holding possible dataset specific settings.
data (instance of DatasetData) – The instance of DatasetData holding the monte-carlo event data.
shg (instance of SourceHypoGroup) – The instance of SourceHypoGroup (i.e. sources and flux model) for which the detector signal yield should be constructed.
ppbar (instance of ProgressBar | None) – The instance of ProgressBar of the optional parent progress bar.

Returns:

detsigyield (instance of DetSigYield) – An instance derived from DetSigYield.

class skyllh.core.detsigyield.NullDetSigYieldBuilder(cfg=None, **kwargs)

Bases: DetSigYieldBuilder

This class provides a dummy detector signal yield builder, which can be used for testing purposes, when an actual builder is not required.

Creates a new instance of NullDetSigYieldBuilder.

Parameters:: cfg (instance of Config | None) – The instance of Config holding the local configuration. Since this detector signal yield builder does nothing, this argument is optional. If not provided the default configuration is used.

construct_detsigyield(*args, **kwargs): Since this is a dummy detector signal yield builder, calling this method will raise a NotImplementedError!

skyllh.core.display module

The display module provides global settings for pretty command line displaying.

class skyllh.core.display.ANSIColors

Bases: object

This class defines the ANSI color codes, which can be used to change the text color in a terminal.

HEADER = '\x1b[95m'

OKBLUE = '\x1b[94m'

OKGREEN = '\x1b[92m'

WARNING = '\x1b[93m'

FAIL = '\x1b[91m'

ENDC = '\x1b[0m'

BOLD = '\x1b[1m'

UNDERLINE = '\x1b[4m'

skyllh.core.display.add_leading_text_line_padding(padwidth, text)

Adds leading white spaces to all the lines of the given text.

Parameters:

padwidth (int) – The width of the padding.
text (str) – The text with new line characters for each line.

Returns:

padded_text (str) – The text where each line is padded with the given number of whitespaces.

skyllh.core.event_selection module

class skyllh.core.event_selection.EventSelectionMethod(shg_mgr, **kwargs)

Bases: object

This is the abstract base class for all event selection method classes. The idea is to pre-select only events that contribute to the likelihood function, i.e. are more signal than background like. The different methods are implemented through derived classes of this base class.

Creates a new event selection method instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager | None) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances. It can be None if the event selection method does not depend on the sources.

property shg_mgr: (read-only) The instance of SourceHypoGroupManager, which defines the list of sources.

__and__(other)

Implements the AND operator (&) for creating an event selection method, which is the intersection of this event selection method and another one using the expression intersection = self & other.

Parameters:: other (instance of EventSelectionMethod) – The instance of EventSelectionMethod that is the other event selection method.
Returns:: intersection (instance of IntersectionEventSelectionMethod) – The instance of IntersectionEventSelectionMethod that creates the intersection of this event selection method and the other.

change_shg_mgr(shg_mgr)

Changes the SourceHypoGroupManager instance of the event selection method. This will also recreate the internal source numpy record array.

Parameters:: shg_mgr (instance of SourceHypoGroupManager | None) – The new SourceHypoGroupManager instance, that should be used for this event selection method. It can be None if the event selection method does not depend on the sources.

sources_to_array(sources)

This method is supposed to convert a sequence of SourceModel instances into a structured numpy ndarray with the source information in a format that is best understood by the actual event selection method.

Parameters:: sources (sequence of SourceModel) – The sequence of source models containing the necessary information of the source.
Returns:: arr (numpy record ndarray | None) – The generated numpy record ndarray holding the necessary information for each source. By default None is returned.

abstract select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

This method selects the events, which will contribute to the log-likelihood ratio function.

Parameters:

events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray of length N_events, holding the events.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray of length N_selected_events, holding the selected events, i.e. a subset of the events argument.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The two 1d ndarrays of int of length N_values, holding the indices of the sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.IntersectionEventSelectionMethod(evt_sel_method1, evt_sel_method2, **kwargs)

Bases: EventSelectionMethod

This class provides an event selection method for the intersection of two event selection methods. It can be created using the & operator: evt_sel_method1 & evt_sel_method2.

Creates a compounded event selection method of two given event selection methods.

Parameters:

evt_sel_method1 (instance of EventSelectionMethod) – The instance of EventSelectionMethod for the first event selection method.
evt_sel_method2 (instance of EventSelectionMethod) – The instance of EventSelectionMethod for the second event selection method.

property evt_sel_method1: The instance of EventSelectionMethod for the first event selection method.

property evt_sel_method2: The instance of EventSelectionMethod for the second event selection method.

change_shg_mgr(shg_mgr)

Changes the SourceHypoGroupManager instance of the event selection method. This will call the change_shg_mgr of the individual event selection methods.

Parameters:: shg_mgr (instance of SourceHypoGroupManager | None) – The new SourceHypoGroupManager instance, that should be used for this event selection method. It can be None if the event selection method does not depend on the sources.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects events by calling the select_events methods of the individual event selection methods.

Parameters:

events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the events.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (DataFieldRecordArray) – The instance of DataFieldRecordArray holding the selected events, i.e. a subset of the events argument.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of the sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.AllEventSelectionMethod(shg_mgr)

Bases: EventSelectionMethod

This event selection method selects all events.

Creates a new event selection method instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances. For this particular event selection method it has no meaning, but it is an interface parameter.

sources_to_array(sources)

Creates the source array from the given list of sources. This event selection method does not depend on the sources. Hence, None is returned.

Returns:: arr (None) – The generated numpy record ndarray holding the necessary information for each source. Since this event selection method does not depend on any source, None is returned.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects all of the given events. Hence, the returned event array is the same as the given array.

Parameters:

events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the events, for which the selection method should get applied.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (DataFieldRecordArray) – The instance of DataFieldRecordArray holding the selected events, i.e. a subset of the events argument.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.SpatialEventSelectionMethod(shg_mgr, **kwargs)

Bases: EventSelectionMethod

This abstract base class defines the base class for all spatial event selection methods.

Creates a new event selection method instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.

sources_to_array(sources)

Converts the given sequence of SourceModel instances into a structured numpy ndarray holding the necessary source information needed for this event selection method.

Parameters:: sources (sequence of SourceModel) – The sequence of source models containing the necessary information of the source.
Returns:: arr (numpy record ndarray) – The generated numpy record ndarray holding the necessary information for each source. It contains the following data fields: ‘ra’, ‘dec’.

class skyllh.core.event_selection.DecBandEventSectionMethod(shg_mgr, delta_angle)

Bases: SpatialEventSelectionMethod

This event selection method selects events within a declination band around a list of point-like source positions.

Creates and configures a spatial declination band event selection method object.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.
delta_angle (float) – The half-opening angle around the source in declination for which events should get selected.

property delta_angle: The half-opening angle around the source in declination and right-ascention for which events should get selected.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects the events within the declination band.

Parameters:

events (instance of DataFieldRecordArray) –
The instance of DataFieldRecordArray that holds the event data. The following data fields must exist:

'dec'float
The declination of the event.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding only the selected events.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.RABandEventSectionMethod(shg_mgr, delta_angle)

Bases: SpatialEventSelectionMethod

This event selection method selects events within a right-ascension band around a list of point-like source positions.

Creates and configures a right-ascension band event selection method object.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.
delta_angle (float) – The half-opening angle around the source in right-ascension for which events should get selected.

property delta_angle: The half-opening angle around the source in declination and right-ascention for which events should get selected.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects the events within the right-ascention band.

The solid angle dOmega = dRA * dSinDec = dRA * dDec * cos(dec) is a function of declination, i.e. for a constant dOmega, the right-ascension value has to change with declination.

Parameters:

events (instance of DataFieldRecordArray) –
The instance of DataFieldRecordArray that holds the event data. The following data fields must exist:

'ra'float
The right-ascention of the event.

'dec'float
The declination of the event.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding only the selected events.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of the sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.SpatialBoxEventSelectionMethod(shg_mgr, delta_angle)

Bases: SpatialEventSelectionMethod

This event selection method selects events within a spatial box in right-ascention and declination around a list of point-like source positions.

Creates and configures a spatial box event selection method object.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.
delta_angle (float) – The half-opening angle around the source for which events should get selected.

property delta_angle: The half-opening angle around the source in declination and right-ascention for which events should get selected.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects the events within the spatial box in right-ascention and declination.

The solid angle dOmega = dRA * dSinDec = dRA * dDec * cos(dec) is a function of declination, i.e. for a constant dOmega, the right-ascension value has to change with declination.

Parameters:

events (instance of DataFieldRecordArray) –
The instance of DataFieldRecordArray that holds the event data. The following data fields must exist:

'ra'float
The right-ascention of the event.

'dec'float
The declination of the event.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding only the selected events.
(src_idxs, evt_idxs) (1d ndarrays of ints | None) – The indices of sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.PsiFuncEventSelectionMethod(shg_mgr, psi_name, func, axis_name_list)

Bases: EventSelectionMethod

This event selection method selects events whose psi value, i.e. the great circle distance of the event to the source, is smaller than the value of the provided function.

Creates a new PsiFuncEventSelectionMethod instance.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.
psi_name (str) – The name of the data field that provides the psi value of the event.
func (callable) –
The function that should get evaluated for each event. The call signature must be

func(*axis_data),

where *axis_data is the event data of each required axis. The number of axes must match the provided axis names through the axis_name_list.
axis_name_list (list of str) – The list of data field names for each axis of the function func. All field names must be valid field names of the trial data’s DataFieldRecordArray instance.

property psi_name: The name of the data field that provides the psi value of the event.

property func: The function that should get evaluated for each event. The call signature must be func(*axis_data), where *axis_data is the event data of each required axis. The number of axes must match the provided axis names through the axis_name_list property.

property axis_name_list: The list of data field names for each axis of the function defined through the func property.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects the events whose psi value is smaller than the value of the predefined function.

Parameters:

events (instance of DataFieldRecordArray) –
The instance of DataFieldRecordArray that holds the event data. The following data fields must exist:

<psi_name>float
The great circle distance of the event with the source.

<axis_name(s)>float
The name of the axis required for the function func to be evaluated.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding only the selected events.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of the sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

class skyllh.core.event_selection.AngErrOfPsiEventSelectionMethod(shg_mgr, func, psi_floor=None, **kwargs)

Bases: SpatialEventSelectionMethod

This event selection method selects events within a spatial box in right-ascention and declination around a list of point-like source positions and performs an additional selection of events whose ang_err value is larger than the value of the provided function at a given psi value.

Creates and configures a spatial box and psi func event selection method object.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.
delta_angle (float) – The half-opening angle around the source for which events should get selected.
psi_name (str | None) – The name of the data field that provides the psi value of the event. If set to None, the psi value will be calculated automatically.
func (callable) –
The function that should get evaluated for each event. The call signature must be

func(psi),

where psi is the opening angle between the source and the event.
psi_floor (float | None) – The psi func event selection is excluded for events having psi value below the psi_floor. If None, set it to default 5 degrees.

property func: The function that should get evaluated for each event. The call signature must be func(*axis_data), where *axis_data is the event data of each required axis. The number of axes must match the provided axis names through the axis_name_list property.

property psi_floor: The psi func event selection is excluded for events having psi value below the psi_floor.

select_events(events, src_evt_idxs=None, ret_original_evt_idxs=False, tl=None)

Selects the events within the spatial box in right-ascention and declination and performs an additional selection of events whose ang_err value is larger than the value of the provided function at a given psi value.

The solid angle dOmega = dRA * dSinDec = dRA * dDec * cos(dec) is a function of declination, i.e. for a constant dOmega, the right-ascension value has to change with declination.

Parameters:

events (instance of DataFieldRecordArray) –
The instance of DataFieldRecordArray that holds the event data. The following data fields must exist:

'ra'float
The right-ascention of the event.

'dec'float
The declination of the event.
src_evt_idxs (2-tuple of 1d ndarrays of ints | None) – The 2-element tuple holding the two 1d ndarrays of int of length N_values, specifying to which sources the given events belong to. If set to None all given events will be considered to for all sources.
ret_original_evt_idxs (bool) – Flag if the original indices of the selected events should get returned as well.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to collect timing information about this method.

Returns:

selected_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding only the selected events.
(src_idxs, evt_idxs) (1d ndarrays of ints) – The indices of the sources and the selected events.
original_evt_idxs (1d ndarray of ints) – The (N_selected_events,)-shaped numpy ndarray holding the original indices of the selected events, if ret_original_evt_idxs is set to True.

skyllh.core.expectation_maximization module

skyllh.core.expectation_maximization.em_expectation_step(ns, mu, sigma, t, sob)

Expectation step of expectation maximization algorithm.

Parameters:

ns (instance of ndarray) – The (n_flares,)-shaped numpy ndarray holding the number of signal neutrinos, as weight for each gaussian flare.
mu (instance of ndarray) – The (n_flares,)-shaped numpy ndarray holding the mean for each gaussian flare.
sigma (instance of ndarray) – The (n_flares,)-shaped numpy ndarray holding the sigma for each gaussian flare.
t (instance of ndarray) – The (n_events,)-shaped numpy ndarray holding the time of each event.
sob (instance of ndarray) – The (n_events,)-shaped numpy ndarray holding the signal-over-background values of each event.

Returns:

expectations (instane of ndarray) – The (n_flares, n_events)-shaped numpy ndarray holding the expectation of each flare and event.
llh (float) – The log-likelihood value, which is the sum of log of the signal and background expectations.

skyllh.core.expectation_maximization.em_maximization_step(e, t)

The maximization step of the expectation maximization algorithm.

Parameters:

e (instance of ndarray) – The (n_flares, n_events)-shaped numpy ndarray holding the expectation for each event and flare.
t (1d ndarray of float) – The times of each event.

Returns:

mu (list of float) – Best fit mean time of the gaussian flare.
sigma (list of float) – Best fit sigma of the gaussian flare.
ns (list of float) – Best fit number of signal neutrinos, as weight for the gaussian flare.

skyllh.core.expectation_maximization.em_fit(x, weights, n=1, tol=1e-200, iter_max=500, weight_thresh=0, initial_width=5000, remove_x=None)

Perform the expectation maximization fit.

Parameters:

x (array of float) – The quantity to run EM on (e.g. the time if EM should find time flares).
weights (array of float) – The weights for each x value (e.g. the signal over background ratio).
n (int) – How many Gaussians flares we are looking for.
tol (float) – The stopping criteria for the expectation maximization. This is the difference in the normalized likelihood over the last 20 iterations.
iter_max (int) – The maximum number of iterations, even if stopping criteria tolerance (tol) is not yet reached.
weight_thresh (float) – Set a minimum threshold for event weights. Events with smaller weights will be removed.
initial_width (float) – The starting width for the gaussian flare in days.
remove_x (float | None) – Specific x of event that should be removed.

Returns:

mu (list of float) – The list of size n with the determined mean values.
sigma (list of float) – The list of size n with the standard deviation values.
ns (list of float) – The list of size n with the normalization factor values.

skyllh.core.flux_model module

The flux_model module contains classes for different flux models. The class for the most generic flux model is FluxModel, which is an abstract base class. It describes a mathematical function for the differential flux:

\[\frac{d^4\Phi(\alpha,\delta,E,t | \vec{p}_{\mathrm{s}})}{\mathrm{d}A \mathrm{d}\Omega \mathrm{d}E \mathrm{d}t}\]

class skyllh.core.flux_model.FluxProfile(**kwargs)

Bases: MathFunction, HasConfig

The abstract base class for a flux profile math function.

Creates a new FluxProfile instance.

class skyllh.core.flux_model.SpatialFluxProfile(angle_unit=None, **kwargs)

Bases: FluxProfile

The abstract base class for a spatial flux profile function.

Creates a new SpatialFluxProfile instance.

Parameters:: angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property angle_unit: The set unit of angle used for this spatial flux profile. If set to Ǹone the configured default angle unit for fluxes is used.

abstract __call__(ra, dec, unit=None)

This method is supposed to return the spatial profile value for the given celestrial coordinates.

Parameters:

ra (float | 1d numpy ndarray of float) – The right-ascention coordinate.
dec (float | 1d numpy ndarray of float) – The declination coordinate.
unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. If None, the set angle unit of this SpatialFluxProfile is assumed.

Returns:

values (1D numpy ndarray) – The spatial profile values.

class skyllh.core.flux_model.UnitySpatialFluxProfile(angle_unit=None, **kwargs)

Bases: SpatialFluxProfile

Spatial flux profile for the constant profile function 1 for any spatial coordinates.

Creates a new UnitySpatialFluxProfile instance.

Parameters:: angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property math_function_str: (read-only) The string representation of the mathematical function of this spatial flux profile instance.

__call__(ra, dec, unit=None)

Returns 1 as numpy ndarray in same shape as ra and dec.

Parameters:

ra (float | 1d numpy ndarray of float) – The right-ascention coordinate.
dec (float | 1d numpy ndarray of float) – The declination coordinate.
unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. By the definition of this class this argument is ignored.

Returns:

values (1D numpy ndarray) – 1 in same shape as ra and dec.

class skyllh.core.flux_model.PointSpatialFluxProfile(ra, dec, angle_unit=None, **kwargs)

Bases: SpatialFluxProfile

Spatial flux profile for a delta function at the celestrical coordinate (ra, dec).

Creates a new spatial flux profile for a point at equatorial coordinate (ra, dec).

Parameters:

ra (float | None) – The right-ascention of the point. In case it is None, the evaluation of this spatial flux profile will return zero, unless evaluated for ra=None.
dec (float | None) – The declination of the point. In case it is None, the evaluation of this spatial flux profile will return zero, unless evaluated for dec=None.
angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property ra: The right-ascention of the point. The unit is the set angle unit of this SpatialFluxProfile instance.

property dec: The declination of the point. The unit is the set angle unit of this SpatialFluxProfile instance.

property math_function_str: (read-only) The string representation of the mathematical function of this spatial flux profile instance. It is None, if the right-ascention or declination property is set to None.

__call__(ra, dec, unit=None)

Returns a numpy ndarray in same shape as ra and dec with 1 if ra equals self.ra and dec equals self.dec, and 0 otherwise.

Parameters:

ra (float | 1d numpy ndarray of float) – The right-ascention coordinate at which to evaluate the spatial flux profile. The unit must be the internally used angle unit.
dec (float | 1d numpy ndarray of float) – The declination coordinate at which to evaluate the spatial flux profile. The unit must be the internally used angle unit.
unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. If set to None, the set angle unit of this SpatialFluxProfile instance is assumed.

Returns:

value (1D numpy ndarray of int8) – A numpy ndarray in same shape as ra and dec with 1 if ra equals self.ra and dec equals self.dec, and 0 otherwise.

class skyllh.core.flux_model.EnergyFluxProfile(energy_unit=None, **kwargs)

Bases: FluxProfile

The abstract base class for an energy flux profile function.

Creates a new energy flux profile with a given energy unit to be used for flux calculation.

Parameters:: energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property energy_unit: The unit of energy used for the flux profile calculation.

abstract __call__(E, unit=None)

This method is supposed to return the energy profile value for the given energy value.

Parameters:

E (float | 1d numpy ndarray of float) – The energy value for which to retrieve the energy profile value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energy. If set to None, the set energy unit of this EnergyFluxProfile is assumed.

Returns:

values (1D numpy ndarray of float) – The energy profile values for the given energies.

get_integral(E1, E2, unit=None)

This is the default implementation for calculating the integral value of this energy flux profile in the range [E1, E2].

Note

This implementation utilizes the scipy.integrate.quad function to perform a generic numeric integration. Hence, this implementation is slow and should be reimplemented by the derived class if an analytic integral form is available.

Parameters:

E1 (float | 1d numpy ndarray of float) – The lower energy bound of the integration.
E2 (float | 1d numpy ndarray of float) – The upper energy bound of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

integral (instance of ndarray) – The (n,)-shaped numpy ndarray holding the integral values of the given integral ranges.

class skyllh.core.flux_model.UnityEnergyFluxProfile(energy_unit=None, **kwargs)

Bases: EnergyFluxProfile

Energy flux profile for the constant function 1.

Creates a new UnityEnergyFluxProfile instance.

Parameters:: energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property math_function_str: (read-only) The string representation of the mathematical function of this energy flux profile.

__call__(E, unit=None)

Returns 1 as numpy ndarray in some shape as E.

Parameters:

E (float | 1D numpy ndarray of float) – The energy value for which to retrieve the energy profile value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. By definition of this specific class, this argument is ignored.

Returns:

values (1D numpy ndarray of int8) – 1 in same shape as E.

get_integral(E1, E2, unit=None)

Computes the integral of this energy flux profile in the range [E1, E2], which by definition is E2 - E1.

Parameters:

E1 (float | 1d numpy ndarray of float) – The lower energy bound of the integration.
E2 (float | 1d numpy ndarray of float) – The upper energy bound of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

integral (1d ndarray of float) – The integral values of the given integral ranges.

class skyllh.core.flux_model.PowerLawEnergyFluxProfile(E0, gamma, energy_unit=None, **kwargs)

Bases: EnergyFluxProfile

Energy flux profile for a power law profile with a reference energy E0 and a spectral index gamma.

\[(E / E_0)^{-\gamma}\]

Creates a new power law flux profile with the reference energy E0 and spectral index gamma.

Parameters:

E0 (castable to float) – The reference energy.
gamma (castable to float) – The spectral index.
energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property E0: The reference energy in the set energy unit of this EnergyFluxProfile instance.

property gamma: The spectral index.

property math_function_str: (read-only) The string representation of this energy flux profile instance.

__call__(E, unit=None)

Returns the power law values for the given energies as numpy ndarray in same shape as E.

Parameters:

E (float | 1D numpy ndarray of float) – The energy value for which to retrieve the energy profile value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of float) – The energy profile values for the given energies.

get_integral(E1, E2, unit=None)

Computes the integral value of this power-law energy flux profile in the range [E1, E2].

Parameters:

E1 (float | 1d numpy ndarray of float) – The lower energy bound of the integration.
E2 (float | 1d numpy ndarray of float) – The upper energy bound of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

integral (1d ndarray of float) – The integral values of the given integral ranges.

class skyllh.core.flux_model.CutoffPowerLawEnergyFluxProfile(E0, gamma, Ecut, energy_unit=None, **kwargs)

Bases: PowerLawEnergyFluxProfile

Cut-off power law energy flux profile of the form

\[(E / E_0)^{-\gamma} \exp(-E/E_{\mathrm{cut}})\]

Creates a new cut-off power law flux profile with the reference energy E0, spectral index gamma, and cut-off energy Ecut.

Parameters:

E0 (castable to float) – The reference energy.
gamma (castable to float) – The spectral index.
Ecut (castable to float) – The cut-off energy.
energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property Ecut: The energy cut value.

property math_function_str: (read-only) The string representation of this energy flux profile instance.

__call__(E, unit=None)

Returns the cut-off power law values for the given energies as numpy ndarray in the same shape as E.

Parameters:

E (float | instance of numpy ndarray) – The energy value(s) for which to retrieve the energy profile value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

values (instance of numpy ndarray) – The energy profile values for the given energies.

class skyllh.core.flux_model.LogParabolaPowerLawEnergyFluxProfile(E0, alpha, beta, energy_unit=None, **kwargs)

Bases: PowerLawEnergyFluxProfile

This class provides an energy flux profile for a power-law with a spectral index that varies as a log parabola in energy of the form

\[\frac{E}{E_0}^{-\left(\alpha + \beta\log(\frac{E}{E_0})\right)}\]

Parameters:

E0 (castable to float) – The reference energy.
alpha (float) – The alpha parameter of the log-parabola spectral index.
beta (float) – The beta parameter of the log-parabola spectral index.
energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property alpha: The alpha parameter of the log-parabola spectral index.

property beta: The beta parameter of the log-parabola spectral index.

property math_function_str: (read-only) The string representation of this energy flux profile instance.

__call__(E, unit=None)

Returns the log-parabola power-law values for the given energies as numpy ndarray in the same shape as E.

Parameters:

E (float | instance of numpy ndarray) – The energy value(s) for which to retrieve the energy profile value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

values (instance of numpy ndarray) – The energy profile values for the given energies.

class skyllh.core.flux_model.PhotosplineEnergyFluxProfile(**kwargs)

Bases: EnergyFluxProfile

The abstract base class for an energy flux profile based on a photospline.

Creates a new energy flux profile with a given energy unit to be used for flux calculation.

Parameters:: energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property splinetable: The instance of photospline.SplineTable that describes the neutrino energy flux profile as function of neutrino energy via B-spline interpolation.

property crit_log10_energy_lower: The lower energy bound of the spline’s support.

property crit_log10_energy_upper: The upper energy bound of the spline’s support.

class skyllh.core.flux_model.TimeFluxProfile(t_start=-inf, t_stop=inf, time_unit=None, **kwargs)

Bases: FluxProfile

The abstract base class for a time flux profile function.

Creates a new time flux profile instance.

Parameters:

t_start (float) – The start time of the time profile. If set to -inf, it means, that the profile starts at the beginning of the entire time-span of the dataset.
t_stop (float) – The stop time of the time profile. If set to +inf, it means, that the profile ends at the end of the entire time-span of the dataset.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property t_start: The start time of the time profile. Can be -inf which means, that the profile starts at the beginning of the entire dataset.

property t_stop: The stop time of the time profile. Can be +inf which means, that the profile ends at the end of the entire dataset.

property duration: (read-only) The duration of the time profile.

property time_unit: The unit of time used for the flux profile calculation.

get_total_integral()

Calculates the total integral of the time profile from t_start to t_stop.

Returns:: integral (float) – The integral value of the entire time profile. The value is in the set time unit of this TimeFluxProfile instance.

abstract __call__(t, unit=None)

This method is supposed to return the time profile value for the given times.

Parameters:

t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of float) – The time profile values.

abstract move(dt, unit=None)

Abstract method to move the time profile by the given amount of time.

Parameters:

dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to Ǹone, the set time unit of this TimeFluxProfile instance is assumed.

abstract get_integral(t1, t2, unit=None)

This method is supposed to calculate the integral of the time profile from time t1 to time t2.

Parameters:

t1 (float | array of float) – The start time of the integration.
t2 (float | array of float) – The end time of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to Ǹone, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s) of the time profile. The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.core.flux_model.UnityTimeFluxProfile(time_unit=None, **kwargs)

Bases: TimeFluxProfile

Time flux profile for the constant profile function 1.

Creates a new instance of UnityTimeFluxProfile.

Parameters:: time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property math_function_str: The string showing the mathematical function of this MathFunction.

__call__(t, unit=None)

Returns 1 as numpy ndarray in same shape as t.

Parameters:

t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. By definition of this specific class, this argument is ignored.

Returns:

values (1D numpy ndarray of int8) – 1 in same shape as t.

move(dt, unit=None)

Moves the time profile by the given amount of time. By definition this method does nothing, because the profile is 1 over the entire dataset time range.

Parameters:

dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the time profile from time t1 to time t2.

Parameters:

t1 (float | array of float) – The start time of the integration.
t2 (float | array of float) – The end time of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s) of the time profile. The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.core.flux_model.BoxTimeFluxProfile(t0, tw, time_unit=None, **kwargs)

Bases: TimeFluxProfile

This class describes a box-shaped time flux profile. It has the following parameters:

t0float
The mid time of the box profile.

twfloat
The width of the box profile.

The box is centered at t0 and extends to +/-tw/2 around t0.

Creates a new box-shaped time profile instance.

Parameters:

t0 (float) – The mid time of the box profile.
tw (float) – The width of the box profile.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

classmethod from_start_and_stop_time(start, stop, time_unit=None, **kwargs)

Constructs a BoxTimeFluxProfile instance from the given start and stop time.

Parameters:

start (float) – The start time of the box profile.
stop (float) – The stop time of the box profile.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.
**kwargs – Additional keyword arguments, which are passed to the constructor of the BoxTimeFluxProfile class.

Returns:

profile (instance of BoxTimeFluxProfile) – The newly created instance of BoxTimeFluxProfile.

property t0: The time of the mid point of the box. The value is in the set time unit of this TimeFluxProfile instance.

property tw: The time width of the box. The value is in the set time unit of this TimeFluxProfile instance.

property math_function_str: The string representation of the mathematical function of this TimeFluxProfile instance.

__call__(t, unit=None)

Returns 1 for all t within the interval [t0-tw/2; t0+tw/2], and 0 otherwise.

Parameters:

t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of int8) – The value(s) of the time flux profile for the given time(s).

cdf(t, unit=None)

Calculates the cumulative distribution function value for the given time values t.

Parameters:

t (float | instance of numpy ndarray) – The (N_times,)-shaped numpy ndarray holding the time values for which to calculate the CDF values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile is assumed.

Returns:

values (instance of numpy ndarray) – The (N_times,)-shaped numpy ndarray holding the cumulative distribution function values for each time t.

move(dt, unit=None)

Moves the box-shaped time profile by the time difference dt.

Parameters:

dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.
unit (instance of astropy.units.UnitBase | None) – The unit of dt. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the box-shaped time flux profile from time t1 to time t2.

Parameters:

t1 (float | array of float) – The start time(s) of the integration.
t2 (float | array of float) – The end time(s) of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s). The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.core.flux_model.GaussianTimeFluxProfile(t0, sigma_t, tol=1e-12, time_unit=None, **kwargs)

Bases: TimeFluxProfile

This class describes a gaussian-shaped time flux profile. It has the following parameters:

t0float
The mid time of the gaussian profile.

sigma_tfloat
The one-sigma width of the gaussian profile.

Creates a new gaussian-shaped time flux profile instance.

Parameters:

t0 (float) – The mid time of the gaussian profile.
sigma_t (float) – The one-sigma width of the gaussian profile.
tol (float) – The tolerance of the gaussian value. This defines the start and end time of the gaussian profile.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property math_function_str: The string showing the mathematical function of this MathFunction.

property t0: The time of the mid point of the gaussian profile. The unit of the value is the set time unit of this TimeFluxProfile instance.

property sigma_t: The one-sigma width of the gaussian profile. The unit of the value is the set time unit of this TimeFluxProfile instance.

__call__(t, unit=None)

Returns the gaussian profile value for the given time t.

Parameters:

t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile is assumed.

Returns:

values (1D numpy ndarray of float) – The value(s) of the time flux profile for the given time(s).

cdf(t, unit=None)

Calculates the cumulative distribution function values for the given time values t.

Parameters:

t (float | instance of numpy ndarray) – The (N_times,)-shaped numpy ndarray holding the time values for which to calculate the CDF values.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile is assumed.

Returns:

values (instance of numpy ndarray) – The (N_times,)-shaped numpy ndarray holding the cumulative distribution function values for each time t.

move(dt, unit=None)

Moves the gaussian time profile by the given amount of time.

Parameters:

dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.
unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to None, the set time unit of this TimeFluxProfile is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the gaussian time profile from time t1 to time t2.

Parameters:

t1 (float | array of float) – The start time(s) of the integration.
t2 (float | array of float) – The end time(s) of the integration.
unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s). The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.core.flux_model.FluxModel(angle_unit=None, energy_unit=None, length_unit=None, time_unit=None, **kwargs)

Bases: MathFunction, HasConfig, Model

Abstract base class for all flux models of the form

\[\Phi_S(\alpha,\delta,E,t | \vec{x}_s,\vec{p}_s).\]

This base class defines the units used for the flux calculation. The unit of the flux is ([angle]^{-2} [energy]^{-1} [length]^{-2} [time]^{-1}).

At this point the functional form of the flux model is not yet defined.

Creates a new FluxModel instance and defines the user-defined units.

Parameters:

angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to None, the configured default angle unit for fluxes is used.
energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.
length_unit (instance of astropy.units.UnitBase | None) – The used unit for length. If set to None, the configured default length unit for fluxes is used.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

static get_default_units(cfg)

Returns the configured default units for flux models.

Parameters:: cfg (instance of Config) – The instance of Config holding the local configuration.
Returns:: units_dict (dict) – The dictionary holding the configured default units used for flux models.

property angle_unit: The unit of angle used for the flux calculation.

property energy_unit: The unit of energy used for the flux calculation.

property length_unit: The unit of length used for the flux calculation.

property time_unit: The unit of time used for the flux calculation.

property unit_str: The string representation of the flux unit.

property unit_latex_str: The latex string representation of the flux unit.

abstract __call__(ra=None, dec=None, E=None, t=None, angle_unit=None, energy_unit=None, time_unit=None)

The call operator to retrieve a flux value for a given celestrial position, energy, and observation time.

Parameters:

ra (float | (Ncoord,)-shaped 1D numpy ndarray of float) – The right-ascention coordinate for which to retrieve the flux value.
dec (float | (Ncoord,)-shaped 1D numpy ndarray of float) – The declination coordinate for which to retrieve the flux value.
E (float | (Nenergy,)-shaped 1D numpy ndarray of float) – The energy for which to retrieve the flux value.
t (float | (Ntime,)-shaped 1D numpy ndarray of float) – The observation time for which to retrieve the flux value.
angle_unit (instance of astropy.units.UnitBase | None) – The unit of the given angles. If None, the set angle unit of the flux model is assumed.
energy_unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If None, the set energy unit of the flux model is assumed.
time_unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If None, the set time unit of the flux model is assumed.

Returns:

flux ((Ncoord,Nenergy,Ntime)-shaped ndarray of float) – The flux values are in unit of the set flux model units [energy]^{-1} [angle]^{-2} [length]^{-2} [time]^{-1}.

to_internal_flux_unit()

Calculates the conversion factor to convert the flux unit of this flux model instance to the SkyLLH internally used flux unit.

Returns:: factor (float) – The conversion factor.

class skyllh.core.flux_model.NullFluxModel(*args, cfg=None, **kwargs)

Bases: FluxModel

This class provides a dummy flux model class, which can be used for testing purposes, in cases where an actual flux model is not required but the framework interface requires one.

Creates a new instance of NullFluxModel.

Parameters:: cfg (instance of Config | None) – The instance of Config holding the local configuration. Since this flux model does nothing, this argument is optional. If not provided the default configuration is used.

math_function_str(): Since this is a dummy flux model, calling this method will raise a NotImplementedError.

__call__(*args, **kwargs): Since this is a dummy flux model, calling this method will raise a NotImplementedError.

class skyllh.core.flux_model.FactorizedFluxModel(Phi0, spatial_profile, energy_profile, time_profile, length_unit=None, **kwargs)

Bases: FluxModel

This class describes a flux model where the spatial, energy, and time profiles of the source factorize. That means the flux can be written as:

\[\Phi(\alpha,\delta,E,t | \vec{p}_\mathrm{s}) = \Phi_0 \Psi(\alpha,\delta|\vec{p}_\mathrm{s}) \epsilon(E|\vec{p}_\mathrm{s}) T(t|\vec{p}_\mathrm{s})\]

where, \(\Phi_0\) is the normalization constant of the flux, and \(\Psi\), \(\epsilon\), and \(T\) are the spatial, energy, and time profiles of the flux given the source parameters \(\vec{p}_\mathrm{s}\), respectively.

Creates a new factorized flux model.

Parameters:

Phi0 (float) – The flux normalization constant.
spatial_profile (instance of SpatialFluxProfile | None) – The SpatialFluxProfile instance providing the spatial profile function of the flux. If set to None, an instance of UnitySpatialFluxProfile will be used, which represents the constant function 1.
energy_profile (instance of EnergyFluxProfile | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.
time_profile (instance of TimeFluxProfile | None) – The TimeFluxProfile instance providing the time profile function of the flux. If set to None, an instance of UnityTimeFluxProfile will be used, which represents the constant function 1.
length_unit (instance of astropy.units.UnitBase | None) – The used unit for length. If set to None, the configured default length unit for fluxes is used.

property Phi0: The flux normalization constant. The unit of this normalization constant is ([angle]^{-2} [energy]^{-1} [length]^{-2} [time]^{-1}).

property spatial_profile: Instance of SpatialFluxProfile describing the spatial profile of the flux.

property energy_profile: Instance of EnergyFluxProfile describing the energy profile of the flux.

property time_profile: Instance of TimeFluxProfile describing the time profile of the flux.

property math_function_str: The string showing the mathematical function of the flux.

property angle_unit: The unit of angle used for the flux calculation. The unit is taken and set from and to the set spatial flux profile, respectively.

property energy_unit: The unit of energy used for the flux calculation. The unit is taken and set from and to the set energy flux profile, respectively.

property time_unit: The unit of time used for the flux calculation. The unit is taken and set from and to the set time flux profile, respectively.

property param_names: The tuple holding the names of the math function’s parameters. This is the total set of parameter names for all flux profiles of this FactorizedFluxModel instance.

__call__(ra=None, dec=None, E=None, t=None, angle_unit=None, energy_unit=None, time_unit=None)

Calculates the flux values for the given celestrial positions, energies, and observation times.

Parameters:

ra (float | (Ncoord,)-shaped 1d numpy ndarray of float | None) – The right-ascention coordinate for which to retrieve the flux value.
dec (float | (Ncoord,)-shaped 1d numpy ndarray of float | None) – The declination coordinate for which to retrieve the flux value.
E (float | (Nenergy,)-shaped 1d numpy ndarray of float | None) – The energy for which to retrieve the flux value.
t (float | (Ntime,)-shaped 1d numpy ndarray of float | None) – The observation time for which to retrieve the flux value.
angle_unit (instance of astropy.units.UnitBase | None) – The unit of the given angles. If None, the set angle unit of the spatial flux profile is assumed.
energy_unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If None, the set energy unit of the energy flux profile is assumed.
time_unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If None, the set time unit of the time flux profile is assumed.

Returns:

flux ((Ncoord,Nenergy,Ntime)-shaped ndarray of float) – The flux values are in unit [energy]^{-1} [angle]^{-2} [length]^{-2} [time]^{-1}.

get_param(name)

Retrieves the value of the given parameter. It returns np.nan if the parameter does not exist.

Parameters:: name (str) – The name of the parameter.
Returns:: value (float | np.nan) – The value of the parameter.

set_params(pdict)

Sets the parameters of the flux model. For this factorized flux model it means that it sets the parameters of the spatial, energy, and time profiles.

Parameters:: pdict (dict) – The flux parameter dictionary.
Returns:: updated (bool) – Flag if parameter values were actually updated.

class skyllh.core.flux_model.PointlikeFFM(Phi0, energy_profile, time_profile, ra=None, dec=None, angle_unit=None, length_unit=None, **kwargs)

Bases: FactorizedFluxModel, IsPointlike

This class describes a factorized flux model (FFM), where the spatial profile is modeled as a point. This class provides the base class for a flux model of a point-like source.

Creates a new factorized flux model for a point-like source.

Parameters:

Phi0 (float) – The flux normalization constant in unit of flux.
energy_profile (instance of EnergyFluxProfile | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.
time_profile (instance of TimeFluxProfile | None) – The TimeFluxProfile instance providing the time profile function of the flux. If set to None, an instance of UnityTimeFluxProfile will be used, which represents the constant function 1.
ra (float | None) – The right-ascention of the point.
dec (float | None) – The declination of the point.
angle_unit (instance of astropy.units.UnitBase | None) – The unit for angles used for the flux unit. If set to None, the configured internal angle unit is used.
length_unit (instance of astropy.units.UnitBase | None) – The unit for length used for the flux unit. If set to None, the configured internal length unit is used.

property unit_str: The string representation of the flux unit.

property unit_latex_str: The latex string representation of the flux unit.

class skyllh.core.flux_model.SteadyPointlikeFFM(Phi0, energy_profile, ra=None, dec=None, angle_unit=None, length_unit=None, time_unit=None, **kwargs)

Bases: PointlikeFFM

This class describes a factorized flux model (FFM), where the spatial profile is modeled as a point and the time profile as constant 1. It is derived from the PointlikeFFM class.

Creates a new factorized flux model for a point-like source with no time dependance.

Parameters:

Phi0 (float) – The flux normalization constant.
energy_profile (instance of EnergyFluxProfile | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.
ra (float | None) – The right-ascention of the point.
dec (float | None) – The declination of the point.
angle_unit (instance of astropy.units.UnitBase | None) – The unit for angles used for the flux unit. If set to None, the configured default angle unit for fluxes is used.
length_unit (instance of astropy.units.UnitBase | None) – The unit for length used for the flux unit. If set to None, the configured default length unit for fluxes is used.
time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

skyllh.core.interpolate module

This module provides functionality for interpolation.

class skyllh.core.interpolate.GridManifoldInterpolationMethod(func, param_grid_set, **kwargs)

Bases: object

This is an abstract base class for implementing a method to interpolate a manifold that is defined on a grid of parameter values. In general the number of parameters can be arbitrary and hence the manifold’s dimensionality can be arbitrary, too. However, in practice the interpolation on a multi-dimensional manifold can be rather difficult. Nevertheless, we provide this interface to allow for manifold grids with different dimensionality.

Constructor for a GridManifoldInterpolationMethod object. It must be called by the derived class.

Parameters:

func (callable R^D -> R) –
The function that takes D parameter grid values as input and returns the value of the D-dimensional manifold at this point for each given trial event and source. The call signature of func must be:

__call__(tdm, eventdata, gridparams_recarray, n_values, **kwargs)

The arguments are as follows:

tdminstance of TrialDataManager
The TrialDataManager instance holding the trial event data.

eventdatainstance of numpy ndarray
A two-dimensional (V,N_events)-shaped numpy ndarray holding the event data, where N_events is the number of trial events, and V the dimensionality of the event data.

gridparams_recarrayinstance of numpy.ndarray
The structured numpy ndarray of length len(src_idxs) with the D parameter names and values on the grid for all sources.

n_valuesint
The length of the output numpy ndarray of shape (n_values,).

**kwargs
Additional keyword arguments required by func.

The return value of func should be the (n_values,)-shaped one-dimensional ndarray holding the values for each set of parameter values of the sources given via the gridparams_recarray. The length of the array, i.e. n_values, depends on the src_evt_idx property of the TrialDataManager. In the worst case n_values is N_sources * N_events.
param_grid_set (instance of ParameterGrid | instance of ParameterGridSet) – The set of D parameter grids. This defines the grid of the manifold.

property func: The R^d -> R manifold function.

property param_grid_set: The ParameterGridSet instance defining the set of D parameter grids. This defines the grid of the manifold.

property ndim: (read-only) The dimensionality of the manifold.

abstract __call__(tdm, eventdata, params_recarray, **kwargs)

Retrieves the interpolated value of the manifold at the D-dimensional point params_recarray for all given events and sources, along with the D gradients, i.e. partial derivatives.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (numpy ndarray) – The 2D (V,N_events)-shaped numpy ndarray holding the event data, where N_events is the number of trial events, and V the dimensionality of the event data.
params_recarray (instance of numpy record ndarray) – The structured numpy ndarray holding the N_sources set of parameter names and values, that define the point (for each source) on the manifold for which the value should get calculated for each event.
**kwargs – Additional keyword arguments required by the function func.

Returns:

values (instance of numpy.ndarray) – The (N,)-shaped numpy ndarray holding the interpolated manifold values for the given events and sources.
grads (instance of numpy.ndarray) – The (D,N)-shaped numpy ndarray holding the D manifold gradients for the N given values, where D is the number of parameters. The order of the D parameters is defined by the ParameterGridSet that has been provided at construction time of this interpolation method object.

class skyllh.core.interpolate.NullGridManifoldInterpolationMethod(func, param_grid_set, **kwargs)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method performs no interpolation. When the __call__() method is called, it rounds the parameter values to their nearest grid point values. All gradients are set to zero.

Creates a new NullGridManifoldInterpolationMethod instance.

Parameters:

func (callable R^d -> R) – The function that takes d parameter grid values as input and returns the value of the d-dimensional manifold at this point for each given trial event and source. See the documentation of the GridManifoldInterpolationMethod class for more details.
param_grid_set (instance of ParameterGrid | instance of ParameterGridSet) – The set of d parameter grids. This defines the grid of the manifold.

__call__(tdm, eventdata, params_recarray, **kwargs)

Calculates the non-interpolated manifold value and its gradient (zero) for each given event and source at the points given by params_recarray.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (instance of numpy.ndarray) – The (V,N_events)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params_recarray (instance of numpy.ndarray) – The structured numpy ndarray of length N_sources holding the parameter names and values of the sources, defining the point on the manifold for which the values should get calculated.
**kwargs – Additional keyword arguments required by the function func.

Returns:

values (instance of numpy.ndarray) – The (N,)-shaped numpy ndarray holding the interpolated manifold values for the given events and sources.
grads (instance of numpy.ndarray) – The (D,N)-shaped ndarray of float holding the D manifold gradients for the N values, where D is the number of parameters of the manifold. By definition, all gradients are zero.

class skyllh.core.interpolate.Linear1DGridManifoldInterpolationMethod(func, param_grid_set, **kwargs)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method interpolates the 1-dimensional grid manifold using a line.

Creates a new Linear1DGridManifoldInterpolationMethod instance.

Parameters:

func (callable R -> R) – The function that takes the parameter grid value as input and returns the value of the 1-dimensional manifold at this point for each given source and trial event. See the documentation of the GridManifoldInterpolationMethod class for more details.
param_grid_set (instance of ParameterGrid | instance of ParameterGridSet) – The one parameter grid. This defines the grid of the manifold.

__call__(tdm, eventdata, params_recarray, **kwargs)

Calculates the interpolated manifold value and its gradient for each given source and trial event at the point params_recarray.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (instance of numpy ndarray) – The (V,N_events)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params_recarray (numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values for each source, defining the point on the manifold for which the value should get calculated. This record ndarray can be of length 1. In that case the single set of parameters is used for all sources.
**kwargs – Additional keyword arguments required by the function func.

Returns:

values (instance of numpy.ndarray) – The (N_values,)-shaped numpy ndarray of float holding the interpolated manifold values for all sources and trial events.
grads (instance of numpy.ndarray) – The (D,N_values)-shaped numpy ndarray of float holding the D manifold gradients for the N_values values for all sources and trial events, where D is the number of interpolation parameters.

class skyllh.core.interpolate.Parabola1DGridManifoldInterpolationMethod(func, param_grid_set, **kwargs)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method interpolates the 1-dimensional grid manifold using a parabola.

Creates a new Parabola1DGridManifoldInterpolationMethod instance.

Parameters:

func (callable R -> R) – The function that takes the parameter grid value as input and returns the value of the 1-dimensional manifold at this point for each given source and trial event. See the documentation of the GridManifoldInterpolationMethod class for more details.
param_grid_set (instance of ParameterGrid | instance of ParameterGridSet) – The one parameter grid. This defines the grid of the manifold.

__call__(tdm, eventdata, params_recarray, **kwargs)

Calculates the interpolated manifold value and its gradient for each given source and trial event at the point params_recarray.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (instance of numpy ndarray) – The (V,N_events)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params_recarray (numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values for each source, defining the point on the manifold for which the value should get calculated. This record ndarray can be of length 1. In that case the single set of parameters is used for all sources.
**kwargs – Additional keyword arguments required by the function func.

Returns:

values ((N_values,) ndarray of float) – The interpolated manifold value for the N given events.
grads ((D,N_values) ndarray of float) – The D manifold gradients for the N given events, where D is the number of parameters.

skyllh.core.livetime module

The livetime module provides general functionality for detector up-time.

class skyllh.core.livetime.Livetime(uptime_mjd_intervals_arr, **kwargs)

Bases: object

The Livetime class defines an interface to query the up-time of the detector.

Creates a new Livetime object from a (N,2)-shaped ndarray holding the uptime intervals.

Parameters:

uptime_mjd_intervals_arr ((N,2)-shaped ndarray) –

The (N,2)-shaped ndarray holding the start and end times of each up-time interval.

Note 1: The intervals must be sorted ascedent in time.

Note 2: By definition the lower edge is included in the interval,: whereas the upper edge is excluded from the interval.

Note 3: The intervals must not overlap.

The integrity of the internal mjd interval array will be ensured by the property setter method of uptime_mjd_intervals_arr by calling the assert_mjd_intervals_integrity method.

static get_integrated_livetime(livetime)

Gets the integrated live-time from the given livetime argument, which is either a scalar value or an instance of Livetime.

Parameters:: livetime (float | Livetime instance) – The live-time in days as float, or an instance of Livetime.
Returns:: intgrated_livetime (float) – The integrated live-time.

assert_mjd_intervals_integrity(arr)

Checks if the given MJD interval array conforms with all its data requirements.

Parameters:

arr (instance of numpy ndarray) – The (N,2)-shaped numpy ndarray holding the up-time intervals.

Raises:

TypeError – If the data array is not a float64 array.
ValueError – If the data integrity is broken.

property uptime_mjd_intervals_arr: The Nx2 numpy ndarray holding the up-time intervals of the detector. The first and second elements of the second axis is the start and stop time of the up-time interval, respectively.

property n_uptime_mjd_intervals: The number of on-time intervals defined.

property livetime: The integrated live-time in days, based on the internal up-time time intervals.

property time_window: (read-only) The two-element tuple holding the time window which is spanned by all the MJD uptime intervals. By definition this included possible detector down-time periods.

property time_start: (read-only) The start time of the detector live-time.

property time_stop: (read-only) The stop time of the detector live-time.

get_uptime_intervals_between(t_start, t_end)

Creates a (N,2)-shaped ndarray holding the on-time detector intervals between the given time range from t_start to t_end.

Parameters:

t_start (float) – The MJD start time of the time range to consider. This might be the lower bound of the first on-time interval.
t_end (float) – The MJD end time of the time range to consider. This might be the upper bound of the last on-time interval.

Returns:

ontime_intervals ((N,2)-shaped ndarray) – The (N,2)-shaped ndarray holding the on-time detector intervals.

get_livetime_upto(mjd)

Calculates the cumulative detector livetime up to the given time.

Parameters:: mjd (float | array of floats) – The time in MJD up to which the detector livetime should be calculated.
Returns:: livetimes (float | ndarray of floats) – The ndarray holding the cumulative detector livetime corresponding to the the given MJD times.

is_on(mjd)

Checks if the detector is on at the given MJD time. MJD times outside any live-time interval will be masked as False.

Parameters:: mjd (float | sequence of float) – The time in MJD.
Returns:: is_on (array of bool) – True if the detector was on at the given time.

draw_ontimes(rss, size, t_min=None, t_max=None)

Draws random MJD times based on the detector on-time intervals.

Parameters:

rss (RandomStateService) – The skyllh RandomStateService instance to use for drawing random numbers from.
size (int) – The number of random MJD times to generate.
t_min (float) – The optional minimal time to consider. If set to None, the start time of this Livetime instance will be used.
t_max (float) – The optional maximal time to consider. If set to None, the end time of this Livetime instance will be used.

Returns:

ontimes (ndarray) – The 1d array holding the generated MJD times.

skyllh.core.llh module

The llh module provides classes for implementing a log-likelihood function. In general these should be detector independent, because they implement the pure math of the log-likelihood function.

class skyllh.core.llh.LLH(pmm, shg_mgr, minimizer=None, **kwargs)

Bases: HasConfig

Abstract base class for a log-likelihood (LLH) function.

Creates a new LLH function instance.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global parameters to local parameters of individual models.
shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the source hypothesis groups.
minimizer (instance of Minimizer | None) – The optional instance of Minimizer that should be used to minimize the negative of this log-likelihood function.

property pmm: The instance of ParameterModelMapper providing the mapping of the global parameters to local parameters of the individual models.

property shg_mgr: The instance of SourceHypoGroupManager that defines the source hypothesis groups.

property minimizer: The instance of Minimizer used to minimize the negative of the log-likelihood function. This can be None, if no minimizer was specified.

change_shg_mgr(shg_mgr)

Changes the source hypothesis group manager of this LL function.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

abstract initialize_for_new_trial(tdm, tl=None, **kwargs)

This method will be called after new trial data has been initialized to the trial data manager. Derived classes can make use of this call hook to perform LLH function specific trial initialization.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for timing measurements.

abstract evaluate(tdm, fitparam_values, src_params_recarray=None, tl=None)

This method evaluates the LLH function for the given set of fit parameter values.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data.
fitparam_values (instance of numpy.ndarray) – The (N_fitparams,)-shaped numpy.ndarray holding the current values of the global fit parameters.
src_params_recarray (instance of numpy.ndarray | None) – The structured instance of numpy.ndarray of length N_sources holding the parameter names and values of all sources. If set to None it will be created automatically from the fitparam_values array. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing.

Returns:

log_lh (float) – The value of the LLH function.
grads (instance of numpy.ndarray) – The (N_fitparams,)-shaped numpy.ndarray holding the gradient value for each global fit parameter.

class skyllh.core.llh.EvtProbLLH(pmm, shg_mgr, sig_pdf, bkg_pdf, evtp_name_fmt='p{i:d}', minimizer=None, **kwargs)

Bases: LLH

This class provides the following log-likelihood function:

\[\log(L(\vec{p},\gamma|\vec{x})) = \sum_{i=1}^{N}\log \left[ p_{i} \mathcal{S}(x_{i}|\gamma) + (1-p_{i}) \mathcal{B}(x_{i}) \right],\]

where the vector \(\vec{p}\) of length \(N\) contains a probability for each event, \(\gamma\) is an additional parameter, and the vector \(\vec{x}\) of length \(N\) contains the data values of each event. The probability density functions \(\mathcal{S}\) and \(\mathcal{B}\) are the signal and background PDFs, respectively.

The gradient \(\partial \log(L)/\partial p_i\) is given as

\[\frac{\partial \log(L)}{\partial p_i} = \frac {\mathcal{S}(x_{i}|\gamma) - \mathcal{B}(x_{i})} {p_i\mathcal{S}(x_{i}|\gamma) + (1-p_i)\mathcal{B}(x_{i})}\]

The gradient \(\partial \log(L)/\partial \gamma\) is given as

\[\frac{\partial \log(L)}{\partial \gamma} = \sum_{i=1}^{N} \frac {p_i \frac{\partial \mathcal{S}(x_{i}|\gamma)}{\partial \gamma}} {p_i\mathcal{S}(x_{i}|\gamma) + (1-p_i)\mathcal{B}(x_{i})}\]

Warning

This LH function works only for single sources and with no applied event selection!

Creates a new instance of EvtProbLLH.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global parameters to local parameters of individual models.
shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the source hypothesis groups.
sig_pdf (instance of PDF and IsSignalPDF) – The signal PDF, which must be an instance of PDF and IsSignalPDF.
bkg_pdf (instance of PDF and IsBackgroundPDF) – The background PDF, which must be an instance of PDF and IsBackgroundPDF.
evtp_name_fmt (str) – The format of the name of the event probability parameters. The varibale i will be the parameter’s event index.
minimizer (instance of Minimizer | None) – The optional instance of Minimizer that should be used to minimize the negative of this log-likelihood function.

property evtp_name_fmt

initialize_for_new_trial(tdm, tl=None, **kwargs)

Initializes this LH function for a new trial by calling the initialize_for_new_trial() methods of the signal and background PDFs.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data.
tl (instance of TimeLord | None) – The optional instance of TimeLord to measure timing information.
**kwargs – Additional keyword arguments are passed to the initialize_for_new_trial() methods of the signal and background PDFs.

evaluate(tdm, fitparam_values, src_params_recarray=None, tl=None)

Evaluates this LLH function for the given trial data and set of fit parameter values.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data.
fitparam_values (instance of numpy.ndarray) – The (N_fitparams,)-shaped numpy.ndarray holding the current values of the global fit parameters.
src_params_recarray (instance of numpy.ndarray | None) – The structured instance of numpy.ndarray of length N_sources holding the parameter names and values of all sources. If set to None it will be created automatically from the fitparam_values array. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing.

Returns:

log_lh (float) – The value of the LLH function.
grads (instance of numpy.ndarray) – The (N_fitparams,)-shaped numpy.ndarray holding the gradient value for each global fit parameter.

skyllh.core.llhratio module

The llhratio module provides classes implementing the log-likelihood ratio functions. In general these should be detector independent, because they implement the pure math of the log-likelihood ratio function.

class skyllh.core.llhratio.LLHRatio(pmm, minimizer, **kwargs)

Bases: HasConfig

Abstract base class for a log-likelihood (LLH) ratio function.

Creates a new LLH ratio function instance.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global parameters to local parameters of individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.

property pmm: The ParameterModelMapper instance providing the mapping of global floating parameters to individual models.

property minimizer: The Minimizer instance used to minimize the negative of the log-likelihood ratio function.

abstract initialize_for_new_trial(tl=None, **kwargs)

This method will be called by the Analysis class after new trial data has been initialized to the trial data manager. Derived classes can make use of this call hook to perform LLHRatio specific trial initialization.

Parameters:: tl (instance of TimeLord | None) – The optional instance of TimeLord to use for timing measurements.

abstract evaluate(fitparam_values, src_params_recarray=None, tl=None)

This method evaluates the LLH ratio function for the given set of fit parameter values.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped numpy 1D ndarray holding the current values of the global fit parameters.
src_params_recarray (instance of numpy record ndarray | None) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. If set to None it will be created automatically from the fitparam_values array. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing.

Returns:

log_lambda (float) – The calculated log-lambda value.
grads (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D numpy ndarray holding the gradient value for each global fit parameter.

maximize(rss, tl=None)

Maximize the log-likelihood ratio function, by using the evaluate method.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService to draw random numbers from. This is needed to generate random parameter initial values.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time the maximization process.

Returns:

log_lambda_max (float) – The (maximum) value of the log-likelihood ratio (log_lambda) function for the best fit parameter values.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the values of the global fit parameters.
status (dict) – The dictionary with status information about the maximization process, i.e. from the minimizer.

class skyllh.core.llhratio.TCLLHRatio(pmm, minimizer, mean_n_sig_0, **kwargs)

Bases: LLHRatio

Abstract base class for a log-likelihood (LLH) ratio function with two components, i.e. signal and background.

Creates a new two-component LLH ratio function instance.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global floating parameters to individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
mean_n_sig_0 (float) – The fixed mean number of signal events for the null-hypothesis.

property mean_n_sig_0: The parameter value for the mean number of signal events of the null-hypothesis.

abstract calculate_ns_grad2(ns, ns_pidx, src_params_recarray, tl=None, **kwargs)

This method is supposed to calculate the second derivative of the log-likelihood ratio function w.r.t. the fit parameter ns, the number of signal events in the data set.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D numpy ndarray holding the current values of the global fit parameters.
ns_pidx (int) – The index of the global ns fit parameter.
src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

nsgrad2 (float) – The second derivative w.r.t. ns of the log-likelihood ratio function for the given fit parameter values.

maximize_with_1d_newton_rapson_minimizer(rss, tl=None)

Maximizes this log-likelihood ratio function, by minimizing its negative using a 1D Newton-Rapson minimizer.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to draw random numbers from. It is used by the minimizer to generate random fit parameter initial values.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time the maximization of the LLH-ratio function.

Returns:

log_lambda_max (float) – The (maximum) value of the log-likelihood ratio (log_lambda) function for the best fit parameter values.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the global fit parameter values.
status (dict) – The dictionary with status information about the maximization process, i.e. from the minimizer.

maximize(rss, tl=None)

Maximizes this log-likelihood ratio function, by minimizing its negative. This method has a special implementation when a 1D Newton-Rapson minimizer is used. In that case only the first and second derivative of the log-likelihood ratio function is calculated.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to draw random numbers from. It is used by the minimizer to generate random fit parameter initial values.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to time the maximization of the LLH-ratio function.

Returns:

log_lambda_max (float) – The (maximum) value of the log-likelihood ratio (log_lambda) function for the best fit parameter values.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the global fit parameter values.
status (dict) – The dictionary with status information about the maximization process, i.e. from the minimizer.

class skyllh.core.llhratio.SingleDatasetTCLLHRatio(pmm, minimizer, shg_mgr, tdm, mean_n_sig_0, **kwargs)

Bases: TCLLHRatio

Abstract base class for a log-likelihood (LLH) ratio function with two components, i.e. signal and background, for a single data set.

Creates a new two-component LLH ratio function instance for a single data set.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global floating parameters to individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
shg_mgr (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance that defines the source hypothesis groups.
tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.
mean_n_sig_0 (float) – The fixed mean number of signal events for the null-hypothesis.

property shg_mgr: The SourceHypoGroupManager instance that defines the source hypothesis groups.

property tdm: The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.

change_shg_mgr(shg_mgr)

Changes the source hypothesis group manager of this two-component LLH ratio function.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

class skyllh.core.llhratio.ZeroSigH0SingleDatasetTCLLHRatio(pmm, minimizer, shg_mgr, tdm, pdfratio, **kwargs)

Bases: SingleDatasetTCLLHRatio

This class implements a two-component (TC) log-likelihood (LLH) ratio function for a single dataset assuming zero signal for the null-hypothesis.

Constructor of the two-component log-likelihood ratio function.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global floating parameters to individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
shg_mgr (instance of SourceHypoGroupManager) – The SourceHypoGroupManager instance that defines the source hypothesis groups.
tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.
pdfratio (instance of PDFRatio) – The instance of PDFRatio. A PDFRatio instance might depend on none, one, or several fit parameters.

property mean_n_sig_0: The parameter value for the mean number of signal events of the null-hypothesis.

property pdfratio: The instance of PDFRatio.

initialize_for_new_trial(tl=None, **kwargs)

Initializes the log-likelihood ratio function for a new trial. It calls the initialize_for_new_trial() method of the PDFRatio class.

Parameters:: tl (instance of TimeLord) – The optional instance of TimeLord to measure timing information.

calculate_log_lambda_and_grads(N, ns, ns_pidx, p_mask, Xi, dXi_dp)

Calculates the log(Lambda) value and its gradient for each global fit parameter. This calculation is source and detector independent.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped ndarray holding the current values of the global fit parameters. These numbers are used as cache key to validate the nsgrad_i values for the given fit parameter values for a possible later calculation of the second derivative w.r.t. ns of the log-likelihood ratio function.
N (int) – The total number of events.
ns (float) – The value of the global fit paramater ns.
ns_pidx (int) – The index of the global fit parameter ns.
p_mask (instance of numpy ndarray) – The (N_fitparam,)-shaped numpy ndarray of bool selecting all global fit parameters, except ns.
Xi (instance of numpy ndarray) – The (n_selected_events,)-shaped 1D numpy ndarray holding the X value of each selected event.
dXi_dp (instance of numpy ndarray) – The (n_selected_events, N_fitparams-1,)-shaped 2D ndarray holding the derivative value for each fit parameter p (i.e. except ns) of each event’s X value.

Returns:

log_lambda (float) – The value of the log-likelihood ratio function.
grads (instance of numpy ndarray) – The (N_fitparams,)-shaped numpy ndarray holding the gradient value of log_lambda for each fit parameter.

calculate_ns_grad2(ns, ns_pidx=None, src_params_recarray=None, tl=None)

Calculates the second derivative w.r.t. ns of the log-likelihood ratio function. This method tries to use cached values for the first derivative w.r.t. ns of the log-likelihood ratio function for the individual events. If cached values don’t exist or do not match the given fit parameter values, they will get calculated automatically by calling the evaluate method with the given fit parameter values.

Parameters:

fitparam_values (numpy (N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the current values of the global fit parameters.
ns (float) – The value of the global fit paramater ns.
ns_pidx (int) – The parameter index of the global fit parameter ns. For this particular class this is an ignored interface parameter.
src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array. For this particular class this is an ignored interface parameter.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

nsgrad2 (float) – The second derivative w.r.t. ns of the log-likelihood ratio function for the given fit parameter values.

evaluate(fitparam_values, src_params_recarray=None, tl=None)

Evaluates the log-likelihood ratio function for the given set of data events.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D ndarray holding the current values of the global fit parameters.
src_params_recarray (instance of numpy structured ndarray | None) – The numpy record ndarray of length N_sources holding the local parameter names and values of all sources. If it is None, it will be generated automatically from the fitparam_values argument using the ParameterModelMapper instance.
tl (instance of TimeLord | None) – The optional instance of TimeLord to measure the timing of evaluating the LLH ratio function.

Returns:

log_lambda (float) – The calculated log-lambda value.
grads (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D numpy ndarray holding the gradient value for each global fit parameter.

class skyllh.core.llhratio.MultiDatasetTCLLHRatio(pmm, minimizer, src_detsigyield_weights_service, ds_sig_weight_factors_service, llhratio_list, **kwargs)

Bases: TCLLHRatio

This class describes a two-component log-likelihood ratio function for multiple datasets. The final log-likelihood ratio value is the sum of the individual log-likelihood ratio values.

The different datasets contribute according to their dataset signal weight factor, f_j(p_s), which depends on possible signal fit parameters. By definition the signal fit parameters are assumed to be the same for each dataset.

By mathematical definition this class is suitable for single and multi source hypotheses.

Creates a new composite two-component log-likelihood ratio function.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global floating parameters to individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService) – An instance of SrcDetSigYieldWeightsService, which provides the roduct of the source weights with the detector signal yield.
ds_sig_weight_factors_service (instance of DatasetSignalWeightFactorsService) – An instance of DatasetSignalWeightFactorsService, which provides the relative dataset signal weight factors.
llhratio_list (list of instance of SingleDatasetTCLLHRatio) – The list of the two-component log-likelihood ratio functions, one for each dataset.

property src_detsigyield_weights_service: The instance of SrcDetSigYieldWeightsService, which provides the product of the source weights with the detector signal yield.

property ds_sig_weight_factors_service: The instance of DatasetSignalWeightFactorsService that provides the relative dataset signal weight factors.

property llhratio_list: (read-only) The list of TCLLHRatio instances, which are part of this composite log-likelihood-ratio function.

property n_selected_events: (read-only) The sum of selected events of each individual log-likelihood ratio function.

property mean_n_sig_0: The parameter value for the mean number of signal events of the null-hypothesis.

change_shg_mgr(shg_mgr)

Changes the source hypo group manager of all objects of this LLH ratio function, hence, calling the change_shg_mgr method of all TCLLHRatio instances of this LLHRatio instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the groups of source hypotheses.

initialize_for_new_trial(tl=None, **kwargs)

Initializes the log-likelihood-ratio function for a new trial. It calls the initialize_for_new_trial() method of the LLHRatio class of each individual log-likelihood ratio function.

Parameters:: tl (instance of TimeLord) – The optional instance of TimeLord to measure timing information.

evaluate(fitparam_values, src_params_recarray=None, tl=None)

Evaluates the composite log-likelihood-ratio function and returns its value and global fit parameter gradients.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped numpy 1D ndarray holding the current values of the global fit parameters.
src_params_recarray (instance of numpy record ndarray | None) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array. It case it is None, it will be created automatically from the fitparam_values argument using the ParameterModelMapper instance.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

log_lambda (float) – The calculated log-lambda value of the composite log-likelihood-ratio function.
grads (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D ndarray holding the gradient value of the composite log-likelihood-ratio function for each global fit parameter.

calculate_ns_grad2(ns, ns_pidx, src_params_recarray, tl=None)

Calculates the second derivative w.r.t. ns of the log-likelihood ratio function.

Note:

This method takes the dataset signal weight factors from the dataset
signal weight factors service. Hence, the service needs to be
updated before calling this method.

Parameters:

fitparam_values (instance of numpy ndarray) – The (N_fitparams,)-shaped 1D ndarray holding the current values of the global fit parameters.
ns (float) – The value of the global fit paramater ns.
ns_pidx (int) – The index of the global parameter ns.
src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

nsgrad2 (float) – The second derivative w.r.t. ns of the log-likelihood ratio function for the given fit parameter values.

class skyllh.core.llhratio.NsProfileMultiDatasetTCLLHRatio(pmm, minimizer, mean_n_sig_0, llhratio, **kwargs)

Bases: TCLLHRatio

This class implements a profile log-likelihood ratio function that has only ns as fit parameter. It uses a MultiDatasetTCLLHRatio instance as log-likelihood function. Hence, mathematically it is

\[\Lambda(n_{\mathrm{s}}) = \frac{L(n_{\mathrm{s}})}{L(n_{\mathrm{s}}=n_{\mathrm{s},0})},\]

where \(n_{\mathrm{s},0}\) is the fixed mean number of signal events for the null-hypothesis.

Creates a new ns-profile log-likelihood-ratio function with a null-hypothesis where \(n_{\mathrm{s}}\) is fixed to mean_n_sig_0.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper providing the mapping of global parameters to local parameters of individual models.
minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
mean_n_sig_0 (float) – The fixed parameter value for the mean number of signal events of the null-hypothesis.
llhratio (instance of MultiDatasetTCLLHRatio) – The instance of MultiDatasetTCLLHRatio, which should be used as log-likelihood function.

property llhratio: The instance of MultiDatasetTCLLHRatio, which should be used as log-likelihood function.

change_shg_mgr(shg_mgr)

Changes the source hypo group manager of all objects of this LLH ratio function, hence, calling the change_shg_mgr method of the underlaying MultiDatasetTCLLHRatio instance of this LLHRatio instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new instance of SourceHypoGroupManager.

initialize_for_new_trial(tl=None, **kwargs)

Initializes the log-likelihood-ratio function for a new trial.

Parameters:: tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

evaluate(fitparam_values, src_params_recarray=None, tl=None)

Evaluates the log-likelihood-ratio function and returns its value and global fit parameter gradients.

Parameters:

fitparam_values (instance of numpy ndarray) – The (1,)-shaped numpy 1D ndarray holding the current values of the global fit parameters. By definition of this LLH ratio function, it must contain the single fit paramater value for ns.
src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

log_lambda (float) – The calculated log-lambda value of this log-likelihood-ratio function.
grads ((1,)-shaped 1D ndarray) – The ndarray holding the gradient value of this log-likelihood-ratio for ns.

calculate_ns_grad2(ns, ns_pidx, src_params_recarray, tl=None)

Calculates the second derivative w.r.t. ns of the log-likelihood ratio function.

Parameters:

ns (float) – The value of the global fit paramater ns.
ns_pidx (int) – The index of the global fit paramater ns. By definition this must be 0.
src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the parameter names and values of all sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information about this array.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used for timing measurements.

Returns:

nsgrad2 (float) – The second derivative w.r.t. ns of the log-likelihood ratio function for the given fit parameter values.

skyllh.core.math module

The math module contains classes for pure mathematical objects.

class skyllh.core.math.MathFunction(**kwargs)

Bases: object

This abstract base class provides an implementation for a mathematical function. Such a function has defined parameters, which are implemented as class properties. The tuple of parameter names is defined through the param_names property.

property param_names: The tuple holding the names of the math function’s parameters.

abstract property math_function_str: The string showing the mathematical function of this MathFunction.

copy(newparams=None)

Copies this MathFunction object by calling the copy.deepcopy function, and sets new parameters if requested.

Parameters:: newparams (dict | None) – The dictionary with the new parameter values to set, where the dictionary key is the parameter name and the dictionary value is the new value of the parameter.

get_param(name)

Retrieves the value of the given parameter. It returns np.nan if the parameter does not exist.

Parameters:: name (str) – The name of the parameter.
Returns:: value (float | np.nan) – The value of the parameter.

set_params(pdict)

Sets the parameters of the math function to the given parameter values.

Parameters:: pdict (dict (name: value)) – The dictionary holding the names of the parameters and their new values.
Returns:: updated (bool) – Flag if parameter values were actually updated.

skyllh.core.minimizer module

The minimizer module provides functionality for the minimization process of a function.

class skyllh.core.minimizer.MinimizerImpl(**kwargs)

Bases: HasConfig

Abstract base class for a minimizer implementation. It defines the interface between the implementation and the Minimizer class.

Creates a new instance having the property cfg.

Parameters:: cfg (instance of Config) – The instance of Config holding the local configuration.

abstract minimize(initials, bounds, func, func_args=None, **kwargs)

This method is supposed to minimize the given function with the given initials.

Parameters:

initials (1D (N_fitparams)-shaped numpy ndarray) – The ndarray holding the initial values of all the fit parameters.
bounds (2D (N_fitparams,2)-shaped numpy ndarray) – The ndarray holding the boundary values (vmin, vmax) of the fit parameters.
func (callable) –
The function that should get minimized. The call signature must be

__call__(x, *args)

The return value of func is minimizer implementation dependent.
func_args (sequence | None) – Optional sequence of arguments for func.
Arguments (Additional Keyword) –
---------------------------- –
minimizer (Additional keyword arguments include options for this) –
dependent. (implementation. These are implementation) –

Returns:

xmin (1D ndarray) – The array containing the function parameter values at the function’s minimum.
fmin (float) – The function value at its minimum.
status (dict) – The status dictionary with information about the minimization process.

abstract get_niter(status)

This method is supposed to return the number of iterations that were required to find the minimum.

Parameters:: status (dict) – The dictionary with the status information about the last minimization process.
Returns:: niter (int) – The number of iterations needed to find the minimum.

abstract has_converged(status)

This method is supposed to analyze the status information dictionary if the last minimization process has converged.

Parameters:: status (dict) – The dictionary with the status information about the last minimization process.
Returns:: converged (bool) – The flag if the minimization has converged (True), or not (False).

abstract is_repeatable(status)

This method is supposed to analyze the status information dictionary if the last minimization process can be repeated to obtain a better minimum.

Parameters:: status (dict) – The dictionary with the status information about the last minimization process.
Returns:: repeatable (bool) – The flag if the minimization process can be repeated to obtain a better minimum.

class skyllh.core.minimizer.ScipyMinimizerImpl(method: str, **kwargs)

Bases: MinimizerImpl

Wrapper for scipy.optimize.minimize

Creates a new instance of ScipyMinimizerImpl.

Parameters:: method (str) – The minimizer method to use. See the documentation for the method argument of the scipy.optimize.minimize() function for possible values.

minimize(initials, bounds, func, func_args=None, **kwargs)

Minimizes the given function func with the given initial function argument values initials.

Parameters:

initials (1D numpy ndarray) – The ndarray holding the initial values of all the fit parameters.
bounds (2D (N_fitparams,2)-shaped numpy ndarray) – The ndarray holding the boundary values (vmin, vmax) of the fit parameters.
func (callable) –
The function that should get minimized. The call signature must be

__call__(x, *args)

The return value of func must be (f, grads), the function value at the function arguments x and the ndarray with the values of the function gradient for each fit parameter, if the func_provides_grads keyword argument option is set to True. If set to False, func must return only the function value.
func_args (sequence | None) – Optional sequence of arguments for func.
Arguments (Additional Keyword) –
---------------------------- –
minimizer (Additional keyword arguments include options for this) –
are (implementation. Possible options) –

func_provides_gradsbool
Flag if the function func also returns its gradients. Default is True.

Any additional keyword arguments are passed on to the underlaying scipy.optimize.minimize() minimization function.

Returns:

xmin (instance of numpy.ndarray) – The 1D array containing the function arguments at the function’s minimum.
fmin (float) – The function value at its minimum.
res (instance of scipy.optimize.OptimizeResult) – The scipy OptimizeResult.

get_niter(status)

Returns the number of iterations needed to find the minimum.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: niter (int) – The number of iterations needed to find the minimum.

has_converged(status)

Analyzes the status information dictionary if the minimization process has converged. By definition the minimization process has converged if status['warnflag'] equals 0.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: converged (bool) – The flag if the minimization has converged (True), or not (False).

is_repeatable(status)

Checks if the minimization process can be repeated to get a better result.

TODO: Method specific checks. For now just return False

Parameters:: status (dict) – The dictionary with the status information about the last minimization process.
Returns:: repeatable (bool) – The flag if the minimization process can be repeated to obtain a better minimum.

class skyllh.core.minimizer.LBFGSMinimizerImpl(ftol=1e-06, pgtol=1e-05, maxls=100, **kwargs)

Bases: MinimizerImpl

The LBFGSMinimizerImpl class provides the minimizer implementation for L-BFG-S minimizer used from the scipy.optimize module.

Creates a new L-BGF-S minimizer instance to minimize the given likelihood function with its given partial derivatives.

Parameters:

ftol (float) – The function value tolerance.
pgtol (float) – The gradient value tolerance.
maxls (int) – The maximum number of line search steps for an interation.

minimize(initials, bounds, func, func_args=None, **kwargs)

Minimizes the given function func with the given initial function argument values initials.

Parameters:

initials (1D numpy ndarray) – The ndarray holding the initial values of all the fit parameters.
bounds (2D (N_fitparams,2)-shaped numpy ndarray) – The ndarray holding the boundary values (vmin, vmax) of the fit parameters.
func (callable) –
The function that should get minimized. The call signature must be

__call__(x, *args)

The return value of func must be (f, grads), the function value at the function arguments x and the ndarray with the values of the function gradient for each fit parameter, if the func_provides_grads keyword argument option is set to True. If set to False, func must return only the function value.
func_args (sequence | None) – Optional sequence of arguments for func.
Arguments (Additional Keyword) –
---------------------------- –
minimizer (Additional keyword arguments include options for this) –
are (implementation. Possible options) –

func_provides_gradsbool
Flag if the function func also returns its gradients. Default is True.

Any additional keyword arguments are passed on to the underlaying scipy.optimize.fmin_l_bfgs_b() minimization function.

Returns:

xmin (1D ndarray) – The array containing the function arguments at the function’s minimum.
fmin (float) – The function value at its minimum.
status (dict) – The status dictionary with information about the minimization process. The following information are provided:

niterint
The number of iterations needed to find the minimum.

warnflagint
The warning flag indicating if the minimization did converge. The possible values are:

0: The minimization converged.

get_niter(status)

Returns the number of iterations needed to find the minimum.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: niter (int) – The number of iterations needed to find the minimum.

has_converged(status)

Analyzes the status information dictionary if the minimization process has converged. By definition the minimization process has converged if status['warnflag'] equals 0.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: converged (bool) – The flag if the minimization has converged (True), or not (False).

is_repeatable(status)

Checks if the minimization process can be repeated to get a better result. It’s repeatable if

status[‘warnflag’] == 2 and ‘FACTR’ in str(status[‘task’])

Parameters:: status (dict) – The dictionary with the status information about the last minimization process.
Returns:: repeatable (bool) – The flag if the minimization process can be repeated to obtain a better minimum.

class skyllh.core.minimizer.NR1dNsMinimizerImpl(ns_tol=0.001, max_steps=100, **kwargs)

Bases: MinimizerImpl

The NR1dNsMinimizerImpl class provides a minimizer implementation for the Newton-Raphson method for finding the minimum of a one-dimensional R1->R1 function, i.e. a function that depends solely on one parameter, the number of signal events ns.

Creates a new NRNs minimizer instance to minimize the given likelihood function with its given partial derivatives.

Parameters:

ns_tol (float) – The tolerance / precision for the ns parameter value.
max_steps (int) – The maximum number of NR steps. If max_step is reached, the fit is considered NOT converged.

minimize(initials, bounds, func, func_args=None, **kwargs)

Minimizes the given function func with the given initial function argument values initials. This minimizer implementation will only vary the first parameter. All other parameters will be set to their initial value.

Parameters:

initials (1D numpy ndarray) – The ndarray holding the initial values of all the fit parameters.
bounds (2D (N_fitparams,2)-shaped numpy ndarray) – The ndarray holding the boundary values (vmin, vmax) of the fit parameters.
func (callable) –
The function that should get minimized. The call signature must be

__call__(x, *args)

The return value of func must be (f, grad, grad2), i.e. the function value at the function arguments x, the value of the function first derivative for the one fit parameter, and the value of the second derivative for the one fit parameter.
func_args (sequence | None) – Optional sequence of arguments for func.
Arguments (Additional Keyword) –
---------------------------- –
minimization (There are no additional options defined for this) –
implementation. –

Returns:

xmin (1D ndarray) – The array containing the function parameter values at the function’s minimum.
fmin (float) – The function value at its minimum.
status (dict) – The status dictionary with information about the minimization process. The following information are provided:

niterint
The number of iterations needed to find the minimum.

last_nr_stepfloat
The Newton-Raphson step size of the last iteration.

warnflagint
The warning flag indicating if the minimization did converge. The possible values are:

-1: The function minimum is above the upper bound of the
parameter value. Convergence forced at upper bound.

-2: The function minimum is below the lower bound of the
parameter value. Convergence forced at lower bound.

0: The minimization converged with a iteration step size
smaller than the specified precision.

1: The minimization did NOT converge within self.max_steps
number of steps

warnreason: str
The description for the set warn flag.

get_niter(status)

Returns the number of iterations needed to find the minimum.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: niter (int) – The number of iterations needed to find the minimum.

has_converged(status)

Analyzes the status information dictionary if the minimization process has converged. By definition the minimization process has converged if status['warnflag'] is smaller or equal to 0.

Parameters:: status (dict) – The dictionary with the status information about the minimization process.
Returns:: converged (bool) – The flag if the minimization has converged (True), or not (False).

is_repeatable(status): Checks if the minimization process can be repeated to get a better result. By definition of this minimization method, this method will always return False.

class skyllh.core.minimizer.NRNsScan2dMinimizerImpl(p2_scan_step, ns_tol=0.001, **kwargs)

Bases: NR1dNsMinimizerImpl

The NRNsScan2dMinimizerImpl class provides a minimizer implementation for the R2->R1 function where the first dimension is minimized using the Newton-Raphson minimization method and the second dimension is scanned.

Creates a new minimizer implementation instance.

Parameters:

p2_scan_step (float) – The step size for the scan of the second parameter of the function to minimize.
ns_tol (float) – The tolerance / precision for the ns parameter value.

minimize(initials, bounds, func, func_args=None, **kwargs)

Minimizes the given function func with the given initial function argument values initials. This minimizer implementation will only vary the first two parameters. The first parameter is the number of signal events, ns, and it is minimized using the Newton-Rapson method. The second parameter is scanned through its boundaries in step sizes of p2_scan_step.

Parameters:

initials (1D numpy ndarray) – The ndarray holding the initial values of all the fit parameters.
bounds (2D (N_fitparams,2)-shaped numpy ndarray) – The ndarray holding the boundary values (vmin, vmax) of the fit parameters.
func (callable) –
The function that should get minimized. The call signature must be

__call__(x, *args)

The return value of func must be (f, grad, grad2), i.e. the function value at the function arguments x, the value of the function first derivative for the first fit parameter, and the value of the second derivative for the first fit parameter.
func_args (sequence | None) – Optional sequence of arguments for func.
Arguments (Additional Keyword) –
---------------------------- –
minimization (There are no additional options defined for this) –
implementation. –

Returns:

xmin (1D ndarray) – The array containing the function parameter values at the function’s minimum.
fmin (float) – The function value at its minimum.
status (dict) – The status dictionary with information about the minimization process. The following information are provided:

niterint
The number of iterations needed to find the minimum.

last_nr_stepfloat
The Newton-Raphson step size of the last iteration.

p2_n_stepsint
The number of scanning steps performed for the 2nd parameter.

warnflagint
The warning flag indicating if the minimization did converge. The possible values are:

0: The minimization converged with a iteration step size
smaller than the specified precision.

1: The function minimum is below the minimum bound of the
parameter value. The last iteration’s step size did not achieve the specified precision.

2: The function minimum is above the maximum bound of the
parameter value. The last iteration’s step size did not achieve the specified precision.

warnreason: str
The description for the set warn flag.

class skyllh.core.minimizer.Minimizer(minimizer_impl, max_repetitions=100, **kwargs)

Bases: object

The Minimizer class provides the general interface for minimizing a function. The class takes an instance of MinimizerImpl for a specific minimizer implementation.

Creates a new Minimizer instance.

Parameters:

minimizer_impl (instance of MinimizerImpl) – The minimizer implementation for a specific minimizer algorithm.
max_repetitions (int) – In case the minimization process did not converge at the first time this option specifies the maximum number of repetitions with different initials.

property minimizer_impl: The instance of MinimizerImpl, which provides the implementation of the minimizer.

property max_repetitions: In case the minimization process did not converge at the first time this option specifies the maximum number of repetitions with different initials.

minimize(rss, paramset, func, args=None, kwargs=None)

Minimizes the the given function func by calling the minimize method of the minimizer implementation.

After the minimization process it calls the has_converged and is_repeatable methods of the minimizer implementation to determine if an additional minimization attempt has to be performed. This is repeated until the minimization process did converge or if the maximal number of repetitions has occurred.

Parameters:

rss (RandomStateService instance) – The RandomStateService instance to draw random numbers from.
paramset (instance of ParameterSet) – The ParameterSet instances holding the floating parameters of the function func.
func (callable f(x, *args)) –
The function to be minimized. It must have the call signature

__call__(x, *args)

The return value of func is minimizer implementation dependent.
args (sequence of arguments for func | None) – The optional sequence of arguments for func.
kwargs (dict | None) – The optional dictionary with keyword arguments for the minimizer implementation minimize method.

Returns:

xmin (1d numpy ndarray) – The array holding the parameter values for which the function has a minimum.
fmin (float) – The function value at its minimum.
status (dict) – The status dictionary with information about the minimization process.

skyllh.core.model module

This module defines the base class for any model class used in SkyLLH.

class skyllh.core.model.Model(name=None, **kwargs)

Bases: object

This class provides a base class for all model classes used in SkyLLH. Models could be for instance source models or background models.

Creates a new Model instance.

Parameters:: name (str | None) – The name of the model. If set to None, the id of the object is taken as name.

property name: The name of the model.

property id: (read-only) The ID of the model. It’s an integer generated with Python’s id function. Hence, it’s related to the memory address of the object.

class skyllh.core.model.ModelCollection(models=None, model_type=None, **kwargs)

Bases: NamedObjectCollection

This class describes a collection of Model instances. It can be used to group several models into a single object.

Creates a new Model collection. The type of the model instances this collection holds can be restricted, by setting the model_type argument.

Parameters:

models (sequence of model_type instances | None) – The sequence of models this collection should be initalized with.
model_type (type | None) – The type of the model. It must be a subclass of class Model. If set to None (default), Model will be used.

static cast(obj, errmsg=None, **kwargs)

Casts the given object to a ModelCollection object. If the cast fails, a TypeError with the given error message is raised.

Parameters:

obj (Model instance | sequence of Model instances |) – ModelCollection | None The object that should be casted to ModelCollection. If set to None, an empty ModelCollection is created.
errmsg (str | None) – The error message if the cast fails. If set to None, a generic error message will be used.
arguments (Additional keyword) –
---------------------------- –
the (Additional keyword arguments are passed to the constructor of) –
class. (ModelCollection) –

Raises:

TypeError – If the cast failed.

Returns:

model_collection (instance of ModelCollection) – The created ModelCollection instance. If obj is already a ModelCollection instance, it will be returned.

property model_type: (read-only) The type of the model.

property models: (read-only) The list of models of type model_type.

class skyllh.core.model.DetectorModel(name, **kwargs)

Bases: Model

This class provides a base class for a detector model. It can be used in combination with the ParameterModelMapper class.

Creates a new DetectorModel instance.

Parameters:: name (str) – The name of the detector model.

skyllh.core.multiproc module

skyllh.core.multiproc.get_ncpu(cfg, local_ncpu)

Determines the number of CPUs to use for functions that support multi-processing.

Parameters:

cfg (instance of Config) – The instance of Config holding the local configuration.
local_ncpu (int | None) – The local setting of the number of CPUs to use.

Returns:

ncpu (int) – The number of CPUs to use by functions that allow multi-processing. If local_ncpu is set to None, the global NCPU setting is returned. If the global NCPU setting is None as well, the default value 1 is returned.

skyllh.core.multiproc.parallelize(func, args_list, ncpu, rss=None, tl=None, ppbar=None)

Parallelizes the execution of the given function for different arguments.

Parameters:

func (callable) – The function which should be called with different arguments, which are given through the args_list argument. If the rss argument is not None, func requires an argument named rss.
args_list (list of 2-element tuple) – The list of the different arguments for function func. Each element of that list must be a 2-element tuple, where the first element is a tuple of the arguments of func, and the second element is a dictionary with the keyword arguments of func. If the rss argument is not None, func argument rss has to be omitted.
ncpu (int) – The number of CPUs to use, i.e. the number of subprocesses to spawn.
rss (RandomStateService | None) – The RandomStateService instance to use for generating random numbers.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to time individual tasks.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.

Returns:

result_list (list) – The list of the result values of func, where each element of that list corresponds to the arguments element in args_list.

class skyllh.core.multiproc.IsParallelizable(*args, ncpu=None, **kwargs)

Bases: object

Classifier class defining the ncpu property. Classes that derive from this class indicate, that they can make use of multi-processing on several CPUs at the same time.

property ncpu: The number (int) of CPUs to utilize. It calls the get_ncpu utility function with this property as argument. Hence, if this property is set to None, the global NCPU setting will take precedence.

skyllh.core.parameters module

skyllh.core.parameters.make_linear_parameter_grid_1d(name, low, high, delta)

Utility function to create a ParameterGrid object for a 1-dimensional linear parameter grid.

Parameters:

name (str) – The name of the parameter.
low (float) – The lowest value of the parameter.
high (float) – The highest value of the parameter.
delta (float) – The constant distance between the grid values. By definition this defines also the precision of the parameter values.

Returns:

obj (ParameterGrid) – The ParameterGrid object holding the discrete parameter grid values.

class skyllh.core.parameters.Parameter(name, initial, valmin=None, valmax=None, isfixed=None)

Bases: object

This class describes a parameter of a mathematical function, like a PDF, or source flux function. A parameter has a name, a value range, and an initial value. Furthermore, it has a flag that determines whether this parameter has a fixed value or not.

Creates a new Parameter instance.

Parameters:

name (str) – The name of the parameter.
initial (float) – The initial value of the parameter.
valmin (float | None) – The minimum value of the parameter in case this parameter is mutable.
valmax (float | None) – The maximum value of the parameter in case this parameter is mutable.
isfixed (bool | None) – Flag if the value of this parameter is mutable (False), or not (True). If set to True, the value of the parameter will always be the initial value. If set to None, the parameter will be mutable if valmin and valmax were specified. Otherwise, the parameter is fixed. The default is None.

property name: The name of the parameter.

property initial: The initial value of the parameter.

property isfixed: The flag if the parameter is mutable (False) or not (True).

property valmin: The minimum bound value of the parameter.

property valmax: The maximum bound value of the parameter.

property value: The current value of the parameter.

__eq__(other)

Implements the equal comparison operator (==). By definition two parameters are equal if there property values are equal.

Parameters:: other (Parameter instance) – The instance of Parameter which should be used to compare against this Parameter instance.
Returns:: cmp (bool) – True, if this Parameter instance and the other Parameter instance have the same property values.

as_linear_grid(delta)

Creates a ParameterGrid instance with a linear grid with constant grid value distances delta.

Parameters:: delta (float) – The constant distance between the grid values. By definition this defines also the precision of the parameter values.
Returns:: grid (ParameterGrid instance) – The ParameterGrid instance holding the grid values.
Raises:: ValueError – If this Parameter instance represents a fixed parameter.

change_fixed_value(value)

Changes the value of this fixed parameter to the given value.

Parameters:: value (float) – The parameter’s new value.
Returns:: value (float) – The parameter’s new value.
Raises:: ValueError – If this parameter is not a fixed parameter.

make_fixed(initial=None)

Fixes this parameter to the given initial value.

Parameters:: initial (float | None) – The new fixed initial value of the Parameter. If set to None, the parameter’s current value will be used as initial value.
Returns:: value (float) – The parameter’s new value.

make_floating(initial=None, valmin=None, valmax=None)

Defines this parameter as floating with the given initial, minimal, and maximal value.

Parameters:

initial (float | None) – The initial value of the parameter. If set to None, the parameter’s current value will be used as initial value.
valmin (float | None) – The minimal value the parameter’s value can take. If set to None, the parameter’s current minimal value will be used.
valmax (float | None) – The maximal value the parameter’s value can take. If set to None, the parameter’s current maximal value will be used.

Returns:

value (float) – The parameter’s new value.

Raises:

ValueError – If valmin is set to None and this parameter has no valmin defined. If valmax is set to None and this parameter has no valmax defined.

class skyllh.core.parameters.ParameterSet(params=None)

Bases: object

This class holds a set of Parameter instances.

Constructs a new ParameterSet instance.

Parameters:: params (instance of Parameter | sequence of Parameter instances | None) – The initial sequence of Parameter instances of this ParameterSet instance.

static union(*paramsets)

Creates a ParameterSet instance that is the union of the given ParameterSet instances.

Parameters:: *paramsets (ParameterSet instances) – The sequence of ParameterSet instances.
Returns:: paramset (ParameterSet instance) – The newly created ParameterSet instance that holds the union of the parameters provided by all the ParameterSet instances.

property params: (read-only) The 1D ndarray holding the Parameter instances.

property params_name_list: (read-only) The list of str holding the names of all the parameters.

property fixed_params: (read-only) The 1D ndarray holding the Parameter instances, whose values are fixed.

property fixed_params_name_list: (read-only) The list of the fixed parameter names.

property fixed_params_mask: (read-only) The 1D ndarray holding the mask for the fixed parameters of this parameter set.

property fixed_params_idxs: The numpy ndarray holding the indices of the fixed parameters.

property floating_params: (read-only) The 1D ndarray holding the Parameter instances, whose values are floating.

property floating_params_name_list: (read-only) The list of the floating parameter names.

property floating_params_mask: (read-only) The 1D ndarray holding the mask for the floating parameters of this parameter set.

property floating_params_idxs: The numpy ndarray holding the indices of the floating parameters.

property n_params: (read-only) The number of parameters this ParameterSet has.

property n_fixed_params: (read-only) The number of fixed parameters defined in this parameter set.

property n_floating_params: (read-only) The number of floating parameters defined in this parameter set.

property fixed_param_values: (read-only) The (n_fixed_params,)-shaped ndarray holding values of the fixed parameters.

property floating_param_initials: (read-only) The 1D (n_floating_params,)-shaped ndarray holding the initial values of all the global floating parameters.

property floating_param_bounds: (read-only) The 2D (n_floating_params,2)-shaped ndarray holding the boundaries for all the floating parameters.

__contains__(param_name)

Implements the param_name in self expression. It calls the has_param() method of this class.

Parameters:: param_name (str) – The name of the parameter.
Returns:: check (bool) – Returns True if the given parameter is part of this ParameterSet instance, False otherwise.

__iter__(): Returns an iterator over the Parameter instances of this ParameterSet instance.

__len__(): The number of parameters this ParameterSet has.

get_fixed_pidx(param_name)

Returns the parameter index of the given fixed parameter.

Parameters:: param_name (str) – The name of the parameter.
Returns:: pidx (int) – The index of the fixed parameter.
Raises:: KeyError – If the given parameter is not part of the set of fixed parameters.

get_floating_pidx(param_name)

Returns the parameter index of the given floating parameter.

Parameters:: param_name (str) – The name of the parameter.
Returns:: pidx (int) – The index of the floating parameter.
Raises:: KeyError – If the given parameter is not part of the set of floating parameters.

generate_random_floating_param_initials(rss)

Generates a set of random initials for all floating parameters. A new random initial is defined as

lower_bound + RAND * (upper_bound - lower_bound),

where RAND is a uniform random variable between 0 and 1.

Parameters:: rss (RandomStateService instance) – The RandomStateService instance that should be used for drawing random numbers from.
Returns:: ri ((N_floating_params,)-shaped numpy ndarray) – The numpy 1D ndarray holding the generated random initial values.

has_fixed_param(param_name)

Checks if this ParameterSet instance has a fixed parameter named param_name.

Parameters:: param_name (str) – The name of the parameter.
Returns:: check (bool) – True if this ParameterSet instance has a fixed parameter of the given name, False otherwise.

has_floating_param(param_name)

Checks if this ParameterSet instance has a floating parameter named param_name.

Parameters:: param_name (str) – The name of the parameter.
Returns:: check (bool) – True if this ParameterSet instance has a floating parameter of the given name, False otherwise.

make_params_fixed(fix_params)

Fixes the given parameters to the given values.

Parameters:: fix_params (dict) – The dictionary defining the parameters that should get fixed to the given dictionary entry values.
Raises:: ValueError – If one of the given parameters is already a fixed parameter.

make_params_floating(float_params)

Makes the given parameters floating with the given initial value and within the given bounds.

Parameters:

float_params (dict) –

The dictionary defining the parameters that should get set to be floating. The format of a dictionary’s entry can be one of the following formats:

None
The parameter’s initial, minimal and maximal value should be taken from the parameter’s current settings.

initialfloat
The parameter’s initial value should be set to the given value. The minimal and maximal values of the parameter will be taken from the parameter’s current settings.

(initial, valmin, valmax)
The parameter’s initial value, minimal and maximal value should be set to the given values. If initial is set to None, the parameter’s current value will be used as initial value.

Raises:

ValueError – If one of the given parameters is already a floating parameter.

update_fixed_param_value_cache(): Updates the internal cache of the fixed parameter values. This method has to be called whenever the values of the fixed Parameter instances change.

copy()

Creates a deep copy of this ParameterSet instance.

Returns:: copy (ParameterSet instance) – The copied instance of this ParameterSet instance.

add_param(param, atfront=False)

Adds the given Parameter instance to this set of parameters.

Parameters:

param (instance of Parameter) – The parameter, which should get added.
atfront (bool) – Flag if the parameter should be added at the front of the parameter list. If set to False (default), it will be added at the back.

Returns:

self (instance of ParameterSet) – This ParameterSet instance so that multiple add_param calls can just be concatenated.

Raises:

TypeError – If param is not an instance of Parameter.
KeyError – If given parameter is already present in the set. The check is performed based on the parameter name.

has_param(param)

Checks if the given Parameter is already present in this ParameterSet instance. The check is performed based on the parameter name.

Parameters:: param (Parameter instance) – The Parameter instance that should be checked.
Returns:: check (bool) – True if the given parameter is present in this parameter set, False otherwise.

get_params_dict(floating_param_values)

Converts the given floating parameter values into a dictionary with the floating parameter names and values and also adds the fixed parameter names and their values to this dictionary.

Parameters:: floating_param_values (1D ndarray) – The ndarray holding the values of the floating parameters in the order that the floating parameters are defined.
Returns:: params_dict (dict) – The dictionary with the floating and fixed parameter names and values.

get_floating_params_dict(floating_param_values)

Converts the given floating parameter values into a dictionary with the floating parameter names and values.

Parameters:: floating_param_values (1D ndarray) – The ndarray holding the values of the floating parameters in the order that the floating parameters are defined.
Returns:: params_dict (dict) – The dictionary with the floating and fixed parameter names and values.

class skyllh.core.parameters.ParameterGrid(name, grid, delta=None, decimals=None)

Bases: object

This class provides a data holder for a parameter that has a set of discrete values on a grid. Thus, the parameter has a value grid. This class represents a one-dimensional grid.

Creates a new parameter grid.

Parameters:

name (str) – The name of the parameter.
grid (sequence of float) – The sequence of float values defining the discrete grid values of the parameter.
delta (float | None) – The width between the grid values. If set to None, the width is taken from the equal-distant grid values.
decimals (int | None) – The number of decimals the grid values should get rounded to. The maximal number of decimals is 16. If set to None, the number of decimals will be the maximum of the number of decimals of the first grid value and the number of decimals of the delta value.

static from_BinningDefinition(binning, delta=None, decimals=None)

Creates a ParameterGrid instance from a BinningDefinition instance.

Parameters:

binning (BinningDefinition instance) – The BinningDefinition instance that should be used to create the ParameterGrid instance from.
delta (float | None) – The width between the grid values. If set to None, the width is taken from the equal-distant grid values.
decimals (int | None) – The number of decimals the grid values should get rounded to. The maximal number of decimals is 16. If set to None, the number of decimals will be the maximum of the number of decimals of the first grid value and the number of decimals of the delta value.

Returns:

param_grid (instance of ParameterGrid) – The created ParameterGrid instance.

static from_range(name, start, stop, delta, decimals=None)

Creates a ParameterGrid instance from a range definition. The stop value will be the last grid point.

Parameters:

name (str) – The name of the parameter grid.
start (float) – The start value of the range.
stop (float) – The end value of the range.
delta (float) – The width between the grid values.
decimals (int | None) – The number of decimals the grid values should get rounded to. The maximal number of decimals is 16. If set to None, the number of decimals will be the maximum of the number of decimals of the first grid value and the number of decimals of the delta value.

Returns:

param_grid (instance of ParameterGrid) – The created ParameterGrid instance.

property name: The name of the parameter.

property decimals: (read-only) The number of significant decimals of the grid values.

property grid: The numpy.ndarray with the grid values of the parameter.

property delta: (read-only) The width (float) between the grid values.

property lower_bound: The lower bound of the parameter grid.

property ndim: The dimensionality of the parameter grid.

add_extra_lower_and_upper_bin(): Adds an extra lower and upper bin to this parameter grid. This is usefull when interpolation or gradient methods require an extra bin on each side of the grid.

copy(): Copies this ParameterGrid object and returns the copy.

round_to_nearest_grid_point(value)

Rounds the given value to the nearest grid point.

Parameters:: value (float | ndarray of float) – The value(s) to round.
Returns:: grid_point (float | ndarray of float) – The calculated grid point(s).

round_to_lower_grid_point(value)

Rounds the given value to the nearest grid point that is lower than the given value.

Note: If the given value is a grid point, that grid point will be: returned!

Parameters:: value (float | ndarray of float) – The value(s) to round.
Returns:: grid_point (float | ndarray of float) – The calculated grid point(s).

round_to_upper_grid_point(value)

Rounds the given value to the nearest grid point that is larger than the given value.

Note: If the given value is a grid point, the next grid point will be: returned!

Parameters:: value (float | ndarray of float) – The value(s) to round.
Returns:: grid_point (ndarray of float) – The calculated grid point(s).

class skyllh.core.parameters.ParameterGridSet(param_grids=None, **kwargs)

Bases: NamedObjectCollection

Describes a set of parameter grids.

Constructs a new ParameterGridSet object.

Parameters:: param_grids (sequence of instance of ParameterGrid | instance of ParameterGrid | None) – The ParameterGrid instances this instance of ParameterGridSet should get initialized with.

property ndim: The dimensionality of this parameter grid set. By definition it’s the number of parameters of the set.

property params_name_list: (read-only) The list of the parameter names.

property parameter_permutation_dict_list: (read-only) The list of parameter dictionaries constructed from all permutations of all the parameter values.

add_extra_lower_and_upper_bin(): Adds an extra lower and upper bin to all the parameter grids. This is usefull when interpolation or gradient methods require an extra bin on each side of the grid.

copy(): Copies this ParameterGridSet object and returns the copy.

class skyllh.core.parameters.ParameterModelMapper(models, **kwargs)

Bases: object

This class provides the parameter to model mapper. The parameter to model mapper provides the functionality to map a global parameter, usually a fit parameter, to a local parameter of a model, e.g. to a source, or a background model parameter.

Constructor of the parameter mapper.

Parameters:: models (sequence of instance of Model.) – The sequence of Model instances the parameter mapper can map global parameters to.

static is_global_fitparam_a_local_param(fitparam_id, params_recarray, local_param_names)

Determines if the given global fit parameter is a local parameter of the given list of local parameter names.

Parameters:

fitparam_id (int) – The ID of the global fit parameter.
params_recarray (instance of numpy record ndarray) – The (N_models,)-shaped numpy record ndarray holding the local parameter names and values of the models. See the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for the format of this record array.
local_param_names (list of str) – The list of local parameters.

Returns:

check (bool) – True if the global fit parameter translates to a local parameter contained in the local_param_names list, False otherwise.

static is_local_param_a_fitparam(local_param_name, params_recarray)

Checks if the given local parameter is a (partly) a fit parameter.

Parameters:

local_param_name (str) – The name of the local parameter.
params_recarray (instance of numpy record ndarray) – The (N_models,)-shaped numpy record ndarray holding the local parameter names and values of the models. See the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for the format of this record array.

Returns:

check (bool) – True if the given local parameter is (partly) a fit parameter.

property models: (read-only) The ModelCollection instance defining the models the mapper can map global parameters to.

property global_paramset: (read-only) The ParameterSet instance holding the list of global parameters.

property n_models: (read-only) The number of models the mapper knows about.

property n_global_params: (read-only) The number of defined global parameters.

property n_global_fixed_params: (read-only) The number of defined global fixed parameters.

property n_global_floating_params: (read-only) The number of defined global floating parameters.

property n_sources: (read-only) The number of source models the mapper knows about.

property unique_model_param_names: (read-only) The unique parameters names of all the models.

property unique_source_param_names: (read-only) The unique parameter names of the sources.

get_model_param_name(model_idx, gp_idx)

Retrieves the local parameter name of a given model and global parameter index.

Parameters:

model_idx (int) – The index of the model.
gp_idx (int) – The index of the global parameter.

Returns:

param_name (str | None) – The name of the local model parameter. It is None, if the given global parameter is not mapped to the given model.

get_gflp_idx(name)

Gets the index of the global floating parameter of the given name.

Parameters:: name (str) – The global floating parameter’s name.
Returns:: idx (int) – The index of the global floating parameter.

get_model_idx_by_name(name)

Determines the index within this ParameterModelMapper instance of the model with the given name.

Parameters:: name (str) – The model’s name.
Returns:: model_idx (int) – The model’s index within this ParameterModelMapper instance.
Raises:: KeyError – If there is no model of the given name.

get_src_model_idxs(sources=None)

Creates a numpy ndarray holding the indices of the requested source models.

Parameters:: sources (instance of SourceModel | sequence of SourceModel | None) – The requested sequence of source models. If set to None, all source models will be requested.
Returns:: src_model_idxs (numpy ndarray) – The (N_sources,)-shaped 1D ndarray holding the indices of the requested source models.

map_param(param, models=None, model_param_names=None)

Maps the given instance of Parameter to the given sequence of models this parameter model mapper knows about. Aliases for the given parameter can be specified for each individual model.

Parameters:

param (instance of Parameter) – The global parameter which should get mapped to one or more models.
models (sequence of Model instances) – The sequence of Model instances the parameter should get mapped to. The instances in the sequence must match Model instances specified at construction of this mapper.
model_param_names (str | sequence of str | None) – The name of the parameter of the model. Hence, the global parameter name can be different to the parameter name of the model. If None, the name of the global parameter will be used as model parameter name for all models.

Returns:

self (ParameterModelMapper) – The instance of this ParameterModelMapper, so that several map_param calls can be concatenated.

Raises:

KeyError – If there is already a model parameter of the same name defined for any of the given to-be-applied models.

create_model_params_dict(gflp_values, model)

Creates a dictionary with the fixed and floating parameter names and their values for the given model.

Parameters:

gflp_values (1D ndarray of float) – The ndarray instance holding the current values of the global floating parameters.
model (instance of Model | str | int) – The index of the model as it was defined at construction time of this ParameterModelMapper instance.

Returns:

model_param_dict (dict) – The dictionary holding the fixed and floating parameter names and values of the specified model.

create_src_params_recarray(gflp_values=None, sources=None)

Creates a numpy record ndarray with a field for each local source parameter name and parameter’s value. In addition each parameter field <name> has a field named <<name>:gpidx> which holds the index plus one of the corresponding global parameter for each source value. For values mapping to fixed parameters, the index is negative. Local parameter values that do not apply to a particular source are set to NaN. The parameter index in such cases is undefined. In addition to the parameter fields, the field :model_idx holds the index of the model for which the local parameter values apply.

Parameters:

gflp_values (numpy ndarray | None) – The (N_global_floating_param,)-shaped 1D ndarray holding the global floating parameter values. The order must match the order of parameter definition in this ParameterModelMapper instance. If set to None, the value numpy.nan will be used as parameter value for floating parameters.
sources (SourceModel | sequence of SourceModel | ndarray of int32 | None) – The sources which should be considered. If a ndarray of type int is provides, it must contain the global source indices. If set to None, all sources are considered.

Returns:

recarray (numpy structured ndarray) – The (N_sources,)-shaped numpy structured ndarray holding the local parameter names and their values for each requested source. It contains the following fields:

:model_idx
The field holding the index of the model to which the set of local parameters apply.

<name>
The field holding the value for the local parameter <name>. Not all local parameters apply to all sources. Example: “gamma”.

<name>:gpidx
The field holding the global parameter index plus one for the local parameter <name>. Example: “gamma:gpidx”. Indices for values mapping to fixed parameters are negative.

create_global_params_dict(gflp_values)

Converts the given global floating parameter values into a dictionary holding the names and values of all floating and fixed parameters.

Parameters:: gflp_values (numpy ndarray) – The (n_global_floating_params,)-shaped 1D numpy ndarray holding the values of the global floating parameters.
Returns:: params_dict (dict) – The dictionary holding the parameter name and values of all floating and fixed parameters.

create_global_floating_params_dict(gflp_values)

Converts the given global floating parameter values into a dictionary holding the names and values of all floating parameters.

Parameters:: gflp_values (numpy ndarray) – The (n_global_floating_params,)-shaped 1D numpy ndarray holding the values of the global floating parameters.
Returns:: params_dict (dict) – The dictionary holding the parameter name and values of all floating parameters.

get_local_param_is_global_floating_param_mask(local_param_names)

Checks which local parameter name is mapped to a global floating parameter.

Parameters:: local_param_names (sequence of str) – The sequence of the local parameter names to test.
Returns:: mask (instance of ndarray) – The (N_local_param_names,)-shaped numpy ndarray holding the mask for each local parameter name if it is mapped to a global floating parameter.

skyllh.core.pdf module

class skyllh.core.pdf.PDFAxis(name, vmin, vmax, *args, **kwargs)

Bases: object

This class describes an axis of a PDF. It’s main purpose is to define the allowed variable space of the PDF. So this information can be used to plot a PDF or a PDF ratio.

Creates a new axis for a PDF.

Parameters:

name (str) – The name of the axis.
vmin (float) – The minimal value of the axis.
vmax (float) – The maximal value of the axis.

property name: The name of the axis.

property vmin: The minimal value of the axis.

property vmax: The maximal value of the axis.

property range: (read-only) The 2-element tuple (vmin,vmax) of the axis.

property length: (read-only) The length of the axis as float. It’s defined as length = vmax - vmin.

__eq__(other): Checks if this PDFAxis object has the same properties than the given other PDFAxis object.

class skyllh.core.pdf.PDFAxes(axes=None, **kwargs)

Bases: NamedObjectCollection

This class describes the set of PDFAxis objects defining the dimensionality of a PDF.

Creates a new PDFAxes instance.

Parameters:: axes (sequence of instance of PDFAxis | None) – The sequence of instance of PDFAxis for this PDFAxes instance. If set to None, the PDFAxes instance will be empty.

static union(*axeses)

Creates a PDFAxes instance that is the union of the given PDFAxes instances.

Parameters:: *axeses (PDFAxes instances) – The sequence of PDFAxes instances.
Returns:: axes (PDFAxes instance) – The newly created PDFAxes instance that holds the union of the PDFAxis instances provided by all the PDFAxes instances.

is_same_as(axes)

Checks if this PDFAxes object has the same axes and range then the given PDFAxes object.

Parameters:: axes (instance of PDFAxes | sequence of PDFAxis) – The instance of PDFAxes or the sequence of instance of PDFAxis that should be compared to the axes of this PDFAxes instance.
Returns:: check (bool) – True, if this PDFAxes and the given PDFAxes have the same axes and ranges. False otherwise.

class skyllh.core.pdf.IsBackgroundPDF(*args, **kwargs)

Bases: object

This is a classifier class that can be used by other classes to indicate that the class describes a background PDF. This is useful for type checking.

Constructor method. Gets called when the an instance of a class is created which derives from this IsBackgroundPDF class.

__mul__(other)

Creates a BackgroundPDFProduct instance for the multiplication of this background PDF and another background PDF.

Parameters:: other (instance of IsBackgroundPDF) – The instance of IsBackgroundPDF, which is the other background PDF.

class skyllh.core.pdf.IsSignalPDF(*args, **kwargs)

Bases: object

This is a classifier class that can be used by other classes to indicate that the class describes a signal PDF.

Constructor method. Gets called when the an instance of a class is created which derives from this IsSignalPDF class.

__mul__(other)

Creates a SignalPDFProduct instance for the multiplication of this signal PDF and another signal PDF.

Parameters:: other (instance of IsSignalPDF) – The instance of IsSignalPDF, which is the other signal PDF.

class skyllh.core.pdf.PDF(pmm=None, param_set=None, **kwargs)

Bases: HasConfig

This is the abstract base class for all probability distribution function (PDF) models. All PDF model classes must be derived from this class. Mathematically, it represents \(f(\vec{x}|\vec{p})\), where \(\vec{x}\) is the event data and \(\vec{p}\) is the set of parameters the PDF is given for.

Creates a new PDF instance.

Parameters:

pmm (instance of ParameterModelMapper | None) – The instance of ParameterModelMapper defining the global parameters and their mapping to local model/source parameters. It can be None, if the PDF does not depend on any parameters.
param_set (instance of Parameter | sequence of instance of Parameter | instance of ParameterSet | None) – If this PDF depends on parameters, this set of parameters defines them. If a single parameter instance is given a ParameterSet instance will be created holding this single parameter. If set to None, this PDF will not depend on any parameters.

property axes: (read-only) The PDFAxes object holding the PDFAxis objects for the dimensions of the PDF.

property ndim: The dimensionality of the PDF. It’s defined as the number of PDFAxis objects this PDF object has. Note, that the internal dimensionality might be smaller than this.

property pmm: The instance of ParameterModelMapper that defines the global parameters and their mapping to local model/source parameters. It can be None if the PDF does not depend on any parameters.

property param_set: The ParameterSet instance defining the set of parameters this PDF depends on. It is None, if this PDF does not depend on any parameters.

property is_signal_pdf: (read-only) The flag if this PDF instance represents a signal PDF. A PDF is a signal PDF if it derives from the IsSignalPDF class.

property is_background_pdf: (read-only) The flag if this PDF instance represents a background PDF. A PDF is a background PDF if it derives from the IsBackgroundPDF class.

add_axis(axis): Adds the given PDFAxis object to this PDF.

abstract assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

This method is supposed to check if this PDF is valid for all the given trial data. This means, it needs to check if there is a PDF value for each trial data event that will be used in the likelihood evaluation. This is just a seatbelt. The method must raise a ValueError if the PDF is not valid for the given trial data.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the trial data is outside the PDF’s value space.

initialize_for_new_trial(tdm, tl=None, **kwargs)

This method is called when a new trial is initialized. Derived classes can use this call hook to pre-compute time-expensive data, which do not depend on any fit parameters.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data.
tl (instance of TimeLord | None) – The optional instance of TimeLord to measure timing information.

abstract get_pd(tdm, params_recarray=None, tl=None)

This abstract method is supposed to calculate the probability density for the specified events given the specified parameter values.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the data events for which the probability density should be calculated. What data fields are required is defined by the derived PDF class and depends on the application.
params_recarray (numpy record ndarray | None) – The (N_models,)-shaped numpy structured ndarray holding the local parameter names and values of the models. The models are defined by the ParameterModelMapper instance. The parameter values can be different for the different models. In case of the signal PDF, the models are the sources. The record array must contain two fields for each source parameter, one named <name> with the source’s local parameter name holding the source’s local parameter value, and one named <name:gpidx> holding the global parameter index plus one for each source value. For values mapping to non-fit parameters, the index should be negative. This can be None for PDFs that do not depend on any parameters.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to measure timing information.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density for each event. The length of this 1D array depends on the number of sources and the events belonging to those sources. In the worst case the length is N_values = N_sources * N_trial_events. The assignment of values to sources is given by the src_evt_idxs property.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter. The key of the dictionary is the id of the global fit parameter. The value is a (N_values,)-shaped numpy ndarray.

class skyllh.core.pdf.PDFProduct(pdf1, pdf2, **kwargs)

Bases: PDF

The PDFProduct class represents the product of two PDF instances, i.e. pdf1 * pdf2. It is derived from the PDF class and hence is a PDF itself.

Creates a new PDFProduct instance, which implements the operation pdf1 * pdf2. The axes of the two PDF instances will be merged.

Parameters:

pdf1 (instance of PDF) – The left-hand-side PDF in the operation pdf1 * pdf2.
pdf2 (instance of PDF) – The right-hand-side PDF in the operation pdf1 * pdf2.

property pdf1: The left-hand-side PDF in the operation pdf1 * pdf2. It must be an instance of PDF.

property pdf2: The right-hand-side PDF in the operation pdf1 * pdf2. It must be an instance of PDF.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Calls the assert_is_valid_for_trial_data() method of pdf1 and pdf2.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that should be used to get the trial data from.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If this PDF does not cover the trial data.

initialize_for_new_trial(tdm, tl=None, **kwargs)

Calls the initialize_for_new_trial method of the two PDF instances of this PDF product.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial event data.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

get_pd(tdm, params_recarray=None, tl=None)

Calculates the probability density for the trial events given the specified parameters by calling the get_pd method of pdf1 and pdf2 and combining the two property densities by multiplication. The gradients will be calculated using the product rule of differentiation.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial event data for which the PDF values should get calculated.
params_recarray (instance of numpy.ndarray | None) – The (N_models,)-shaped structured numpy ndarray holding the parameter values of the models. The the documentation of the get_pd() method of the PDF class for further information.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pd (instance of numpy.ndarray) – The (N_events,)-shaped numpy ndarray holding the probability density for each event. In case of a signal PDF product the shape will be (N_sources,N_events).
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each fit parameter. The key of the dictionary is the id of the global fit parameter. The value is the (N_events,)-shaped numpy ndarray. In case of a signal PDF product, the value is a (N_sources,N_events)-shaped ndarray.

class skyllh.core.pdf.SignalPDFProduct(pdf1, pdf2, **kwargs)

Bases: PDFProduct, IsSignalPDF

This class provides a signal PDF that is the product of two signal PDF instances.

Creates a new PDF product of two signal PDFs.

class skyllh.core.pdf.BackgroundPDFProduct(pdf1, pdf2, **kwargs)

Bases: PDFProduct, IsBackgroundPDF

This class provides a background PDF that is the product of two background PDF instances.

Creates a new PDF product of two background PDFs.

class skyllh.core.pdf.SpatialPDF(ra_range, dec_range, **kwargs)

Bases: PDF

This is the abstract base class for a spatial PDF model. A spatial PDF has two axes, right-ascension (ra) and declination (dec).

Constructor of a spatial PDF. It adds the PDF axes “ra” and “dec” with the specified ranges of coverage.

Parameters:

ra_range (2-element tuple) – The tuple specifying the right-ascension range this PDF covers.
dec_range (2-element tuple) – The tuple specifying the declination range this PDF covers.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if this spatial PDF is valid for all the given experimental data. It checks if all the data is within the right-ascension and declination range.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial data. The following data fields must exist:
- ’ra’float
  The right-ascension of the data event.
- ’dec’float
  The declination of the data event.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the data is outside the right-ascension or declination range.

class skyllh.core.pdf.EnergyPDF(*args, **kwargs)

Bases: PDF

This is the abstract base class for an energy PDF.

Creates a new PDF instance.

Parameters:

pmm (instance of ParameterModelMapper | None) – The instance of ParameterModelMapper defining the global parameters and their mapping to local model/source parameters. It can be None, if the PDF does not depend on any parameters.
param_set (instance of Parameter | sequence of instance of Parameter | instance of ParameterSet | None) – If this PDF depends on parameters, this set of parameters defines them. If a single parameter instance is given a ParameterSet instance will be created holding this single parameter. If set to None, this PDF will not depend on any parameters.

class skyllh.core.pdf.TimePDF(livetime, time_flux_profile, **kwargs)

Bases: PDF

This is the abstract base class for a time PDF. It consists of a Livetime instance and a TimeFluxProfile instance. Together they construct the actual time PDF, which has detector down-time taking into account.

Creates a new time PDF instance for a given time flux profile and detector live time.

Parameters:

livetime (instance of Livetime) – An instance of Livetime, which provides the detector live-time information.
time_profile (instance of TimeFluxProfile) – The signal’s time flux profile.
**kwargs – Additional keyword arguments are passed to the constructor of the base class, PDF.

property livetime: The instance of Livetime, which provides the detector live-time information.

property time_flux_profile: The instance of TimeFluxProfile providing the physical time flux profile.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if the time PDF is valid for all the given trial data. It checks if the time of all events is within the defined time axis of the PDF.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager that holds the trial data. The following data fields must exist:

'time'float
The time of the data event.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the data is outside the time range of the PDF.

class skyllh.core.pdf.MultiDimGridPDF(pmm, axis_binnings, path_to_pdf_splinetable=None, pdf_grid_data=None, norm_factor_func=None, cache_pd_values=False, **kwargs)

Bases: PDF

This class provides a multi-dimensional PDF. The PDF is created from pre-calculated PDF data on a grid. The grid data is either interpolated using a scipy.interpolate.RegularGridInterpolator instance, or is provided as a photospline fit through a photospline table file.

Creates a new PDF instance for a multi-dimensional PDF given as PDF values on a grid or as PDF values stored in a photospline table.

In case of PDF values on a grid, the grid data is interpolated with a scipy.interpolate.RegularGridInterpolator instance. As grid points the bin edges of the axis binning definitions are used.

In case of PDF values stored in a photospline table, this table is loaded via the photospline.SplineTable class.

Note:

By definition this PDF must not depend on any fit parameters.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper that defines the mapping of the global parameters to local model parameters.
axis_binnings (instance of BinningDefinition | sequence of instance of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each instance of BinningDefinition defines the event field name that should be used for querying the PDF.
path_to_pdf_splinetable (str | None) – The path to the file containing the spline table, which contains a pre-computed fit to the grid data. If specified, pdf_grid_data must be None.
pdf_grid_data (instance of numpy ndarray | None) – The n-dimensional numpy ndarray holding the PDF values at given grid points. The grid points must match the bin edges of the given BinningDefinition instances of the axis_binnings argument. If specified, path_to_pdf_splinetable must be None.
norm_factor_func (callable | None) –
The function that calculates a possible required normalization factor for the PDF value based on the event properties. The call signature of this function must be

__call__(pdf, tdm, params_recarray, eventdata, evt_mask=None),

where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the event data for which to calculate the PDF values, params_recarray is a numpy structured ndarray holding the local parameter names and values, eventdata is is a (V,N_values)-shaped numpy ndarray holding the event data necessary for this PDF, and evt_mask is an optional (N_values,)-shaped numpy ndarray holding the mask for the events, i.e. rows in eventdata, which should be considered. If None, all events should be considered.
cache_pd_values (bool) – Flag if the probability density values should be cached. The evaluation of the photospline fit might be slow and caching the probability density values might increase performance.

property axis_binning_list: The list of BinningDefinition instances for each PDF axis. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.

property basis_function_indices: The (V,N_values)-shaped numpy.ndarray of int holding the basis function indices of the photospline table for the current trial eventdata.

property norm_factor_func

The function that calculates the possible required normalization factor. The call signature of this function must be

__call__(pdf, tdm, params_recarray, eventdata, evt_mask=None),

where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the events for which to calculate the PDF values, params_recarray is a numpy structured ndarray holding the local parameter names and values, eventdata is a (V,N_values)-shaped numpy ndarray holding the event data necessary for this PDF, and evt_mask is an optional (N_values,)-shaped numpy ndarray holding the mask for the events, i.e. rows in eventdata, which should be considered. If None, all events should be considered.. This property can be set to None. In that case a unity returning function is used.

property cache_pd_values: Flag if the probability density values should be cached.

property pdf: (read-only) The instance of RegularGridInterpolator or instance of photospline.SplineTable that represents the internal PDF object.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if the PDF is valid for all values of the given evaluation data. The evaluation data values must be within the ranges of the PDF axes.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial data for which the PDF should be valid.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If any of the evaluation trial data is out of its axis range.

initialize_for_new_trial(tdm, tl=None, **kwargs): This method is called whenever a new trial is initialized.

get_pd_with_eventdata(tdm, params_recarray, eventdata, evt_mask=None, tl=None)

Calculates the probability density value for the given eventdata.

This method is useful when PDF values for the same trial data need to be evaluated.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial event data for which the PDF values should get calculated.
params_recarray (instance of numpy structured ndarray | None) – The (N_models,)-shaped numpy structured ndarray holding the local parameter names and values of the models. By definition, this PDF does not depend on any parameters.
eventdata (instance of numpy.ndarray) – The (V,N_values)-shaped numpy ndarray holding the V data attributes for each of the N_values events needed for the evaluation of the PDF.
evt_mask (instance of numpy ndarray | None) – The (N_values,)-shaped numpy ndarray defining the elements of the N_values pd array for which pd values should get calculated. This is needed to determine if the requested pd values are already cached.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to measure timing information.

Returns:

pd ((N,)-shaped numpy ndarray) – The (N,)-shaped numpy ndarray holding the probability density value for each model and event. The length of this array depends on the evt_mask argument. Only values are returned where evt_mask evaluates to True. If evt_mask is set to None, the length is N_values.

static create_eventdata_for_sigpdf(tdm, axes)

Creates the (V,N_values)-shaped eventdata ndarray necessary for evaluating the signal PDF.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial event data.
axes (instance of PDFAxes) – The instance of PDFAxes defining the data field names for the PDF.

Returns:

eventdata (instance of numpy.ndarray) – The (V,N_values)-shaped numpy ndarray holding the event data for evaluating the signal PDF.

static create_eventdata_for_bkgpdf(tdm, axes)

Creates the (V,N_values)-shaped eventdata ndarray necessary for evaluating the background PDF.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial event data.
axes (instance of PDFAxes) – The instance of PDFAxes defining the data field names for the PDF.

get_pd(tdm, params_recarray=None, tl=None)

Calculates the probability density for the given trial events given the specified local parameters.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial event data for which the PDF values should get calculated.
params_recarray (instance of numpy structured ndarray | None) – The (N_models,)-shaped numpy structured ndarray holding the local parameter names and values of the models. By definition, this PDF does not depend on any parameters.
tl (instance of TimeLord | None) – The optional instance of TimeLord that should be used to measure timing information.

Returns:

pd ((N_values,)-shaped numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density value for each source and event.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter. Since this PDF does not depend on any fit parameter, this is an empty dictionary.

class skyllh.core.pdf.PDFSet(param_grid_set, **kwargs)

Bases: HasConfig

This class describes a set of PDF objects which are related to each other via different values of a set of parameters. A signal PDF usually consists of multiple same-kind PDFs for different signal parameters. In general background PDFs could have parameters, too.

This class has the params_grid_set property holding the set of parameter grids. Also it holds a dictionary with the PDFs for the different sets of parameter values. PDF instances can be added via the add_pdf() method and can be retrieved via the get_pdf() method.

Constructs a new PDFSet instance.

Parameters:: param_grid_set (instance of ParameterGrid |) – instance of ParameterGridSet The instance of ParameterGridSet with the parameter grids defining the discrete parameter values for which the PDFs of this PDF set are made for.

property param_grid_set: The ParameterGridSet instance defining the grid values of the different parameters.

property gridparams_list: (read-only) The list of dictionaries of all the parameter permutations on the grid.

property pdf_keys: (read-only) The list of stored PDF object keys.

property axes: (read-only) The PDFAxes object of one of the PDFs of this PDF set. All PDFs of this set are supposed to have the same axes.

__contains__(key)

Checks if the given key exists in this PDFSet instance.

Parameters:: key (dict | int) – If a dictionary is provided, it must be the gridparams dictionary containing the grid parameter names and vales. If an integer is provided, it must be the hash of the gridparams dictionary.

__getitem__(key): Implements the access operator self[gridparams_hash].

__iter__(): Returns an iterator of the PDF dictionary of this PDFSet.

items(): Returns an iterator over the (gridparams_hash, PDF) pairs of this PDFSet instance.

values(): Returns an iterator over the PDF instances of the PDFSet instance.

make_key(gridparams)

Creates the key for the given grid parameter dictionary.

Parameters:: gridparams (dict) – The dictionary holding the grid parameter names and values.
Returns:: key (int) – The key for the given grid parameter dictionary.

add_pdf(pdf, gridparams)

Adds the given PDF object for the given parameters to the internal registry. If this PDF set is not empty, the to-be-added PDF must have the same axes than the already added PDFs.

Parameters:

pdf (instance of PDF) – The PDF instance, that should be added
gridparams (dict) – The dictionary with the grid parameter values, which identify the PDF object.

Raises:

KeyError – If the given PDF was already added for the given set of parameters.
TypeError – If any of the method’s arguments has the wrong type.
ValueError – If the axes of the given PDFs are not the same as the axes of the already added PDFs.

get_pdf(gridparams)

Retrieves the PDF object for the given set of fit parameters.

Parameters:: gridparams (dict | int) – The dictionary with the grid parameter names and values for which the PDF object should get retrieved. If an integer is given, it is assumed to be the PDF key.
Returns:: pdf (instance if PDF) – The PDF instance for the given parameters.
Raises:: KeyError – If no PDF instance was created for the given set of parameters.

initialize_for_new_trial(tdm, tl=None, **kwargs)

This method is called whenever a new trial data is available. It calls the initialize_for_new_trial() method of each PDF.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if the PDFs of this PDFSet instance are valid for all the given trial data events. Since all PDFs should have the same axes, only the first PDF will be checked. It calls the assert_is_valid_for_trial_data() method of the first PDF instance.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the data is outside the axes range of the PDF.

get_pd(gridparams, tdm, params_recarray=None, tl=None)

Calls the get_pd method of the PDF instance that belongs to the given grid parameter values gridparams.

Parameters:

gridparams (dict) – The dictionary holding the parameter values, which define PDF instance within this PDFSet instance. Note, that the parameter values must match a set of parameter grid values for which a PDF instance has been created and added to this PDFSet instance.
tdm (instance of TrialDataManager) – The TrialDataManager instance holding the data events for which the probability density of the events should be calculated.
params_recarray (instance of ndarray | None) – The numpy record ndarray holding the parameter name and values for each source model.

Returns:

pd (numpy ndarray) – The 1D numpy ndarray holding the probability density values for each event and source. See skyllh.core.pdf.PDF.get_pd() for further information.
grads (dict) – The dictionary holding the gradient values for each global fit parameter. See skyllh.core.pdf.PDF.get_pd() for further information.

skyllh.core.pdfratio module

class skyllh.core.pdfratio.PDFRatio(sig_param_names=None, bkg_param_names=None, **kwargs)

Bases: HasConfig

Abstract base class for a signal over background PDF ratio class. It defines the interface of a signal over background PDF ratio class.

Creates a new PDFRatio instance.

Parameters:

sig_param_names (sequence of str | str | None) – The sequence of signal parameter names this PDFRatio instance is a function of.
bkg_param_names (sequence of str | str | None) – The sequence of background parameter names this PDFRatio instance is a function of.

property n_params: (read-only) The number of parameters the PDF ratio depends on. This is the sum of signal and background parameters.

property param_names: (read-only) The list of parameter names this PDF ratio is a function of. This is the superset of signal and background parameter names.

property n_sig_params: (read-only) The number of signal parameters the PDF ratio depends on.

property n_bkg_params: (read-only) The number of background parameters the PDF ratio depends on.

property sig_param_names: The list of signal parameter names this PDF ratio is a function of.

property bkg_param_names: The list of background parameter names this PDF ratio is a function of.

abstract initialize_for_new_trial(tdm, tl=None, **kwargs)

Initializes the PDFRatio instance for a new trial. This method can be utilized to pre-calculate PDFRatio values that do not depend on any fit parameters.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial data.
tl (instance of TimeLord) – The optional instance of TimeLord to measure timing information.

abstract get_ratio(tdm, src_params_recarray, tl=None)

Retrieves the PDF ratio value for each given trial data events (and sources), given the given set of parameters.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
src_params_recarray (instance of numpy record ndarray | None) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios (instance of ndarray) – The (N_values,)-shaped 1d numpy ndarray of float holding the PDF ratio value for each trial event and source.

abstract get_gradient(tdm, src_params_recarray, fitparam_id, tl=None)

Retrieves the PDF ratio gradient for the global fit parameter fitparam_id for each trial data event and source, given the given set of parameters src_params_recarray for each source.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio gradient values should get calculated.
src_params_recarray (instance of numpy structured ndarray) – The (N_sources,)-shaped numpy structured ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
fitparam_id (int) – The ID of the global fit parameter for which the gradient should get calculated.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

gradient (instance of ndarray | 0) – The (N_values,)-shaped 1d numpy ndarray of float holding the PDF ratio gradient value for each source and trial data event. If the PDF ratio does not depend on the given global fit parameter, 0 should be returned.

__mul__(other): Implements the mathematical operation new = self * other, where other is an instance of PDFRatio. It creates an instance of PDFRatioProduct holding the two PDFRatio instances.

class skyllh.core.pdfratio.PDFRatioProduct(pdfratio1, pdfratio2, **kwargs)

Bases: PDFRatio

This is the mathematical product of two PDFRatio instances, which is a PDFRatio instance again.

Creates a new PDFRatioProduct instance representing the product of two PDFRatio instances.

property pdfratio1: The first PDFRatio instance in the muliplication pdfratio1 * pdfratio2.

property pdfratio2: The second PDFRatio instance in the muliplication pdfratio1 * pdfratio2.

initialize_for_new_trial(**kwargs): Initializes the PDFRatioProduct instance for a new trial. It calls the initialize_for_new_trial() method of each of the two PDFRatio instances.

get_ratio(tdm, src_params_recarray, tl=None)

Retrieves the PDF ratio product value for each trial data event and source, given the given set of parameters for all sources.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
src_params_recarray (instance of numpy record ndarray) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios (instance of ndarray) – The (N_values,)-shaped 1d numpy ndarray of float holding the product of the PDF ratio values for each trial event and source. The PDF ratio product value for each trial event.

get_gradient(tdm, src_params_recarray, fitparam_id, tl=None)

Retrieves the PDF ratio product gradient for the global fit parameter with parameter ID fitparam_id for each trial data event and source, given the set of parameters src_params_recarray for all sources.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
src_params_recarray (instance of numpy record ndarray | None) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
fitparam_id (int) – The ID of the global fit parameter for which the gradient should get calculated.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

gradient (instance of ndarray | 0) – The (N_values,)-shaped 1d numpy ndarray of float holding the PDF ratio gradient value for each trial event and source. If none of the two PDFRatio instances depend on the given global fit parameter, the scalar value 0 is returned.

class skyllh.core.pdfratio.SourceWeightedPDFRatio(dataset_idx, src_detsigyield_weights_service, pdfratio, **kwargs)

Bases: PDFRatio

This class provides the calculation of a source weighted PDF ratio for multiple sources:

\[\mathcal{R}_i(\vec{p}_{\mathrm{s}}) = \frac{1}{A(\vec{p}_{\mathrm{s}})} \sum_{k=1}^{K} a_k(\vec{p}_{\mathrm{s}_k}) \mathcal{R}_{i,k} (\vec{p}_{\mathrm{s}_k})\]

Creates a new SourceWeightedPDFRatio instance.

Parameters:

dataset_idx (int) – The index of the dataset. It is used to access the source detector signal yield weight.
src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService) – The instance of SrcDetSigYieldWeightsService providing the source detector signal yield weights, i.e. the product of the theoretical source weight with the detector signal yield.
pdfratio (instance of PDFRatio) – The instance of PDFRatio providing the PDF ratio values and derivatives.

property dataset_idx: (read-only) The index of the dataset for which this SourceWeightedPDFRatio instance is made.

property src_detsigyield_weights_service: (read-only) The instance of SrcDetSigYieldWeightsService providing the source detector signal yield weights, i.e. the product of the theoretical source weight with the detector signal yield.

property pdfratio: (read-only) The PDFRatio instance that is used to calculate the source weighted PDF ratio.

initialize_for_new_trial(tdm, tl=None, **kwargs)

Initializes the PDFRatio instance for a new trial. It calls the initialize_for_new_trial() method of the PDFRatio instance.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial data.
tl (instance of TimeLord) – The optional instance of TimeLord to measure timing information.

get_ratio(tdm, src_params_recarray, tl=None)

Retrieves the PDF ratio value for each given trial data events (and sources), given the given set of parameters.

Note

This method uses the source detector signal yield weights service. Hence, the skyllh.core.weights.SrcDetSigYieldWeightsService.calculate() method needs to be called prior to calling this method.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
src_params_recarray (instance of numpy record ndarray) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios (instance of ndarray) – The (N_selected_events,)-shaped 1d numpy ndarray of float holding the PDF ratio value for each selected trial data event.

get_gradient(tdm, src_params_recarray, fitparam_id, tl=None)

Retrieves the PDF ratio gradient for the parameter fitparam_id for each trial data event, given the given set of parameters src_params_recarray for each source.

Note

This method requires that the get_ratio method has been called prior to calling this method.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio gradient values should get calculated.
src_params_recarray (instance of numpy record ndarray) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the documentation of the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
fitparam_id (int) – The ID of the global fit parameter for which the gradient should get calculated.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

gradient (instance of ndarray | 0) – The (N_selected_events,)-shaped 1d numpy ndarray of float holding the PDF ratio gradient value for each trial data event. If the PDF ratio does not depend on the given global fit parameter, 0 will be returned.

class skyllh.core.pdfratio.SigOverBkgPDFRatio(sig_pdf, bkg_pdf, same_axes=True, zero_bkg_ratio_value=1.0, **kwargs)

Bases: PDFRatio

This class implements a generic signal-over-background PDF ratio for a signal and a background PDF instance. It takes a signal PDF of type pdf_type and a background PDF of type pdf_type and calculates the PDF ratio.

Creates a new signal-over-background PDF ratio instance.

Parameters:

sig_pdf (class instance derived from pdf_type, IsSignalPDF) – The instance of the signal PDF.
bkg_pdf (class instance derived from pdf_type, IsBackgroundPDF) – The instance of the background PDF.
same_axes (bool) – Flag if the signal and background PDFs are supposed to have the same axes. Default is True.
zero_bkg_ratio_value (float) – The value of the PDF ratio to take when the background PDF value is zero. This is to avoid division by zero. Default is 1.

property sig_pdf: The signal PDF object used to create the PDF ratio.

property bkg_pdf: The background PDF object used to create the PDF ratio.

property zero_bkg_ratio_value: The value of the PDF ratio to take when the background PDF value is zero. This is to avoid division by zero.

initialize_for_new_trial(tdm, tl=None, **kwargs): Initializes the PDFRatio instance for a new trial. It calls the assert_is_valid_for_trial_data() of the signal and background PDF instances.

get_ratio(tdm, src_params_recarray, tl=None)

Calculates the PDF ratio for the given trial events.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should be calculated.
src_params_recarray (instance of numpy record ndarray) – The (N_sources,)-shaped numpy record ndarray holding the local parameter names and values of the sources. See the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios (instance of ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density ratio for each event and source.

get_gradient(tdm, src_params_recarray, fitparam_id, tl=None)

Retrieves the gradient of the PDF ratio w.r.t. the given parameter.

Note

This method uses cached values from the get_ratio() method. Hence, that method needs to be called prior to this method.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data.
src_params_recarray (instance of numpy record ndarray | None) – The (N_models,)-shaped numpy record ndarray holding the parameter names and values of the models. See skyllh.core.pdf.PDF.get_pd() for more information. This can be None, if the signal and background PDFs do not depend on any parameters.
fitparam_id (int) – The ID of the global fit parameter for which the gradient should get calculated.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

grad (instance of ndarray) – The (N_values,)-shaped 1d numpy ndarray of float holding the PDF ratio gradient value for each source and trial event.

class skyllh.core.pdfratio.SigSetOverBkgPDFRatio(sig_pdf_set, bkg_pdf, interpolmethod_cls=None, **kwargs)

Bases: PDFRatio

Class for a PDF ratio class that takes a PDFSet as signal PDF and a PDF as background PDF. The signal PDF depends on signal parameters and an interpolation method defines how the PDF ratio gets interpolated between the parameter grid values.

Constructor called by creating an instance of a class which is derived from this PDFRatio class.

Parameters:

sig_pdf_set (instance of PDFSet and instance of IsSignalPDF) – The PDF set, which provides signal PDFs for a set of discrete signal parameter values.
bkg_pdf (instance of PDF and instance of IsBackgroundPDF) – The background PDF instance.
interpolmethod_cls (class of GridManifoldInterpolationMethod | None) – The class implementing the parameter interpolation method for the PDF ratio manifold grid. If set to None (default), the skyllh.core.interpolate.Parabola1DGridManifoldInterpolationMethod will be used for 1-dimensional parameter manifolds.

property bkg_pdf: The background PDF instance, derived from IsBackgroundPDF.

property sig_pdf_set: The signal PDFSet instance, derived from IsSignalPDF.

property interpolmethod_cls: The class derived from GridManifoldInterpolationMethod implementing the interpolation of the parameter manifold.

initialize_for_new_trial(tdm, tl=None, **kwargs)

Initializes the PDFRatio instance for a new trial. It calls the assert_is_valid_for_trial_data() of the signal PDFSet instance and the background PDF instance.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

skyllh.core.pdfratio_fill module

This module defines the interface and provides particular implementations of PDF ratio fill methods. For a binned PDF ratio it could happen, that some bins don’t have background information but signal information is available. Hence, a ratio cannot be computed for those bins. The PDF ratio fill method specifies how those bins should get filled.

class skyllh.core.pdfratio_fill.PDFRatioFillMethod(*args, **kwargs)

Bases: object

Abstract base class to implement a PDF ratio fill method. It can happen, that there are empty background bins but where signal could possibly be. A PDFRatioFillMethod implements what happens in such cases.

abstract __call__(ratios, sig_pd_h, bkg_pd_h, sig_mask_mc_covered, sig_mask_mc_covered_zero_physics, bkg_mask_mc_covered, bkg_mask_mc_covered_zero_physics)

The __call__ method is supposed to fill the ratio bins (array) with the signal / background ratio values. For bins (array elements), where the division is undefined, e.g. due to zero background, the fill method decides how to fill those bins.

Note: Bins which have neither signal monte-carlo nor background: monte-carlo coverage, are undefined about their signal-ness or background-ness by construction.

Parameters:

ratios (ndarray of float) – The multi-dimensional array for the final ratio bins. The shape is the same as the sig_h and bkg_h ndarrays.
sig_pd_h (ndarray of float) – The multi-dimensional array (histogram) holding the signal probability densities.
bkg_pd_h (ndarray of float) – The multi-dimensional array (histogram) holding the background probability densities.
sig_mask_mc_covered (ndarray of bool) – The mask array indicating which array elements of sig_pd_h have monte-carlo coverage.
sig_mask_mc_covered_zero_physics (ndarray of bool) – The mask array indicating which array elements of sig_pd_h have monte-carlo coverage but don’t have physics contribution.
bkg_mask_mc_covered (ndarray of bool) – The mask array indicating which array elements of bkg_pd_h have monte-carlo coverage. In case of experimental data as background, this mask indicate where (experimental data) background is available.
bkg_mask_mc_covered_zero_physics (ndarray of bool) – The mask array ndicating which array elements of bkg_pd_h have monte-carlo coverage but don’t have physics contribution. In case of experimental data as background, this mask contains only False entries.

Returns:

ratios (ndarray) – The array holding the final ratio values.

class skyllh.core.pdfratio_fill.Skylab2SkylabPDFRatioFillMethod(**kwargs)

Bases: PDFRatioFillMethod

This PDF ratio fill method implements the exact same fill method as in the skylab2 software named “skylab”. It exists just for comparsion and backward compatibility reasons. In general, it should not be used, because it does not distinguish between bins with MC converage and physics model contribution, and those with MC coverage and no physics model contribution!

property signallike_percentile: The percentile of signal-like ratios, which should be taken as the ratio value for ratios with no background probability. This percentile must be given as a float value in the range [0, 100] inclusively.

__call__(ratio, sig_pd_h, bkg_pd_h, sig_mask_mc_covered, sig_mask_mc_covered_zero_physics, bkg_mask_mc_covered, bkg_mask_mc_covered_zero_physics): Fills the ratio array ratio. For more information see the documentation of skyllh.core.pdfratio_fill.PDFRatioFillMethod.__call__().

class skyllh.core.pdfratio_fill.MostSignalLikePDFRatioFillMethod(signallike_percentile=99.0, **kwargs)

Bases: PDFRatioFillMethod

PDF ratio fill method to set the PDF ratio to the most signal like PDF ratio for bins, where there is signal but no background coverage.

Creates the PDF ratio fill method object for filling PDF ratio bins, where there is signal MC coverage but no background (MC) coverage with the most signal-like ratio value.

Parameters:: signallike_percentile (float in range [0., 100.], default 99.) – The percentile of signal-like ratios, which should be taken as the ratio value for ratios with no background probability.

property signallike_percentile: The percentile of signal-like ratios, which should be taken as the ratio value for ratios with no background probability. This percentile must be given as a float value in the range [0, 100] inclusively.

__call__(ratio, sig_pd_h, bkg_pd_h, sig_mask_mc_covered, sig_mask_mc_covered_zero_physics, bkg_mask_mc_covered, bkg_mask_mc_covered_zero_physics): Fills the ratio array ratio. For more information see the documentation of skyllh.core.pdfratio_fill.PDFRatioFillMethod.__call__().

class skyllh.core.pdfratio_fill.MinBackgroundLikePDFRatioFillMethod(**kwargs)

Bases: PDFRatioFillMethod

PDF ratio fill method to set the PDF ratio to the minimal background like value for bins, where there is signal but no background coverage.

Creates the PDF ratio fill method object for filling PDF ratio bins, where there is signal MC coverage but no background (MC) coverage with the minimal background-like ratio value.

__call__(ratio, sig_pd_h, bkg_pd_h, sig_mask_mc_covered, sig_mask_mc_covered_zero_physics, bkg_mask_mc_covered, bkg_mask_mc_covered_zero_physics): Fills the ratio array ratio. For more information see the documentation of skyllh.core.pdfratio_fill.PDFRatioFillMethod.__call__().

skyllh.core.progressbar module

class skyllh.core.progressbar.ProgressBar(maxval, startval=0, parent=None, **kwargs)

Bases: object

This class provides an hierarchical progress bar for SkyLLH. For rendering it uses the tqdm Python package. In case of multiple layers of progress bars, it creates only a single progress bar, which gets updated whenever the deeper level progress bars are updated.

Creates a new ProgressBar instance.

Parameters:

maxval (int) – The maximal value the progress can reach.
startval (int) – The progress value to start with. Must be smaller than maxval.
parent (instance of ProgressBar | False | None) – The parent instance of ProgressBar if this progress bar is a sub progress bar. If set to False, this progress bar is deactivated and the property is_shown will return False. If set to None, this progress bar will be a primary progress bar.
arguments (Additional keyword) –
---------------------------- –
tqdm (Additional keyword arguments are passed to the constructor of the) –
class. –

property maxval: The maximal integer value the progress can reach.

property startval: The progress integer value to start with. It must be smaller than maxval.

property val: (read-only) The current value of the progess.

property is_shown: (read-only) Flag if the progress bar is shown. This is True if the program is run in an interactive session, False otherwise.

property parent: The parent ProgressBar instance of this progress bar, or None if no parent exist.

add_sub_progress_bar(pbar): Adds the given progress bar to the list of running sub progress bars of this progress bar.

remove_sub_progress_bars(): Removes all progress bar instances from the list of sub progress bars of this progress bar. It calles the remove_sub_progress_bars method of each sub progress bar.

get_progressbar_list()

Retrieves the list of ProgressBar instances.

Returns:: pbar_list (list of instance of ProgressBar) – The list of ProgressBar instances, which are part of this ProgressBar instance.

rerender(): Rerenders this progress bar on the display. It calls the update method of the tqdm progess bar.

trigger_rerendering(): Triggers a rerendering / update of the most top progress bar.

start(): Sets the current progess value to startval and updates the progess bar to fulfill the start conditions.

finish(): Finishes this progress bar by setting the current progress value to its max value. If this progress bar is the top most progessbar, it will also close the tqdm instance, what will trigger a flush of the output buffer.

increment(dval=1)

Updates the progress bar by incrementing the progress by the given integral amount.

Parameters:: dval (int) – The amount of progress to increment the progress bar with.

update(val)

Updates the progress value to the given value.

Parameters:: val (int) – The new current progress value.

skyllh.core.py module

class skyllh.core.py.PyQualifier(*args, **kwargs)

Bases: object

This is the abstract base class for any Python qualifier class. An object can get qualified by calling a PyQualifier instance with that object. The PyQualifier class will be added to the __pyqualifiers__ attribute of the object.

__call__(obj)

Declares the given Python object to be qualified with the PyQualifier class of self. It adds the class of self to the __pyqualifiers__ tuple of the given object.

Parameters:: obj (object) – The Python object that should get qualified.
Returns:: obj (object) – The given object, but modified to be declared for this Python qualifier.

check(obj)

Checks if the given Python object is declared with the PyQualifier class of the self object.

Parameters:: obj (object) – The Python object to check.
Returns:: check (bool) – The check result. True if the object is declared for this Python qualifier, and False otherwise.

class skyllh.core.py.ConstPyQualifier(*args, **kwargs)

Bases: PyQualifier

This class defines a PyQualifier for constant Python objects.

skyllh.core.py.get_class_of_func(f)

Determines the class object that defined the given method or function f.

Parameters:: f (function | method) – The function or method whose parent class should be determined.
Returns:: cls (class | None) – The class object which defines the given function or method. None is returned when no class could be determined.

skyllh.core.py.typename(t): Returns the name of the given type t.

skyllh.core.py.classname(obj): Returns the name of the class of the class instance obj.

skyllh.core.py.module_classname(obj): Returns the module and class name of the given instance obj.

skyllh.core.py.module_class_method_name(obj, meth_name)

Returns the module, class, and method name of the given instance obj.

Parameters:

obj (instance of object) – The object instance.
meth_name (str) – The name of the method.

skyllh.core.py.get_byte_size_prefix(size)

Determines the biggest size prefix for the given size in bytes such that the new size is still greater one.

Parameters:

size (int) – The size in bytes.

Returns:

newsize (float) – The new byte size accounting for the byte prefix.
prefix (str) – The biggest byte size prefix.

skyllh.core.py.getsizeof(objects)

Determines the size in bytes the given objects have in memory. If an object is a sequence, the size of the elements of the sequence will be estimated as well and added to the result. This does not account for the multiple occurence of the same object.

Parameters:: objects (sequence of instances of object | instance of object.) –
Returns:: memsize (int) – The memory size in bytes of the given objects.

skyllh.core.py.issequence(obj)

Checks if the given object obj is a sequence or not. The definition of a sequence in this case is, that the function len is defined for the object.

Note

A str object is NOT considered a sequence!

Returns:: check (bool) – True if the given object is a sequence. False if the given object is an instance of str or not a sequence.

skyllh.core.py.issequenceof(obj, T, pyqualifiers=None)

Checks if the given object obj is a sequence with items being instances of type T, possibly qualified with the given Python qualifiers.

Parameters:

obj (instance of object) – The Python object to check.
T (type | tuple of types) – The type each item of the sequence should be. If a tuple of types is given, each item can be one of the given types.
pyqualifiers (instance of PyQualifier |) – sequence of instances of PyQualifier | None One or more instances of PyQualifier. Each instance acts as a filter for each item. If any of the filters return False for any of the items, this check returns False. If set to Ǹone, no filters are applied.

Returns:

check (bool) – The result of the check.

skyllh.core.py.issequenceofsubclass(obj, T)

Checks if the given object obj is a sequence with items being sub-classes of class T.

Parameters:

obj (instance of object) – The object to check.
T (class) – The base class of the items of the given object.

Returns:

check (bool) – True if the given object is a sequence of instances which are sub-classes of class T. False if obj is not a sequence or any item is not a sub-class of class T.

skyllh.core.py.isproperty(obj, name)

Checks if the given attribute is of type property. The attribute must exist in obj.

Parameters:

obj (object) – The Python object whose attribute to check for being a property.
name (str) – The name of the attribute.

Returns:

check (bool) – True if the given attribute is of type property, False otherwise.

Raises:

AttributeError – If the given attribute is not an attribute of the class of obj.

skyllh.core.py.func_has_n_args(func, n)

Checks if the given function func has n arguments.

Parameters:

func (callable) – The function to check.
n (int) – The number of arguments the function must have.

Returns:

check (bool) – True if the given function has n arguments. False otherwise.

skyllh.core.py.bool_cast(v, errmsg): Casts the given value to a boolean value. If the cast is impossible, a TypeError is raised with the given error message.

skyllh.core.py.int_cast(v, errmsg, allow_None=False): Casts the given value to an integer value. If the cast is impossible, a TypeError is raised with the given error message. If allow_None is set to True the value v can also be None.

skyllh.core.py.float_cast(v, errmsg, allow_None=False)

Casts the given value to a float. If the cast is impossible, a TypeError is raised with the given error message. If allow_None is set to True the value v can also be None.

Parameters:

v (to_float_castable object | sequence of to_float_castable objects) – The object that should get casted to a float. This can also be a sequence of objects that should get casted to floats.
errmsg (str) – The error message in case the cast failed.
allow_None (bool) – Flag if None is allowed as value for v. If yes, the casted result is None.

Returns:

float | None | list of float and or None – The float / None value casted from v. If a sequence of objects was provided, a list of casted values is returned.

skyllh.core.py.str_cast(v, errmsg, allow_None=False): Casts the given value to a str object. If the cast is impossible, a TypeError is raised with the given error message.

skyllh.core.py.list_of_cast(t, v, errmsg): Casts the given value v to a list of items of type t. If the cast is impossible, a TypeError is raised with the given error message.

skyllh.core.py.get_smallest_numpy_int_type(values)

Returns the smallest numpy integer type that can represent the given integer values.

Parameters:: values (int | sequence of int) – The integer value(s) that need to be representable by the returned integer type.
Returns:: inttype (numpy integer type) – The smallest numpy integer type that can represent the given values.

skyllh.core.py.get_number_of_float_decimals(value)

Determines the number of significant decimals the given float number has. The maximum number of supported decimals is 16.

Parameters:: value (float) – The float value whose number of significant decimals should get determined.
Returns:: decimals (int) – The number of decimals of value which are non-zero.
Raises:: ValueError – If a nan value was provided.

skyllh.core.py.make_dict_hash(d)

Creates a hash value for the given dictionary.

Parameters:: d (dict | None) – The dictionary holding (name: value) pairs. If set to None, an empty dictionary is used.
Returns:: hash (int) – The hash of the dictionary.

class skyllh.core.py.ObjectCollection(objs=None, obj_type=None)

Bases: object

This class provides a collection of objects of a specific type. Objects can be added to the collection via the add method or can be removed from the collection via the pop method. The objects of another object collection can be added to this object collection via the add method as well.

Constructor of the ObjectCollection class. Must be called by the derived class.

Parameters:

objs (instance of obj_type | sequence of obj_type instances | None) – The sequence of objects of type obj_type with which this collection should get initialized with.
obj_type (type | None) – The type of the objects, which can be added to the collection. If set to None, the type will be determined from the given objects. If no objects are given, the object type will be object.

property obj_type: (read-only) The object type.

property objects: (read-only) The list of objects of this object collection. All objects are of the same type as specified through the obj_type property.

__len__(): Returns the number of objects being in this object collection.

__getitem__(key)

__iter__()

__add__(other)

Implementation to support the operation oc = self + other, where self is this ObjectCollection object and other something useful else. This creates a copy oc of self and adds other to oc.

Parameters:: other (obj_type | ObjectCollection of obj_type) –
Returns:: oc (ObjectCollection) – The new ObjectCollection object with object from self and other.

copy(): Creates a copy of this ObjectCollection. The objects of the collection are not copied!

add(obj)

Adds the given object, sequence of objects, or object collection to this object collection.

Parameters:: obj (obj_type instance | sequence of obj_type |) – ObjectCollection of obj_type An instance of obj_type that should be added to the collection. If given an ObjectCollection for objects of type obj_type, it will add all objects of the given collection to this collection.
Returns:: self (ObjectCollection) – The instance of this ObjectCollection, in order to be able to chain several add calls.

__iadd__(obj)

Adds the given object, sequence of objects, or object collection to this object collection.

Parameters:: obj (obj_type instance | sequence of obj_type |) – ObjectCollection of obj_type An instance of obj_type that should be added to the collection. If given an ObjectCollection for objects of type obj_type, it will add all objects of the given collection to this collection.
Returns:: self (ObjectCollection) – The instance of this ObjectCollection, in order to be able to chain several add calls.

index(obj)

Gets the index of the given object instance within this object collection.

Parameters:: obj (obj_type instance) – The instance of obj_type whose index should get retrieved.
Returns:: idx (int) – The index of the object within this object collection.

pop(index=None)

Removes and returns the object at the given index (default last). Raises IndexError if the collection is empty or index is out of range.

Parameters:: index (int | None) – The index of the object to remove. If set to None, the index of the last object is used.
Returns:: obj (obj_type) – The removed object.

class skyllh.core.py.NamedObjectCollection(objs=None, obj_type=None, **kwargs)

Bases: ObjectCollection

This class provides a collection of objects, which have a name. Access via the object name is efficient because the index of each object is tracked w.r.t. its name.

Creates a new NamedObjectCollection instance. Must be called by the derived class.

Parameters:

objs (instance of obj_type | sequence of instances of obj_type | None) – The sequence of objects of type obj_type with which this collection should get initialized with.
obj_type (type) – The type of the objects, which can be added to the collection. This type must have an attribute named name.

property name_list: (read-only) The list of the names of all the objects of this NamedObjectCollection instance. The order of this list of names is preserved to the order objects were added to this collection.

__contains__(name)

Returns True if an object of the given name exists in this NamedObjectCollection instance, False otherwise.

Parameters:: name (str) – The name of the object.
Returns:: check (bool) – True if an object of name name exists in this NamedObjectCollection instance, False otherwise.

__getitem__(key)

Returns an object based on its name or index.

Parameters:: key (str | int) – The object identification. Either its name or its index position within the object collection.
Returns:: obj (instance of obj_type) – The requested object.
Raises:: KeyError – If the given object is not found within this object collection.

add(obj)

Adds the given object to this named object collection.

Parameters:: obj (obj_type instance | NamedObjectCollection of obj_type) – An instance of obj_type that should be added to this named object collection. If a NamedObjectCollection instance for objects of type obj_type is given, all objects of that given collection will be added to this named object collection.
Returns:: self (NamedObjectCollection) – The instance of this NamedObjectCollection, in order to be able to chain several add calls.

__iadd__(obj)

Adds the given object to this named object collection.

Parameters:: obj (obj_type instance | NamedObjectCollection of obj_type) – An instance of obj_type that should be added to this named object collection. If a NamedObjectCollection instance for objects of type obj_type is given, all objects of that given collection will be added to this named object collection.
Returns:: self (NamedObjectCollection) – The instance of this NamedObjectCollection, in order to be able to chain several add calls.

get_index_by_name(name)

Gets the index of the object with the given name within this named object collection.

Parameters:: name (str) – The name of the object whose index should get retrieved.
Returns:: idx (int) – The index of the object within this named object collection.

pop(index=None)

Removes and returns the object at the given index (default last). Raises IndexError if the collection is empty or index is out of range.

Parameters:: index (int | str | None) – The index of the object to remove. If set to None, the index of the last object is used. If a str instance is given, it specifies the name of the object.
Returns:: obj (obj_type instance) – The removed object.

skyllh.core.random module

class skyllh.core.random.RandomStateService(seed=None, **kwargs)

Bases: object

The RandomStateService class provides a container for a numpy.random.RandomState object, initialized with a given seed. This service can then be passed to any function or method within skyllh that requires a random number generator.

Creates a new random state service. The random property can then be used to draw random numbers.

Parameters:: seed (int | None) – The seed to use. If None, the random number generator will be seeded randomly. See the numpy documentation for numpy.random.RandomState what that means.

property seed: (read-only) The seed (int) of the random number generator. None, if not set. To change the seed, use the reseed method.

property random: The numpy.random.RandomState object.

reseed(seed)

Reseeds the random number generator with the given seed.

Parameters:: seed (int | None) – The seed to use. If None, the random number generator will be seeded randomly. See the numpy documentation for numpy.random.RandomState what that means.

class skyllh.core.random.RandomChoice(items, probabilities, **kwargs)

Bases: object

This class provides an efficient numpy.random.choice functionality specialized for SkyLLH. The advantage is that it stores the cumulative distribution function (CDF), which is assumed to be constant.

Creates a new instance of RandomChoice holding the probabilities and their cumulative distribution function (CDF).

Parameters:

items (instance of numpy.ndarray) – The (N,)-shaped numpy.ndarray holding the items from which to choose.
probabilities (instance of numpy.ndarray) – The (N,)-shaped numpy.ndarray holding the probability for each item.

property items: (read-only) The (N,)-shaped numpy.ndarray holding the items from which to choose.

property probabilities: (read-only) The (N,)-shaped numpy.ndarray holding the probability for each item.

__call__(rss, size)

Chooses size random items from self.items according to self.probabilities.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService from which random numbers are drawn from.
size (int) – The number of items to draw.

Returns:

random_items (instance of numpy.ndarray) – The (size,)-shaped numpy.ndarray holding the randomly selected items from self.items.

skyllh.core.scrambling module

class skyllh.core.scrambling.DataScramblingMethod(**kwargs)

Bases: object

Base class for implementing a data scrambling method.

abstract scramble(rss, dataset, data)

The scramble method implements the actual scrambling of the given data, which is method dependent. The scrambling must be performed in-place, i.e. it alters the data inside the given data array.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.
data (instance of DataFieldRecordArray) – The DataFieldRecordArray containing the to be scrambled data.

Returns:

data (instance of DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.UniformRAScramblingMethod(ra_range=None, **kwargs)

Bases: DataScramblingMethod

The UniformRAScramblingMethod method performs right-ascention scrambling uniformly within a given RA range. By default it’s (0, 2pi).

Note::: This alters only the ra values of the data!

Initializes a new RAScramblingMethod instance.

Parameters:: ra_range (tuple | None) – The two-element tuple holding the range in radians within the RA values should get drawn from. If set to None, the default (0, 2pi) will be used.

property ra_range: The two-element tuple holding the range within the RA values should get drawn from.

scramble(rss, dataset, data)

Scrambles the given data uniformly in right-ascention.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.
data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

data (instance of DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.TimeScramblingMethod(timegen, hor_to_equ_transform, **kwargs)

Bases: DataScramblingMethod

The TimeScramblingMethod class provides a data scrambling method to perform data coordinate scrambling based on a generated time. It draws a random time from a time generator and transforms the horizontal (local) coordinates into equatorial coordinates using a specified transformation function.

Initializes a new time scramling method instance.

Parameters:

timegen (instance of TimeGenerator) – The time generator that should be used to generate random MJD times.
hor_to_equ_transform (callable) –
The transformation function to transform coordinates from the horizontal system into the equatorial system.

The call signature must be:

__call__(azi, zen, mjd)

The return signature must be: (ra, dec)

property timegen: The TimeGenerator instance that should be used to generate random MJD times.

property hor_to_equ_transform: The transformation function to transform coordinates from the horizontal system into the equatorial system.

scramble(rss, dataset, data)

Scrambles the given data based on random MJD times, which are generated from a TimeGenerator instance. The event’s right-ascention and declination coordinates are calculated via a horizontal-to-equatorial coordinate transformation and the generated MJD time of the event.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.
data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

data (instance of DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.DataScrambler(method, **kwargs)

Bases: object

Creates a data scrambler instance with a given defined scrambling method.

Parameters:: method (instance of DataScramblingMethod) – The instance of DataScramblingMethod that defines the method of the data scrambling.

property method: The underlaying scrambling method that should be used to scramble the data. This must be an instance of the DataScramblingMethod class.

scramble_data(rss, dataset, data, copy=False)

Scrambles the given data by calling the scramble method of the scrambling method class, that was configured for the data scrambler. If the inplace_scrambling property is set to False, a copy of the data is created before the scrambling is performed.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.
data (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the data, which should get scrambled.
copy (bool) – Flag if a copy of the given data should be made before scrambling the data. The default is False.

Returns:

data (instance of DataFieldRecordArray) – The given DataFieldRecordArray instance with the scrambled data. If the inplace_scrambling property is set to True, this output array is the same array as the input array, otherwise it’s a new array.

skyllh.core.services module

class skyllh.core.services.DetSigYieldService(shg_mgr, dataset_list, data_list, ppbar=None, **kwargs)

Bases: object

This class provides a service to build and hold detector signal yield instances for multiple datasets and source hypothesis groups.

Creates a new DetSigYieldService instance.

property shg_mgr: (read-only) The instance of SourceHypoGroupManager providing the list of source hypothesis groups.

property dataset_list: The list of instance of Dataset for which the detector signal yields should be built.

property data_list: The list of instance of DatasetData for which the detector signal yields should be built.

property arr: (read-only) The (N_datasets, N_source_hypo_groups)-shaped numpy ndarray of object holding the constructed DetSigYield instances.

property n_datasets: (read-only) The number of datasets this service was created for.

property n_shgs: (read-only) The number of source hypothesis groups this service was created for.

change_shg_mgr(shg_mgr, ppbar=None): Changes the instance of SourceHypoGroupManager of this service. This will also rebuild the detector signal yields.

get_builder_to_shgidxs_dict(ds_idx)

Creates a dictionary with the builder instance as key and the list of source hypo group indices to which the builder applies as value. Hence, SHGs using the same builder instance can be grouped for DetSigYield construction.

Parameters:: ds_idx (int) – The index of the dataset for which the same builders apply.
Returns:: builder_shgidxs_dict (dict) – The dictionary with the builder instance as key and the list of source hypo group indices to which the builder applies as value.

construct_detsigyield_array(ppbar=None)

Creates a (N_datasets, N_source_hypo_groups)-shaped numpy ndarray of object holding the constructed DetSigYield instances.

If the same DetSigYieldBuilder class is used for all source hypotheses of a particular dataset, the construct_detsigyields() method is called with different flux models to optimize the construction of the detector signal yield functions.

Parameters:: ppbar (instance of ProgressBar | None) – The instance of ProgressBar of the optional parent progress bar.
Returns:: detsigyield_arr (instance of numpy.ndarray) – The (N_datasets, N_source_hypo_groups)-shaped numpy ndarray of object holding the constructed DetSigYield instances.

class skyllh.core.services.SrcDetSigYieldWeightsService(detsigyield_service, **kwargs)

Bases: object

This class provides a service for the source detector signal yield weights, which are the product of the source weights with the detector signal yield, denoted with \(a_{j,k}(\vec{p}_{\mathrm{s}_k})\) in the math formalism documentation.

\[a_{j,k}(\vec{p}_{\mathrm{s}_k}) = W_k \mathcal{Y}_{\mathrm{s}_{j,k}}(\vec{p}_{\mathrm{s}_k})\]

The service has a method to calculate the weights and a method to retrieve the weights. The weights are stored internally.

Creates a new SrcDetSigYieldWeightsService instance.

Parameters:: detsigyield_service (instance of DetSigYieldService) – The instance of DetSigYieldService providing the (N_datasets, N_source_hypo_groups)-shaped array of DetSigYield instances, one instance for each combination of dataset and source hypothesis group.

static create_src_recarray_list_list(detsigyield_service)

Creates a list of numpy record ndarrays, one for each source hypothesis group suited for evaluating the detector signal yield instance of that source hypothesis group.

Parameters:: detsigyield_service (instance of DetSigYieldService) – The instance of DetSigYieldService providing the (N_datasets, N_source_hypo_groups)-shaped 2D ndarray of DetSigYield instances, one for each dataset and source hypothesis group combination.
Returns:: src_recarray_list_list (list of list of numpy record ndarrays) – The (N_datasets,N_source_hypo_groups)-shaped list of list of the source numpy record ndarrays, one for each dataset and source hypothesis group combination, which is needed for evaluating a particular detector signal yield instance.

static create_src_weight_array_list(shg_mgr)

Creates a list of numpy 1D ndarrays holding the source weights, one for each source hypothesis group.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager defining the source hypothesis groups with their sources.
Returns:: src_weight_array_list (list of numpy 1D ndarrays) – The list of 1D numpy ndarrays holding the source weights, one for each source hypothesis group.

property shg_mgr: (read-only) The instance of SourceHypoGroupManager defining the source hypothesis groups.

property detsigyield_service: The instance of DetSigYieldService providing the (N_datasets, N_source_hypo_groups)-shaped array of DetSigYield instances.

property detsigyield_arr: (read-only) The (N_datasets, N_source_hypo_groups)-shaped 2D numpy ndarray holding the DetSigYield instances for each source hypothesis group.

property n_datasets: (read-only) The number of datasets this service was created for.

property n_shgs: (read-only) The number of source hypothesis groups this service was created for.

property src_recarray_list_list: (read-only) The (N_datasets,N_source_hypo_groups)-shaped list of list of the source numpy record ndarrays, one for each dataset and source hypothesis group combination, which is needed for evaluating a particular detector signal yield instance.

change_shg_mgr(shg_mgr)

Re-creates the internal source numpy record arrays needed for the detector signal yield calculation.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The new SourceHypoGroupManager instance.

calculate(src_params_recarray)

Calculates the source detector signal yield weights for each source and their derivative w.r.t. each global floating parameter. The result is stored internally as:

a_jkinstance of ndarray
The (N_datasets,N_sources)-shaped numpy ndarray holding the source detector signal yield weight for each combination of dataset and source.

a_jk_gradsdict
The dictionary holding the (N_datasets,N_sources)-shaped numpy ndarray with the derivatives w.r.t. the global fit parameter the SrcDetSigYieldWeightsService depend on. The dictionary’s key is the index of the global fit parameter.

Parameters:: src_params_recarray (instance of numpy record ndarray) – The numpy record ndarray of length N_sources holding the local source parameters. See the documentation of skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() for more information about this record array.

get_weights()

Returns the source detector signal yield weights and their derivatives w.r.t. the global fit parameters.

Returns:

a_jk (instance of ndarray) – The (N_datasets, N_sources)-shaped numpy ndarray holding the source detector signal yield weight for each combination of dataset and source.
a_jk_grads (dict) – The dictionary holding the (N_datasets, N_sources)-shaped numpy ndarray with the derivatives w.r.t. the global fit parameter the SrcDetSigYieldWeightsService depend on. The dictionary’s key is the index of the global fit parameter.

class skyllh.core.services.DatasetSignalWeightFactorsService(src_detsigyield_weights_service)

Bases: object

This class provides a service to calculates the dataset signal weight factors, \(f_j(\vec{p}_\mathrm{s})\), for each dataset. It utilizes the source detector signal yield weights \(a_{j,k}(\vec{p}_{\mathrm{s}_k})\), provided by the SrcDetSigYieldWeightsService class.

Creates a new DatasetSignalWeightFactors instance.

Parameters:: src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService) – The instance of SrcDetSigYieldWeightsService providing the source detector signal yield weights \(a_{j,k}(\vec{p}_{\mathrm{s}_k})\).

property src_detsigyield_weights_service: The instance of SrcDetSigYieldWeightsService providing the source detector signal yield weights \(a_{j,k}(\vec{p}_{\mathrm{s}_k})\).

property n_datasets: (read-only) The number of datasets.

calculate()

Calculates the dataset signal weight factors, \(f_j(\vec{p}_\mathrm{s})\). The result is stored internally as:

f_jinstance of ndarray
The (N_datasets,)-shaped 1D numpy ndarray holding the dataset signal weight factor for each dataset.

f_j_gradsdict
The dictionary holding the (N_datasets,)-shaped numpy ndarray with the derivatives w.r.t. the global fit parameter the DatasetSignalWeightFactorsService depend on. The dictionary’s key is the index of the global fit parameter.

get_weights()

Returns the

Returns:

f_j (instance of ndarray) – The (N_datasets,)-shaped 1D numpy ndarray holding the dataset signal weight factor for each dataset.
f_j_grads (dict) – The dictionary holding the (N_datasets,)-shaped numpy ndarray with the derivatives w.r.t. the global fit parameter the DatasetSignalWeightFactorsService depend on. The dictionary’s key is the index of the global fit parameter.

skyllh.core.session module

skyllh.core.session.enable_interactive_session(): Enables interactive session mode.

skyllh.core.session.disable_interactive_session(): Disables interactive session mode.

skyllh.core.session.is_interactive_session()

Checks whether the current session is interactive (True) or not (False).

Returns:: check (bool) – True if the current SkyLLH session is interactive, False otherwise.

skyllh.core.session.is_python_interpreter_in_interactive_mode()

Checks if the Python interpreter is in interactive mode.

Returns:: check (bool) – True if the Python interpreter is in interactive mode, False otherwise.

skyllh.core.signal_generation module

class skyllh.core.signal_generation.SignalGenerationMethod(energy_range, **kwargs)

Bases: object

This is a base class for a source and detector specific signal generation method, that calculates the source flux for a given monte-carlo event, which is needed to calculate the MC event weights for the signal generator.

Constructs a new signal generation method instance.

Parameters:: energy_range (2-element tuple of float | None) – The energy range from which to take MC events into account for signal event generation. If set to None, the entire energy range [0, +inf] is used.

property energy_range: The 2-element tuple of floats holding the energy range from which to take MC events into account for signal event generation.

abstract calc_source_signal_mc_event_flux(data_mc, shg)

This method is supposed to calculate the signal flux of each given MC event for each source hypothesis of the given source hypothesis group.

Parameters:

data_mc (numpy record ndarray) – The numpy record array holding all the MC events.
shg (instance of SourceHypoGroup) – The source hypothesis group instance, which defines the list of sources, and their flux model.

Returns:

ev_idx_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the index of the MC event.
shg_src_idx_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the index of the source within the given source hypothesis group for each signal candidate event.
flux_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the flux value of each signal candidate event.

signal_event_post_sampling_processing(shg, shg_sig_events_meta, shg_sig_events)

This method should be reimplemented by the derived class if there is some processing needed after the MC signal events have been sampled from the global MC data.

Parameters:

shg (SourceHypoGroup instance) – The source hypothesis group instance holding the sources and their locations.
shg_sig_events_meta (numpy record ndarray) –
The numpy record ndarray holding meta information about the generated signal events for the given source hypothesis group. The length of this array must be the same as shg_sig_events. It needs to contain the following data fields:

shg_src_idxint
The source index within the source hypothesis group.
shg_sig_events (numpy record ndarray) – The numpy record ndarray holding the generated signal events for the given source hypothesis group and in the format of the original MC events.

Returns:

shg_sig_events (numpy record array) – The processed signal events. In the default implementation of this method this is just the shg_sig_events input array.

skyllh.core.signal_generator module

class skyllh.core.signal_generator.SignalGenerator(shg_mgr, **kwargs)

Bases: HasConfig

This is the abstract base class for all signal generator classes in SkyLLH. It defines the interface for a signal generator.

Constructs a new signal generator instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The SourceHypoGroupManager instance defining the source hypothesis groups.

property shg_mgr: The SourceHypoGroupManager instance defining the source hypothesis groups.

create_src_params_recarray(src_detsigyield_weights_service)

Creates the src_params_recarray structured ndarray of length N_sources holding the local source parameter names and values needed for the calculation of the detector signal yields.

Parameters:: src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService) – The instance of SrcDetSigYieldWeightsService providing the product of the source weights with the detector signal yield.
Returns:: src_params_recarray (instance of numpy structured ndarray) – The structured numpy ndarray of length N_sources, holding the local parameter names and values of each source needed to calculate the detector signal yield.

change_shg_mgr(shg_mgr): Changes the source hypothesis group manager. Derived classes can reimplement this method but this method of the base class must still be called by the derived class.

abstract generate_signal_events(rss, mean, poisson=True, src_detsigyield_weights_service=None)

This abstract method must be implemented by the derived class to generate a given number of signal events.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (int | float) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean specifies the actual number of generated signal events.
src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService | None) – The instance of SrcDetSigYieldWeightsService providing the weighting of the sources within the detector. This can be None if this signal generator does not need this information.

Returns:

n_signal (int) – The number of generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.

class skyllh.core.signal_generator.MultiDatasetSignalGenerator(shg_mgr, dataset_list, data_list, sig_generator_list=None, ds_sig_weight_factors_service=None, **kwargs)

Bases: SignalGenerator

This is a signal generator class handling multiple datasets by using the individual signal generator instances for each dataset. This is the most general way to support multiple datasets of different formats and signal generation.

Constructs a new signal generator handling multiple datasets.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of source hypothesis groups, i.e. the list of sources.
dataset_list (list of instance of Dataset) – The list of instance of Dataset for which signal events should get generated.
data_list (list of instance of DatasetData) – The list of instance of DatasetData holding the actual data of each dataset. The order must match the order of dataset_list.
sig_generator_list (list of instance of SignalGenerator | None) – The optional list of instance of SignalGenerator holding signal generator instances for each individual dataset. This can be None if this signal generator does not require individual signal generators for each dataset.
ds_sig_weight_factors_service (instance of DatasetSignalWeightFactorsService) – The instance of DatasetSignalWeightFactorsService providing the dataset signal weight factor service for calculating the dataset signal weights.

property dataset_list: The list of Dataset instances for which signal events should get generated for.

property data_list: The list of DatasetData instances holding the actual data of each dataset. The order must match the order of the dataset_list property.

property sig_generator_list: The list of instance of SignalGenerator holding signal generator instances for each individual dataset.

property ds_sig_weight_factors_service: The instance of DatasetSignalWeightFactorsService providing the dataset signal weight factor service for calculating the dataset signal weights.

property n_datasets: (read-only) The number of datasets.

change_shg_mgr(shg_mgr): Changes the source hypothesis group manager. This will recreate the src_params_recarray needed for calculating the detector signal yields. Also it calls the change_shg_mgr methods of the signal generators of the individual datasets.

generate_signal_events(rss, mean, poisson=True, **kwargs)

Generates a given number of signal events distributed across the individual datasets.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (float | int) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean must be an integer and specifies the actual number of generated signal events.

Returns:

n_signal (int) – The number of actual generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.

class skyllh.core.signal_generator.MCMultiDatasetSignalGenerator(shg_mgr, dataset_list, data_list, valid_event_field_ranges_dict_list=None, **kwargs)

Bases: MultiDatasetSignalGenerator

This is a signal generator class, which handles multiple datasets with monte-carlo (MC). It uses the MC events of all datasets to determine the possible signal events for a source. It does not depend on the detector or source hypothesis, because these dependencies are factored out into the signal generation method. In fact the construction within this class depends on the construction of the signal generation method.

Constructs a new signal generator instance.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The SourceHypoGroupManager instance defining the source hypothesis groups.
dataset_list (list of Dataset instances) – The list of Dataset instances for which signal events should get generated for.
data_list (list of DatasetData instances) – The list of DatasetData instances holding the actual data of each dataset. The order must match the order of dataset_list.
valid_event_field_ranges_dict_list (list of dict | None) – If not None, it specifies for each dataset event fields (key) and their valid value range as a 2-element tuple (value). If a generated signal event does not fall into a given field range, the signal event will be discarded and a new signal event will be drawn.

property valid_event_field_ranges_dict_list: The list of dictionary holding the event data fields (key) and their valid value range as 2-element tuple (value).

change_shg_mgr(shg_mgr): Recreates the signal candidates with the changed source hypothesis group manager.

mu2flux(mu, per_source=False)

Translate the mean number of signal events mu into the corresponding flux. The unit of the returned flux is the internally used flux unit.

Parameters:

mu (float) – The mean number of expected signal events for which to get the flux.
per_source (bool) – Flag if the flux should be returned for each source individually (True), or as the sum of all these fluxes (False). The default is False.

Returns:

mu_flux (float | (n_sources,)-shaped numpy ndarray) – The total flux for all sources (if per_source = False) that would correspond to the given mean number of detected signal events mu. If per_source is set to True, a numpy ndarray is returned that contains the flux for each individual source.

generate_signal_events(rss, mean, poisson=True, **kwargs)

Generates a given number of signal events from the signal candidate monte-carlo events.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (float | int) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean must be an integer and specifies the actual number of generated signal events.

Returns:

n_signal (int) – The number of actual generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.

skyllh.core.signalpdf module

The signalpdf module contains possible signal PDF models for the likelihood function.

class skyllh.core.signalpdf.GaussianPSFPointLikeSourceSignalSpatialPDF(ra_range=None, dec_range=None, pd_event_data_field_name=None, **kwargs)

Bases: SpatialPDF, IsSignalPDF

This spatial signal PDF model describes the spatial PDF for a point source smeared with a 2D gaussian point-spread-function (PSF). Mathematically, it’s the convolution of a point in the sky, i.e. the source location, with the PSF. The result of this convolution has the gaussian form

\[\frac{1}{2\pi\sigma^2} \exp(-\frac{r^2}{2\sigma^2}),\]

where \(\sigma\) is the spatial uncertainty of the event and \(r\) the distance on the sphere between the source and the data event.

This PDF requires the src_array data field, that is numpy record ndarray with the data fields ra and dec holding the right-ascension and declination of the point-like sources, respectively.

Creates a new spatial signal PDF for point-like sources with a gaussian point-spread-function (PSF).

Parameters:

ra_range (2-element tuple | None) – The range in right-ascension this spatial PDF is valid for. If set to None, the range (0, 2pi) is used.
dec_range (2-element tuple | None) – The range in declination this spatial PDF is valid for. If set to None, the range (-pi/2, +pi/2) is used.
pd_event_data_field_name (str | None) – The probability density values can be pre-calculated by the user. This specifies the name of the event data field, where these values are stored.

property pd_event_data_field_name: The event data field name where pre-calculated probability density values are stored.

calculate_pd(tdm)

Calculates the gaussian PSF probability density values for all events and sources.

Parameters:

tdm (instance of TrialDataManager) –

The instance of TrialDataManager holding the trial event data for which to calculate the PDF values. The following data fields need to be present:

src_arraynumpy record ndarray

The numpy record ndarray with the following data fields:

rafloat: The right-ascension of the point-like source.
decfloat: The declination of the point-like source.

rafloat

The right-ascension in radian of the data event.

decfloat

The declination in radian of the data event.

ang_err: float

The reconstruction uncertainty in radian of the data event.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density for each event. The length of this 1D array depends on the number of sources and the events belonging to those sources. In the worst case the length is N_sources * N_trial_events.

get_pd(tdm, params_recarray=None, tl=None)

Calculates the spatial signal probability density of each event for all sources.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial event data for which to calculate the PDF values. The following data fields need to be present:

src_arraynumpy record ndarray
The numpy record ndarray with the following data fields:

rafloat
The right-ascension of the point-like source.

decfloat
The declination of the point-like source.

rafloat
The right-ascension in radian of the data event.

decfloat
The declination in radian of the data event.

ang_err: float
The reconstruction uncertainty in radian of the data event.

In case the probability density values were pre-calculated,
params_recarray (None) – Unused interface argument.
tl (TimeLord instance | None) – The optional TimeLord instance to use for measuring timing information.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density for each event. The length of this 1D array depends on the number of sources and the events belonging to those sources. In the worst case the length is N_sources * N_trial_events.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each fit parameter. By definition this PDF does not depend on any fit parameters and hence, this dictionary is empty.

class skyllh.core.signalpdf.RayleighPSFPointSourceSignalSpatialPDF(ra_range=None, dec_range=None, **kwargs)

Bases: SpatialPDF, IsSignalPDF

This spatial signal PDF model describes the spatial PDF for a point-like source following a Rayleigh distribution in the opening angle between the source and reconstructed muon direction. Mathematically, it’s the convolution of a point in the sky, i.e. the source location, with the PSF. The result of this convolution has the following form

\[1/(2\pi \sin\Psi) * \Psi/\sigma^2 \exp(-\Psi^2/(2\sigma^2)),\]

where \(\sigma\) is the spatial uncertainty of the event and \(\Psi\) the distance on the sphere between the source and the data event.

This PDF requires the src_array source data field, that is numpy structured ndarray with the data fields ra and dec holding the right-ascension and declination of the point-like sources, respectively.

Creates a new spatial signal PDF for point-like sources with a Rayleigh point-spread-function (PSF).

Parameters:

ra_range (2-element tuple | None) – The range in right-ascension this spatial PDF is valid for. If set to None, the range (0, 2pi) is used.
dec_range (2-element tuple | None) – The range in declination this spatial PDF is valid for. If set to None, the range (-pi/2, +pi/2) is used.

initialize_for_new_trial(tdm, tl=None, **kwargs): Pre-computes the probability density values once a new trial data is available.

get_pd(tdm, params_recarray=None, tl=None)

Calculates the spatial signal probability density of each event for all sources.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial event data for which to calculate the PDF values. The following data fields need to be present:

psifloat
The opening angle in radian between the source direction and the reconstructed muon direction.

ang_err: float
The reconstruction uncertainty in radian of the data event.
params_recarray (None) – Unused interface argument.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pd ((N_values,)-shaped numpy ndarray) – The (N_values,)-shaped 1D numpy ndarray holding the probability density value for each event and source in unit 1/rad.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter. By definition this PDF does not depend on any global fit parameters and hence, this dictionary is empty.

class skyllh.core.signalpdf.SignalTimePDF(livetime, time_flux_profile, **kwargs)

Bases: TimePDF, IsSignalPDF

This class provides a signal time PDF class. It consists of a Livetime instance and a TimeFluxProfile instance. Together they construct the actual signal time PDF, which has detector down-time taking into account.

Creates a new signal time PDF instance for a given time flux profile and detector live time.

Parameters:

livetime (instance of Livetime) – An instance of Livetime, which provides the detector live-time information.
time_flux_profile (instance of TimeFluxProfile) –
The signal’s time flux profile.

Note

This instance of TimeFluxProfile will be altered by this PDF class when calculating the probability density values!

initialize_for_new_trial(tdm, tl=None, **kwargs)

This method is called when a new trial is initialized. Derived classes can use this call hook to pre-compute time-expensive data, which do not depend on any fit parameters.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data.
tl (instance of TimeLord | None) – The optional instance of TimeLord to measure timing information.

get_pd(tdm, params_recarray, tl=None)

Calculates the signal time probability density of each event for the given set of time parameter values for each source.

Parameters:

tdm (instance of TrialDataManager) –
The instance of TrialDataManager holding the trial event data for which to calculate the PDF value. The following data fields must exist:

'time'float
The time of the event.
params_recarray (instance of numpy structured ndarray) – The numpy structured ndarray holding the local parameter values for each source.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped 1D numpy ndarray holding the probability density value for each trial event and source.
grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter.

class skyllh.core.signalpdf.SignalMultiDimGridPDF(*args, **kwargs)

Bases: MultiDimGridPDF, IsSignalPDF

This class provides a multi-dimensional signal PDF. The PDF is created from pre-calculated PDF data on a grid. The grid data is interpolated using a scipy.interpolate.RegularGridInterpolator instance.

Creates a new PDF instance for a multi-dimensional PDF given as PDF values on a grid or as PDF values stored in a photospline table.

See the documentation of the skyllh.core.pdf.MultiDimGridPDF.__init__() method for the documentation of possible arguments.

class skyllh.core.signalpdf.SignalMultiDimGridPDFSet(pmm, param_set, param_grid_set, gridparams_pdfs, interpol_method_cls=None, use_same_photospline_bfi_for_all_pdfs=False, **kwargs)

Bases: IsSignalPDF, PDFSet, PDF

This class provides a set of MultiDimGridPDF instances that implements also the PDF interface.

Creates a new MultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for each point of a parameter grid set.

Parameters:

pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper that defines the mapping of the global parameters to local model parameters.
param_set (instance of Parameter | sequence of instance of Parameter | instance of ParameterSet) – The set of parameters defining the parameters of this PDF.
param_grid_set (ParameterGrid instance | ParameterGridSet instance) – The set of ParameterGrid instances, which define the grid values of the model parameters, the given MultiDimGridPDF instances belong to.
gridparams_pdfs (sequence of (dict, MultiDimGridPDF) tuples) – The sequence of 2-element tuples which define the mapping of grid values to PDF instances.
interpol_method_cls (subclass of GridManifoldInterpolationMethod) – The class specifying the interpolation method. This must be a subclass of GridManifoldInterpolationMethod. If set to None, the default grid manifold interpolation method Linear1DGridManifoldInterpolationMethod will be used.
use_same_photospline_bfi_for_all_pdfs (bool) – Flag if the same basis function indices (bfi) should be used for all PDFs when photospline tables are used. Default is False. This should be set to True if all photospline tables share the same binning. In that case the PDF evaluation will be accelerated.

property interpol_method_cls: The class derived from GridManifoldInterpolationMethod implementing the interpolation of the PDF grid manifold.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if the PDFs of this PDFSet instance are valid for all the given trial data events. Since all PDFs should have the same axes, only the first PDF will be checked.

This method calls the assert_is_valid_for_trial_data() method of the PDFSet class.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the data is outside the axes range of the PDF.

initialize_for_new_trial(tdm, tl=None, **kwargs)

This method is called whenever a new trial data is initialized. It calls the initialize_for_new_trial() method. Furthermore, it creates the two-dimensional (V,N_events)-shaped ndarray holding the event data and stores it to self._cache_eventdata.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

get_pd(tdm, params_recarray, tl=None)

Calculates the probability density for each event, given the given parameter values.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that will be used to get the data from the trial events.
params_recarray (instance of structured ndarray | None) – The numpy record ndarray holding the parameter name and values for each source model.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density value for each source and event.
grads (dict) – The dictionary holding the PDF gradient value for each event w.r.t. each global fit parameter. The key of the dictionary is the ID of the global fit parameter. The value is the (N_values,)-shaped numpy ndarray holding the gradient value for each event.

class skyllh.core.signalpdf.SignalSHGMappedMultiDimGridPDFSet(shg_mgr, pmm, shgidxs_pdf_list, use_same_photospline_bfi_for_all_pdfs=False, **kwargs)

Bases: IsSignalPDF, PDFSet, PDF

This class provides a set of MultiDimGridPDF instances, one for one or more source hypothesis groups.

Creates a new SignalSHGMappedMultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for one or more source hypothesis groups.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the source hypothesis groups and their sources.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper which defines the mapping of global parameters to local source parameters.
shgidxs_pdf_list (sequence of (shg_idxs, MultiDimGridPDF) tuples) – The sequence of 2-element tuples which define the mapping of the source hypothesis groups to a PDF instance.
use_same_photospline_bfi_for_all_pdfs (bool) – Flag if the same basis function indices (bfi) should be used for all PDFs when photospline tables are used. Default is False. This should be set to True if all photospline tables share the same binning. In that case the PDF evaluation will be accelerated.

property shg_mgr: (read-only) The instance of SourceHypoGroupManager that defines the source hypothesis groups and their sources.

initialize_for_new_trial(tdm, tl=None, **kwargs)

This method is called whenever a new trial data is initialized. It calls the initialize_for_new_trial() method. Furthermore, it creates the two-dimensional (V,N_events)-shaped ndarray holding the event data and stores it to self._cache_eventdata.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager holding the new trial data events.
tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

get_pd(tdm, params_recarray, tl=None)

Calculates the probability density for each event, given the given parameter values.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that will be used to get the data from the trial events.
params_recarray (instance of structured ndarray | None) – The numpy record ndarray holding the parameter name and values for each source model.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pd (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the probability density value for each event.
grads (dict) – The dictionary holding the PDF gradient value for each event w.r.t. each global fit parameter. The key of the dictionary is the ID of the global fit parameter. The value is the (N_values,)-shaped numpy ndarray holding the gradient value for each event. By definition this PDF set does not depend on any fit parameters, hence, this dictionary is empty.

skyllh.core.smoothing module

class skyllh.core.smoothing.HistSmoothingMethod(**kwargs)

Bases: object

Abstract base class for implementing a histogram smoothing method.

abstract smooth(h)

This method is supposed to smooth the given histogram h.

Parameters:: h (N-dimensional ndarray) – The ndarray holding histogram bin values.
Returns:: smoothed_h (N-dimensional ndarray) – The array holding the smoothed histogram bin values.

class skyllh.core.smoothing.NoHistSmoothingMethod(**kwargs)

Bases: HistSmoothingMethod

This class implements a no-shoothing histogram method.

smooth(h)

Does not perform any smoothing and just returns the input histogram.

Parameters:: h (N-dimensional ndarray) – The ndarray holding histogram bin values.
Returns:: h (N-dimensional ndarray) – The input histogram array.

class skyllh.core.smoothing.NeighboringBinHistSmoothingMethod(axis_kernel_arrays, **kwargs)

Bases: HistSmoothingMethod

This class implements a smoothing algorithm that smoothes a histogram based on the neighboring bins.

Constructs a new neighboring bin histogram smoothing method.

Parameters:: axis_kernel_arrays (sequence of 1D ndarrays) – The sequence of smoothing kernel arrays, one for each axis. If an axis should not get smoothed, the UNSMOOTH_AXIS constant should be used for that axis’ smoothing kernel array.

property ndim: (read-only) The dimensionality of the histogram this smoothing instances is made for.

smooth(h)

Smoothes the given histogram array h with the internal kernel array k. Both arrays must have the same dimensionality. The shape values of k must be smaller than or equal to the shape values of h.

Parameters:: h (N-dimensional ndarray) – The ndarray holding histogram bin values.
Returns:: smoothed_h (N-dimensional ndarray.)

class skyllh.core.smoothing.SmoothingFilter(axis_kernel_array, **kwargs)

Bases: object

This class provides a base class for a histogram smoothing filter. It provides an axis kernel array that defines how many neighboring bins of a histogram bin should be used to smooth that histogram bin.

property axis_kernel_array: The kernel array for a histogram axis.

class skyllh.core.smoothing.BlockSmoothingFilter(nbins, **kwargs)

Bases: SmoothingFilter

This class defines the histogram smoothing filter for smoothing a histogram via a block kernel function. The half-width of that block is specified via the nbins argument.

Creates a new BlockSmoothingFilter instance.

Parameters:: nbins (int) – The number of neighboring bins into one direction of a histogram bin, which should be used to smooth that histogram bin.

class skyllh.core.smoothing.GaussianSmoothingFilter(nbins, **kwargs)

Bases: SmoothingFilter

This class defines the histogram smoothing filter for smoothing a histogram via a Gaussian kernel function. The width of that Gaussian is approximately one standard deviation, spread over nbins on each side of the central histogram bin.

Creates a new GaussianSmoothingFilter instance.

Parameters:: nbins (int) – The number of neighboring bins into one direction of a histogram bin, which should be used to smooth that histogram bin.

skyllh.core.source_hypo_grouping module

This module contains classes for source hypothesis grouping functionalities. Same kind sources can be grouped to allow more efficient calculations in the analysis.

class skyllh.core.source_hypo_grouping.SourceHypoGroup(sources, fluxmodel, detsigyield_builders, sig_gen_method=None, **kwargs)

Bases: SourceHypoGroup_t

The source hypothesis group class provides a data container to describe a group of sources that share the same flux model, detector signal yield, and signal generation methods.

Constructs a new source hypothesis group.

Parameters:

sources (SourceModel | sequence of SourceModel) – The source or sequence of sources that define the source group.
fluxmodel (instance of FluxModel) – The FluxModel instance that applies to the list of sources of the group.
detsigyield_builders (sequence of DetSigYieldBuilder instances) – The sequence of detector signal yield builder instances, which should be used to create the detector signal yield for the sources of this group. Each element is the detector signal yield builder for the particular dataset, if several datasets are used. If this list contains only one builder, it should be used for all datasets.
sig_gen_method (SignalGenerationMethod instance | None) – The instance of SignalGenerationMethod that implements the signal generation for the specific detector and source hypothesis. It can be set to None, which means, no signal can be generated. Useful for data unblinding and data trial generation, where no signal is required.

property source_list: The list of SourceModel instances for which the group is defined.

property fluxmodel: The FluxModel instance that applies to the list of sources of this source group.

property detsigyield_builder_list: The list of DetSigYieldBuilder instances, which should be used to create the detector signal yield for this group of sources. Each element is the detector signal yield builder for the particular dataset, if several datasets are used. If this list contains only one builder, it should be used for all datasets.

property sig_gen_method: The instance of SignalGenerationMethod that implements the signal generation for the specific detector and source hypothesis. It can be None, which means, no signal can be generated. Useful for data unblinding and data trial generation, where no signal is required.

property n_sources: (read-only) The number of sources within this source hypothesis group.

get_source_weights()

Gets the weight from each source of this source hypothesis group.

Returns:: weights (numpy ndarray | None) – The (N_sources,)-shaped numpy ndarray holding the theoretical weight of each source. It is None if any of the individual source weights is None.

class skyllh.core.source_hypo_grouping.SourceHypoGroupManager(src_hypo_groups=None, **kwargs)

Bases: object

The source hypothesis group manager provides the functionality to group sources of the same source hypothesis, i.e. spatial model and flux model, with an assigned detector signal yield implementation method.

This helps to evaluate the log-likelihood ratio function in an efficient way.

Creates a new source hypothesis group manager instance.

Parameters:: src_hypo_groups (SourceHypoGroup instance |) – sequence of SourceHypoGroup instances | None The SourceHypoGroup instances to initialize the manager with.

property source_list: The list of defined SourceModel instances.

property n_sources: (read-only) The total number of sources defined in all source groups.

property n_src_hypo_groups

Use n_shgs instead. The number of defined source hypothesis groups.

Type:: DEPRICATED

property n_shgs: The number of defined source hypothesis groups.

property shg_list: (read-only) The list of source hypothesis groups, i.e. SourceHypoGroup instances.

create_source_hypo_group(sources, fluxmodel, detsigyield_builders, sig_gen_method=None)

Creates and adds a source hypothesis group to this source hypothesis group manager. A source hypothesis group shares sources of the same source model with the same flux model and hence the same detector signal yield and signal generation methods.

Parameters:

sources (SourceModel | sequence of SourceModel) – The source or sequence of sources that define the source group.
fluxmodel (instance of FluxModel) – The FluxModel instance that applies to the list of sources of the group.
detsigyield_builders (sequence of DetSigYieldBuilder instances) – The sequence of detector signal yield builder instances, which should be used to create the detector signal yield for the sources of this group. Each element is the detector signal yield builder for the particular dataset, if several datasets are used. If this list contains only one builder, it should be used for all datasets.
sig_gen_method (instance of SignalGenerationMethod | None) – The SignalGenerationMethod instance that implements the detector and source hypothesis specific signal generation. It can be set to None which means no signal can be generated.

get_fluxmodel_by_src_idx(src_idx)

Retrieves the FluxModel instance for the source specified by its source index.

Parameters:: src_idx (int) – The index of the source, which must be in the range [0, N_sources-1].
Returns:: fluxmodel (instance of FluxModel) – The FluxModel instance that applies to the specified source.

get_detsigyield_builder_list_by_src_idx(src_idx)

Retrieves the list of DetSigYieldBuilder instances for the source specified by its source index.

Parameters:: src_idx (int) – The index of the source, which must be in the range [0, N_sources-1].
Returns:: detsigyield_builder_list (list of DetSigYieldBuilder instances) – The list of DetSigYieldBuilder instances that apply to the specified source.

get_src_mask_of_shg(shg_idx)

Creates a source mask for the sources of the shg_idx th source hypothesis group.

Parameters:: shg_idx (int) – The index of the source hypothesis group.
Returns:: src_mask (instance of numpy ndarray) – The (N_sources,)-shaped numpy ndarray of bool holding the mask for selecting the sources of the given source hypothesis group.

get_src_idxs_of_shg(shg_idx)

Creates an array of indices of sources that belong to the given source hypothesis group.

Parameters:: shg_idx (int) – The index of the source hypothesis group.
Returns:: src_idxs (instance of numpy ndarray) – The numpy ndarray of int holding the indices of the sources that belong to the given source hypothesis group.

skyllh.core.source_model module

The model module contains the base class SourceModel for modelling a source in the sky. What kind of properties this source has is modeled by a derived class. The most common one is the PointLikeSource source model for a point-like source at a given location in the sky.

class skyllh.core.source_model.SourceModel(name=None, classification=None, weight=None, **kwargs)

Bases: Model

The base class for all source models in SkyLLH. A source can have a relative weight w.r.t. other sources.

Creates a new source model instance.

Parameters:

name (str | None) – The name of the source model.
classification (str | None) – The astronomical classification of the source.
weight (float | None) – The relative weight of the source w.r.t. other sources. If set to None, unity will be used.

property classification: The astronomical classification of the source.

property weight: The weight of the source.

class skyllh.core.source_model.SourceModelCollection(sources=None, source_type=None, **kwargs)

Bases: ModelCollection

This class describes a collection of source models. It can be used to group sources into a single object, for instance for a stacking analysis.

Creates a new source collection.

Parameters:

sources (sequence of source_type instances | None) – The sequence of sources this collection should be initalized with. If set to None, an empty SourceModelCollection instance is created.
source_type (type | None) – The type of the source. If set to None (default), SourceModel will be used.

static cast(obj, errmsg=None, **kwargs)

Casts the given object to a SourceModelCollection object. If the cast fails, a TypeError with the given error message is raised.

Parameters:

obj (SourceModel | sequence of SourceModel | SourceModelCollection |) – None The object that should be casted to SourceModelCollection. If set to None, an empty SourceModelCollection is created.
errmsg (str | None) – The error message if the cast fails. If set to None, a generic error message will be used.
arguments (Additional keyword) –
---------------------------- –
the (Additional keyword arguments are passed to the constructor of) –
class. (SourceModelCollection) –

Raises:

TypeError – If the cast failed.

property source_type: (read-only) The type of the source model. This property is an alias for the obj_type property.

property sources: (read-only) The list of sources of type source_type.

class skyllh.core.source_model.IsPointlike(ra_func_instance=None, get_ra_func=None, set_ra_func=None, dec_func_instance=None, get_dec_func=None, set_dec_func=None, **kwargs)

Bases: object

This is a classifier class that can be used by other classes to indicate that the specific class describes a point-like object.

Constructor method. Gets called when the an instance of a class is created which derives from this IsPointlike class.

Parameters:

ra_func_instance (object) – The instance object the right-ascention property’s getter and setter functions are defined in.
get_ra_func (callable) – The callable object of the getter function of the right-ascention property. It must have the call signature __call__(ra_func_instance).
set_ra_func (callable) – The callable object of the setter function of the right-ascention property. It must have the call signature __call__(ra_func_instance, value).
dec_func_instance (object) – The instance object the declination property’s getter and setter functions are defined in.
get_dec_func (object) – The callable object of the getter function of the declination property. It must have the call signature __call__(dec_func_instance).
set_dec_func (object) – The callable object of the setter function of the declination property. It must have the call signature __call__(dec_func_instance, value).

property ra: The right-ascention coordinate of the point-like source.

property dec: The declination coordinate of the point-like source.

class skyllh.core.source_model.PointLikeSource(ra, dec, name=None, weight=None, **kwargs)

Bases: SourceModel, IsPointlike

The PointLikeSource class is a source model for a point-like source object in the sky at a given location (right-ascention and declination).

Creates a new PointLikeSource instance for defining a point-like source.

Parameters:

ra (float) – The right-ascention coordinate of the source in radians.
dec (float) – The declination coordinate of the source in radians.
name (str | None) – The name of the source.
weight (float | None) – The relative weight of the source w.r.t. other sources. If set to None, unity will be used.

skyllh.core.storage module

skyllh.core.storage.register_FileLoader(formats, fileloader_cls)

Registers the given file formats (file extensions) to the given FileLoader class.

Parameters:

formats (str | list of str) – The list of file name extensions that should be mapped to the FileLoader class.
fileloader_cls (instance of FileLoader) – The subclass of FileLoader that should be used for the given file formats.

skyllh.core.storage.create_FileLoader(pathfilenames, **kwargs)

Creates the appropriate FileLoader object for the given file names. It looks up the FileLoader class from the FileLoader registry for the file name extension of the first file name in the given list.

Parameters:

pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the files that should be loaded.
Parameters (Additional) –
--------------------- –
the (Additional parameters will be passed to the constructor method of) –
class. (chosen FileLoader) –

Returns:

fileloader (FileLoader) – The appropriate FileLoader instance for the given type of data files.

skyllh.core.storage.assert_file_exists(pathfilename): Checks if the given file exists and raises a RuntimeError if it does not exist.

class skyllh.core.storage.FileLoader(pathfilenames, **kwargs)

Bases: object

Abstract base class for a FileLoader class.

Creates a new FileLoader instance.

Parameters:: pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the data files that need to be loaded.

property pathfilename_list: The list of fully qualified file names of the data files.

abstract load_data(**kwargs): This method is supposed to load the data from the file.

class skyllh.core.storage.NPYFileLoader(pathfilenames, **kwargs)

Bases: FileLoader

The NPYFileLoader class provides the data loading functionality for numpy data files containing numpy arrays. It uses the numpy.load function for loading the data and the numpy.append function to concatenate several data files.

Creates a new NPYFileLoader instance.

Parameters:: pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the data files that need to be loaded.

load_data(keep_fields=None, dtype_conversions=None, dtype_conversion_except_fields=None, efficiency_mode=None)

Loads the data from the files specified through their fully qualified file names.

Parameters:

keep_fields (str | sequence of str | None) – Load the data into memory only for these data fields. If set to None, all in-file-present data fields are loaded into memory.
dtype_conversions (dict | None) – If not None, this dictionary defines how data fields of specific data types get converted into the specified data types. This can be used to use less memory.
dtype_conversion_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.
efficiency_mode (str | None) –
The efficiency mode the data should get loaded with. Possible values are:

'memory':
The data will be load in a memory efficient way. This will require more time, because all data records of a file will be loaded sequentially.

'time'
The data will be loaded in a time efficient way. This will require more memory, because each data file gets loaded in memory at once.

The default value is 'time'. If set to None, the default value will be used.

Returns:

data (instance of DataFieldRecordArray) – The DataFieldRecordArray holding the loaded data.

Raises:

RuntimeError if a file does not exist. –

class skyllh.core.storage.ParquetFileLoader(**kwargs)

Bases: FileLoader

The ParquetFileLoader class provides the data loading functionality for parquet files. It uses the pyarrow package.

Creates a new FileLoader instance.

Parameters:: pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the data files that need to be loaded.

load_data(keep_fields=None, dtype_conversions=None, dtype_conversion_except_fields=None, copy=False, **kwargs)

Loads the data from the files specified through their fully qualified file names.

Parameters:

keep_fields (str | sequence of str | None) – Load the data into memory only for these data fields. If set to None, all in-file-present data fields are loaded into memory.
dtype_conversions (dict | None) – If not None, this dictionary defines how data fields of specific data types get converted into the specified data types. This can be used to use less memory.
dtype_conversion_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.
copy (bool) – If set to True, the column data from the pyarrow.Table instance will be copied into the DataFieldRecordArray. This should not be necessary.

Returns:

data (instance of DataFieldRecordArray) – The DataFieldRecordArray holding the loaded data.

class skyllh.core.storage.PKLFileLoader(pathfilenames, pkl_encoding=None, **kwargs)

Bases: FileLoader

The PKLFileLoader class provides the data loading functionality for pickled Python data files containing Python data structures. It uses the pickle.load function for loading the data from the file.

Creates a new file loader instance for a pickled data file.

Parameters:

pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the data files that need to be loaded.
pkl_encoding (str | None) – The encoding of the pickled data files. If None, the default encodings ‘ASCII’ and ‘latin1’ will be tried to load the data.

property pkl_encoding: The encoding of the pickled data files. Can be None. If None, the default encodings ‘ASCII’ and ‘latin1’ will be tried to load the data.

load_data(**kwargs)

Loads the data from the files specified through their fully qualified file names.

Returns:: data (Python object | list of Python objects) – The de-pickled Python object. If more than one file was specified, this is a list of Python objects, i.e. one object for each file. The file <-> object mapping order is preserved.
Raises:: RuntimeError if a file does not exist. –

class skyllh.core.storage.TextFileLoader(pathfilenames, header_comment='#', header_separator=None, **kwargs)

Bases: FileLoader

The TextFileLoader class provides the data loading functionality for data text files where values are stored in a comma, or whitespace, separated format. It uses the numpy.loadtxt function to load the data. It reads the first line of the text file for a table header.

Creates a new file loader instance for a text data file.

Parameters:

pathfilenames (str | sequence of str) – The sequence of fully qualified file names of the data files that need to be loaded.
header_comment (str) – The character that defines a comment line in the text file.
header_separator (str | None) – The separator of the header field names. If None, it assumes whitespaces.

property header_comment: The character that defines a comment line in the text file.

property header_separator: The separator of the header field names. If None, it assumes whitespaces.

load_data(keep_fields=None, dtype_conversions=None, dtype_conversion_except_fields=None, **kwargs)

Loads the data from the data files specified through their fully qualified file names.

Parameters:

keep_fields (str | sequence of str | None) – Load the data into memory only for these data fields. If set to None, all in-file-present data fields are loaded into memory.
dtype_conversions (dict | None) – If not None, this dictionary defines how data fields of specific data types get converted into the specified data types. This can be used to use less memory.
dtype_conversion_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.

Returns:

data (instance of DataFieldRecordArray) – The DataFieldRecordArray holding the loaded data.

Raises:

RuntimeError – If a file does not exist.
ValueError – If the table header cannot be read.

class skyllh.core.storage.DataTableAccessor(**kwargs)

Bases: object

This class provides an interface wrapper to access the data table of a particular format in a unified way.

abstract get_column(data, name)

This method is supposed to return a numpy.ndarray holding the data of the column with name name.

Parameters:

data (any) – The data table.
name (str) – The name of the column.

Returns:

arr (instance of numpy.ndarray) – The column data as numpy ndarray.

abstract get_field_names(data): This method is supposed to return a list of field names.

abstract get_field_name_to_dtype_dict(data): This method is supposed to return a dictionary with field name and numpy dtype instance for each field.

abstract get_length(data): This method is supposed to return the length of the data table.

class skyllh.core.storage.NDArrayDataTableAccessor(**kwargs)

Bases: DataTableAccessor

This class provides an interface wrapper to access the data table stored as a structured numpy ndarray.

get_column(data, name)

Gets the column data from the structured ndarray.

Parameters:

data (instance of numpy.ndarray) – The structured numpy ndarray holding the table data.
name (str) – The name of the column.

get_field_names(data): This method is supposed to return a list of field names.

get_field_name_to_dtype_dict(data): Returns the dictionary with field name and numpy dtype instance for each field.

get_length(data): Returns the length of the data table.

class skyllh.core.storage.DictDataTableAccessor(**kwargs)

Bases: DataTableAccessor

This class provides an interface wrapper to access the data table stored as a Python dictionary.

get_column(data, name)

Gets the column data from the dictionary.

Parameters:

data (dict) – The dictionary holding the table data.
name (str) – The name of the column.

get_field_names(data): This method is supposed to return a list of field names.

get_field_name_to_dtype_dict(data): Returns the dictionary with field name and numpy dtype instance for each field.

get_length(data): Returns the length of the data table.

class skyllh.core.storage.ParquetDataTableAccessor(**kwargs)

Bases: DataTableAccessor

This class provides an interface wrapper to access the data table stored as a Parquet table.

get_column(data, name)

Gets the column data from the Parquet table.

Parameters:

data (instance of pyarrow.Table) – The instance of pyarrow.Table holding the table data.
name (str) – The name of the column.

get_field_names(data): This method is supposed to return a list of field names.

get_field_name_to_dtype_dict(data): Returns the dictionary with field name and numpy dtype instance for each field.

get_length(data): Returns the length of the data table.

class skyllh.core.storage.DataFieldRecordArrayDataTableAccessor(**kwargs)

Bases: DataTableAccessor

get_column(data, name)

Gets the column data from the Parquet table.

Parameters:

data (instance of pyarrow.Table) – The instance of pyarrow.Table holding the table data.
name (str) – The name of the column.

get_field_names(data): This method is supposed to return a list of field names.

get_field_name_to_dtype_dict(data): Returns the dictionary with field name and numpy dtype instance for each field.

get_length(data): Returns the length of the data table.

class skyllh.core.storage.DataFieldRecordArray(data, data_table_accessor=None, keep_fields=None, dtype_conversions=None, dtype_conversion_except_fields=None, copy=True)

Bases: object

The DataFieldRecordArray class provides a data container similar to a numpy record ndarray. But the data fields are stored as individual numpy ndarray objects. Hence, access of single data fields is much faster compared to access on the record ndarray.

Creates a DataFieldRecordArray from the given data.

Parameters:

data (any | None) –
The tabulated data in any format. The only requirement is that there is a DataTableAccessor instance available for the given data format. Supported data types are:

numpy.ndarray
A structured numpy ndarray.

dict
A Python dictionary with field names as keys and one-dimensional numpy.ndarrays as values.

pyarrow.Table
An instance of pyarrow.Table.

DataFieldRecordArray
An instance of DataFieldRecordArray.

If set to None, the DataFieldRecordArray instance is initialized with no data and the length of the array is set to 0.
data_table_accessor (instance of DataTableAccessor | None) – The instance of DataTableAccessor which provides column access to data. If set to None, an appropriate DataTableAccessor instance will be selected based on the type of data.
keep_fields (str | sequence of str | None) – If not None (default), this specifies the data fields that should get kept from the given data. Otherwise all data fields get kept.
dtype_conversions (dict | None) – If not None, this dictionary defines how data fields of specific data types get converted into the specified data types. This can be used to use less memory.
dtype_conversion_except_fields (str | sequence of str | None) – The sequence of field names whose data type should not get converted.
copy (bool) – Flag if the input data should get copied. Default is True. If a DataFieldRecordArray instance is provided, this option is set to True automatically.

__contains__(name)

Checks if the given field exists in this DataFieldRecordArray instance.

Parameters:: name (str) – The name of the field.
Returns:: check (bool) – True, if the given field exists in this DataFieldRecordArray instance, False otherwise.

__getitem__(name)

Implements data field value access.

Parameters:: name (str | numpy ndarray of int or bool) – The name of the data field. If a numpy ndarray is given, it must contain the indices for which to retrieve a data selection of the entire DataFieldRecordArray. A numpy ndarray of bools can be given as well to define a mask.
Raises:: KeyError – If the given data field does not exist.
Returns:: data (numpy ndarray | instance of DataFieldRecordArray) – The requested field data or a DataFieldRecordArray holding the requested selection of the entire data.

__setitem__(name, arr)

Implements data field value assignment. If values are assigned to a data field that does not exist yet, it will be added via the append_field method.

Parameters:

name (str | numpy ndarray of int or bool) – The name of the data field, or a numpy ndarray holding the indices or mask of a selection of this DataFieldRecordArray.
arr (numpy ndarray | instance of DataFieldRecordArray) – The numpy ndarray holding the field values. It must be of the same length as this DataFieldRecordArray. If name is a numpy ndarray, arr must be a DataFieldRecordArray.

Raises:

ValueError – If the given data array is not of the same length as this DataFieldRecordArray instance.

__len__()

__sizeof__()

Calculates the size in bytes of this DataFieldRecordArray instance in memory.

Returns:: memsize (int) – The memory size in bytes that this DataFieldRecordArray instance has.

property field_name_list: (read-only) The list of the field names of this DataFieldRecordArray.

property indices: (read-only) The numpy ndarray holding the indices of this DataFieldRecordArray.

append(arr)

Appends the given DataFieldRecordArray to this DataFieldRecordArray instance.

Parameters:: arr (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray that should get appended to this DataFieldRecordArray. It must contain the same data fields. Additional data fields are ignored.

append_field(name, data)

Appends a field and its data to this DataFieldRecordArray instance.

Parameters:

name (str) – The name of the new data field.
data (numpy ndarray) – The numpy ndarray holding the data. The length of the ndarray must match the current length of this DataFieldRecordArray instance.

Raises:

KeyError – If the given data field name already exists in this DataFieldRecordArray instance.
ValueError – If the length of the data array does not equal to the length of the data of this DataFieldRecordArray instance.
TypeError – If the arguments are of the wrong type.

as_numpy_record_array()

Creates a numpy record ndarray instance holding the data of this DataFieldRecordArray instance.

Returns:: arr (instance of numpy record ndarray) – The numpy recarray ndarray holding the data of this DataFieldRecordArray instance.

copy(keep_fields=None)

Creates a new DataFieldRecordArray that is a copy of this DataFieldRecordArray instance.

Parameters:: keep_fields (str | sequence of str | None) – If not None (default), this specifies the data fields that should get kept from this DataFieldRecordArray. Otherwise all data fields get kept.

remove_field(name)

Removes the given field from this array.

Parameters:: name (str) – The name of the data field that is to be removed.

get_field_dtype(name): Returns the numpy dtype object of the given data field.

set_field_dtype(name, dt)

Sets the data type of the given field.

Parameters:

name (str) – The name of the data field.
dt (numpy.dtype) – The dtype instance defining the new data type.

convert_dtypes(conversions, except_fields=None)

Converts the data type of the data fields of this DataFieldRecordArray. This method can be used to compress the data.

Parameters:

conversions (dict of old_dtype -> new_dtype) – The dictionary with the old dtype as key and the new dtype as value.
except_fields (sequence of str | None) – The sequence of field names, which should not get converted.

get_selection(indices)

Creates an DataFieldRecordArray that contains a selection of the data of this DataFieldRecordArray instance.

Parameters:: indices ((N,)-shaped numpy ndarray of int or bool) – The numpy ndarray holding the indices for which to select the data.
Returns:: data_field_array (instance of DataFieldRecordArray) – The DataFieldRecordArray that contains the selection of the original DataFieldRecordArray. The selection data is a copy of the original data.

set_selection(indices, arr)

Sets a selection of the data of this DataFieldRecordArray instance to the data given in arr.

Parameters:

indices ((N,)-shaped numpy ndarray of int or bool) – The numpy ndarray holding the indices or mask for which to set the data.
arr (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the selection data. It must have the same fields defined as this DataFieldRecordArray instance.

rename_fields(conversions, must_exist=False)

Renames the given fields of this array.

Parameters:

conversions (dict of old_name -> new_name) – The dictionary holding the old and new names of the data fields.
must_exist (bool) – Flag if the given fields must exist. If set to True and a field does not exist, a KeyError is raised.

Raises:

KeyError – If must_exist is set to True and a given field does not exist.

tidy_up(keep_fields)

Removes all fields that are not specified through the keep_fields argument.

Parameters:: keep_fields (str | sequence of str) – The field name(s), that should not be removed.
Raises:: TypeError – If keep_fields is not an instance of str or a sequence of str instances.

sort_by_field(name)

Sorts the data along the given field name in ascending order.

Parameters:: name (str) – The name of the field along the events should get sorted.
Returns:: sorted_idxs ((n_events,)-shaped numpy ndarray) – The numpy ndarray holding the indices of the sorted array.
Raises:: KeyError – If the given data field does not exist.

skyllh.core.test_statistic module

The test_statistic module provides the classes for different test statistic functions.

class skyllh.core.test_statistic.TestStatistic(**kwargs)

Bases: object

This is the abstract base class for a test statistic class.

Constructs the test-statistic function instance.

abstract __call__(pmm, log_lambda, fitparam_values, **kwargs)

This method is supposed to evaluate the test-statistic function.

Parameters:

pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance that defines the global parameter set.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the global fit parameter values of the log-likelihood ratio function for the given log_lambda value.

Returns:

TS (float) – The calculated test-statistic value.

class skyllh.core.test_statistic.WilksTestStatistic(ns_param_name='ns', **kwargs)

Bases: TestStatistic

This class implements the standard Wilks theorem test-statistic function:

\[TS = 2 \text{sign}(\hat{n}_{\text{s}}) \log \left( \frac{\mathcal{L}(\hat{\vec{p}})}{\mathcal{L}(n_{\text{s}} = 0)} \right)\]

where the \(\text{sign}(\hat{n}_{\text{s}})\) is negative for \(\hat{n}_{\text{s}} < 0\), and positive otherwise.

Constructs the test-statistic function instance.

Parameters:: ns_param_name (str) – The name of the global fit parameter for the number of signal events in the detector, ns.

property ns_param_name: (read-only) The name of the global fit parameter for the number of signal events in the detector, ns.

__call__(pmm, log_lambda, fitparam_values, **kwargs)

Evaluates the test-statistic function.

Parameters:

pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance that defines the global parameter set.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the global fit parameter values of the log-likelihood ratio function for the given log_lambda value.

Returns:

TS (float) – The calculated test-statistic value.

class skyllh.core.test_statistic.LLHRatioZeroNsTaylorWilksTestStatistic(ns_param_name='ns', **kwargs)

Bases: TestStatistic

Similar to the TestStatisticWilks class, this class implements the standard Wilks theorem test-statistic function. But for zero ns values, the log-likelihood ratio function is taylored up to second order and the resulting apex is used as log_lambda value. Hence, the TS function is defined as:

\[TS = 2 \text{sign}(\hat{n}_{\text{s}}) \log \left( \frac{\mathcal{L}(\hat{\vec{p}})}{\mathcal{L}(n_{\text{s}} = 0)} \right)\]

for \(\hat{n}_{\text{s}} \neq 0\), and

\[TS = -2 \frac{a^2}{4b}\]

for \(\hat{n}_{\text{s}} = 0\), with

\[a = \frac{\text{d}}{\text{d}n_{\text{s}}} \left( \frac{\mathcal{L}(\hat{\vec{p}})}{\mathcal{L}(n_{\text{s}} = 0)} \right)\]

being the derivative w.r.t. \(n_{\text{s}}\) of the log-likelihood ratio function, and

\[b = \frac{\text{d}a}{\text{d}n_{\text{s}}}\]

being its second derivative w.r.t. ns.

Constructs the test-statistic function instance.

Parameters:: ns_param_name (str) – The name of the global fit parameter for the number of signal events in the detector, ns.

property ns_param_name: (read-only) The name of the global fit parameter for the number of signal events in the detector, ns.

__call__(pmm, log_lambda, fitparam_values, llhratio, grads, tl=None, **kwargs)

Evaluates the test-statistic function.

Parameters:

pmm (instance of ParameterModelMapper) – The ParameterModelMapper instance that defines the global parameter set.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the global fit parameter values of the log-likelihood ratio function for the given log_lambda value.
llhratio (instance of LLHRatio) – The log-likelihood ratio function, which should be used for the test-statistic function.
grads (instance of numpy ndarray) – The (N_fitparam,)-shaped 1D numpy ndarray holding the values of the first derivative of the log-likelihood ratio function w.r.t. each global fit parameter.
tl (instance of TimeLord | None) – The optional instance of TimeLord to measure timing information.

Returns:

TS (float) – The calculated test-statistic value.

skyllh.core.times module

class skyllh.core.times.TimeGenerationMethod(**kwargs)

Bases: object

Base class (type) for implementing a method to generate times.

abstract generate_times(rss, size)

The generate_times method implements the actual generation of times, which is method dependent.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
size (int) – The number of times that should get generated.

Returns:

times (ndarray) – The 1d numpy ndarray holding the generated times.

class skyllh.core.times.LivetimeTimeGenerationMethod(livetime, **kwargs)

Bases: TimeGenerationMethod

The LivetimeTimeGenerationMethod provides the method to generate times from a Livetime object. It will uniformely generate times that will coincide with the on-time intervals of the detector, by calling the draw_ontimes method of the Livetime class.

Creates a new LivetimeTimeGeneration instance.

Parameters:: livetime (Livetime) – The Livetime instance that should be used to generate times from.

property livetime: The Livetime instance used to draw times from.

generate_times(rss, size, **kwargs)

Generates size MJD times according to the detector on-times provided by the Livetime instance.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
size (int) – The number of times that should get generated.

Returns:

times (ndarray) – The 1d (size,)-shaped numpy ndarray holding the generated times.

class skyllh.core.times.TimeGenerator(method)

Bases: object

Creates a time generator instance with a given defined time generation method.

Parameters:: method (instance of TimeGenerationMethod) – The instance of TimeGenerationMethod that defines the method of generating times.

property method: The TimeGenerationMethod object that should be used to generate the times.

generate_times(rss, size, **kwargs)

Generates size amount of times by calling the generate_times method of the TimeGenerationMethod class.

Parameters:

rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).
size (int) – The number of time that should get generated.
**kwargs – Additional keyword arguments are passed to the generate_times method of the TimeGenerationMethod class.

Returns:

times (ndarray) – The 1d (size,)-shaped ndarray holding the generated times.

skyllh.core.timing module

The timing module provides code execution timing functionalities. The TimeLord class keeps track of execution times of specific code segments, called “tasks”. The TaskTimer class can be used within a with statement to time the execution of the code within the with block.

class skyllh.core.timing.TaskRecord(name, start_times, end_times)

Bases: object

Creates a new TaskRecord instance.

Parameters:

name (str) – The name of the task.
start_times (list of float) – The start times of the task in seconds.
end_times (list of float) – The end times of the task in seconds.

property tstart: (read-only) The time stamps the execution of this task started.

property tend: (read-only) The time stamps the execution of this task was stopped.

property duration: (read-only) The total duration (without time overlap) the task was executed.

property niter: (read-only) The number of times this task was executed.

join(tr)

Joins this TaskRecord with the given TaskRecord instance.

Parameters:: tr (instance of TaskRecord) – The instance of TaskRecord that should be joined with this TaskRecord instance.

class skyllh.core.timing.TimeLord

Bases: object

property task_name_list: (read-only) The list of task names.

add_task_record(tr): Adds a given task record to the internal list of task records.

get_task_record(name)

Retrieves a task record of the given name.

Parameters:: name (str) – The name of the task record.
Returns:: task_record (instance of TaskRecord) – The instance of TaskRecord with the requested name.

has_task_record(name)

Checks if this TimeLord instance has a task record of the given name.

Parameters:: name (str) – The name of the task record.
Returns:: check (bool) – True if this TimeLord instance has a task record of the given name, and False otherwise.

join(tl)

Joins a given TimeLord instance with this TimeLord instance. Tasks of the same name will be updated and new tasks will be added.

Parameters:: tl (instance of TimeLord) – The instance of TimeLord whos tasks should be joined with the tasks of this TimeLord instance.

task_timer(name): Creates TaskTimer instance for the given task name.

class skyllh.core.timing.TaskTimer(time_lord, name)

Bases: object

Parameters:

time_lord (instance of TimeLord) – The TimeLord instance that keeps track of the recorded tasks.
name (str) – The name of the task.

property time_lord: The TimeLord instance that keeps track of the recorded tasks. This can be None, which means that the task should not get recorded.

property name: The name if the task.

property duration: The duration in seconds the task was executed.

__enter__(): This gets executed when entering the with block.

__exit__(exc_type, exc_value, traceback): This gets executed when exiting the with block.

skyllh.core.tool module

The tool module provides functionality to interface with an optional external python package (tool). The tool can be imported dynamically at run-time when needed.

skyllh.core.tool.assert_tool_version(tool, version)

Asserts the required version of the tool. The tool module must have the attribute __version__.

Parameters:

tool (str) – The name of the tool.
version (str) – The required version of the tool in the format "<COMP>X.Y.Z", where <COMP> is one of <=, ==, and >=.

Raises:

ImportError – If the version of the tool does not match the requirements.
KeyError – If the tool module has no attribute named __version__.
ValueError – If <COMP> is not supported.

skyllh.core.tool.is_available(name)

Checks if the given Python package is available for import.

Parameters:: name (str) – The name of the Python package.
Returns:: check (bool) – True if the given Python package is available, False otherwise.
Raises:: ModuleNotFoundError – If the package is not a Python package, i.e. lacks a __path__ attribute.

skyllh.core.tool.get(name)

Returns the module object of the given tool. This will import the Python package if it was not yet imported.

Parameters:: name (str) – The name of the Python package.
Returns:: module (Python module) – The (imported) Python module object.

skyllh.core.tool.requires(*tools)

This is decorator function that can be used whenever a function requires optional tools.

Parameters:

*tools (sequence of str | sequence of (str, str)) – The name(s) of the required Python packages. If a 2-element tuple of (str, str) is provided for a tool, the first element specifies the name of the tool and the second element its version of the form "<COMP>X.Y.Z", where <COMP> is one of <=, ==, and >=.

Raises:

ModuleNotFoundError – If any of the specified tools is not available.
ImportError – If the version of a tool does not meet the requirements.

skyllh.core.trialdata module

The trialdata module of SkyLLH provides a trial data manager class that manages the data of an analysis trial. It provides also possible additional data fields and their calculation, which are required by the particular analysis. The rational behind this manager is to compute data fields only once, which can then be used by different analysis objects, like PDF objects.

class skyllh.core.trialdata.DataField(name, func, global_fitparam_names=None, dt=None, is_src_field=False, is_srcevt_data=False, **kwargs)

Bases: object

This class defines a data field and its calculation that is used by an Analysis class instance. The calculation is defined through an external function.

Creates a new instance of DataField that might depend on fit parameters.

Parameters:

name (str) – The name of the data field. It serves as the identifier for the data field.
func (callable) –
The function that calculates the values of this data field. The call signature must be

__call__(tdm, shg_mgr, pmm, global_fitparams_dict=None)

where tdm is the instance of TrialDataManager holding the trial event data, shg_mgr is the instance of SourceHypoGroupManager, pmm is the instance of ParameterModelMapper, and global_fitparams_dict is the dictionary with the current global fit parameter names and values.
global_fitparam_names (str | sequence of str | None) – The sequence of str instances specifying the names of the global fit parameters this data field depends on. If set to None, the data field does not depend on any fit parameters.
dt (numpy dtype | str | None) – If specified it defines the data type this data field should have. If a str instance is given, it defines the name of the data field whose data type should be taken for this data field.
is_src_field (bool) – Flag if this data field is a source data field (True) and values should be stored within this DataField instance, instead of the events DataFieldRecordArray instance of the TrialDataManager (False).
is_srcevt_data (bool) – Flag if the data field will hold source-event data, i.e. data of length N_values. In that case the data cannot be stored within the events attribute of the TrialDataManager, but must be stored in the values attribute of this DataField instance.

property name: The name of the data field.

property func: The function that calculates the data field values.

property dt: The numpy dtype object defining the data type of this data field. A str instance defines the name of the data field whose data type should be taken for this data field. It is None, if there is no explicit data type defined for this data field.

property is_srcevt_data: (read-only) Flag if the data field contains source-event data, i.e. is of length N_values.

property values: (read-only) The calculated data values of the data field.

class skyllh.core.trialdata.TrialDataManager(index_field_name=None, **kwargs)

Bases: object

The TrialDataManager class manages the event data for an analysis trial. It provides possible additional data fields and their calculation. New data fields can be defined via the add_data_field() method. Whenever a new trial is being initialized the data fields get re-calculated. The data trial manager is provided to the PDF evaluation method. Hence, data fields are calculated only once.

Creates a new TrialDataManager instance.

Parameters:: index_field_name (str | None) – The name of the field that should be used as primary index field. If provided, the events will be sorted along this data field. This might be useful for run-time performance.

property index_field_name: The name of the primary index data field. If not None, events will be sorted by this data field.

property events: The DataFieldRecordArray instance holding the data events, which should get evaluated.

property has_global_fitparam_data_fields: (read-only) True if the TrialDataManager has global fit parameter data fields defined, False otherwise.

property n_sources: (read-only) The number of sources. This information is taken from the source hypo group manager when a new trial is initialized.

property n_events: The total number of events of the dataset this trial data manager corresponds to.

property n_selected_events: (read-only) The number of selected events which should get evaluated.

property n_pure_bkg_events: (read-only) The number of pure background events, which are not part of the trial data, but must be considered for the test-statistic value. It is the difference of n_events and n_selected_events.

property src_evt_idxs: (read-only) The 2-tuple holding the source indices and event indices 1d ndarray arrays. This can be None, indicating that all trial data events should be considered for all sources.

property trial_data_state_id: (read-only) The integer ID number of the trial data. This ID number can be used to determine when the trial data has changed its state.

__contains__(name)

Checks if the given data field is defined in this data field manager.

Parameters:: name (str) – The name of the data field.
Returns:: check (bool) – True if the data field is defined in this data field manager, False otherwise.

__getitem__(name): Implements the evaluation of self[name] to access data fields. This method calls the get_data() method of this class.

broadcast_sources_array_to_values_array(arr)

Broadcasts the given 1d numpy ndarray of length 1 or N_sources to a numpy ndarray of length N_values.

Parameters:: arr (instance of ndarray) – The (N_sources,)- or (1,)-shaped numpy ndarray holding values for each source.
Returns:: out_arr (instance of ndarray) – The (N_values,)-shaped numpy ndarray holding the source values broadcasted to each event value.

broadcast_sources_arrays_to_values_arrays(arrays)

Broadcasts the 1d numpy ndarrays to the values array.

Parameters:: arrays (sequence of numpy 1d ndarrays) – The sequence of (N_sources,)-shaped numpy ndarrays holding the parameter values.
Returns:: out_arrays (list of numpy 1d ndarrays) – The list of (N_values,)-shaped numpy ndarrays holding the broadcasted array values.

broadcast_selected_events_arrays_to_values_arrays(arrays)

Broadcasts the given arrays of length N_selected_events to arrays of length N_values.

Parameters:: arrays (sequence of instance of ndarray) – The sequence of instance of ndarray with the arrays to be broadcasted.
Returns:: out_arrays (list of instance of ndarray) – The list of broadcasted numpy ndarray instances.

change_shg_mgr(shg_mgr, pmm)

This method is called when the source hypothesis group manager has changed. Hence, the source data fields need to get recalculated.

After calling this method, a new trial should be initialized via the initialize_trial() method!

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the source hypothesis groups.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper that defines the global parameters and their mapping to local source parameter.

initialize_trial(shg_mgr, pmm, events, n_events=None, evt_sel_method=None, tl=None)

Initializes the trial data manager for a new trial. It sets the raw events, calculates pre-event-selection data fields, performs a possible event selection and calculates the static data fields for the left-over events.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the source hypothesis groups.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, that defines the global parameters and their mapping to local source parameters.
events (DataFieldRecordArray instance) – The DataFieldRecordArray instance holding the entire raw events.
n_events (int | None) – The total number of events of the data set this trial data manager corresponds to. If None, the number of events is taken from the number of events present in the events array.
evt_sel_method (instance of EventSelectionMethod | None) – The optional event selection method that should be used to select potential signal events.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

get_n_values()

Returns the expected size of the values array after a PDF evaluation, which will include PDF values for all trial data events and all sources.

Returns:: n (int) – The length of the expected values array after a PDF evaluation.

get_values_mask_for_source_mask(src_mask)

Creates a boolean mask for the values array where entries belonging to the sources given by the source mask are selected.

Parameters:: src_mask (instance of numpy ndarray) – The (N_sources,)-shaped numpy ndarray holding the boolean selection of the sources.
Returns:: values_mask (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray holding the boolean selection of the values.

add_source_data_field(name, func, dt=None)

Adds a new data field to the manager. The data field must depend solely on source parameters.

Parameters:

name (str) – The name of the data field. It serves as the identifier for the data field.
func (callable) –
The function that calculates the data field values. The call signature must be

__call__(tdm, shg_mgr, pmm)

where tdm is the TrialDataManager instance holding the event data, shg_mgr is the instance of SourceHypoGroupManager, and pmm is the instance of ParameterModelMapper.
dt (numpy dtype | str | None) – If specified it defines the data type this data field should have. If a str instance is given, it defines the name of the data field whose data type should be taken for the data field.

add_data_field(name, func, global_fitparam_names=None, dt=None, pre_evt_sel=False, is_srcevt_data=False)

Adds a new data field to the manager.

Parameters:

name (str) – The name of the data field. It serves as the identifier for the data field.
func (callable) –
The function that calculates the data field values. The call signature must be

__call__(tdm, shg_mgr, pmm, global_fitparams_dict=None)

where tdm is the TrialDataManager instance holding the trial event data, shg_mgr is the instance of SourceHypoGroupManager, pmm is the instance of ParameterModelMapper, and global_fitparams_dict is the dictionary with the current global fit parameter names and values. The shape of the returned array must be (N_selected_events,).
global_fitparam_names (str | sequence of str | None) – The sequence of str instances specifying the names of the global fit parameters this data field depends on. If set to None, it means that the data field does not depend on any fit parameters.
dt (numpy dtype | str | None) – If specified it defines the data type this data field should have. If a str instance is given, it defines the name of the data field whose data type should be taken for the data field.
pre_evt_sel (bool) – Flag if this data field should get calculated before potential signal events get selected (True), or afterwards (False). Default is False.
is_srcevt_data (bool) – Flag if this data field contains source-event data, hence the length of the data array will be N_values. Default is False.

calculate_source_data_fields(shg_mgr, pmm)

Calculates the data values of the data fields that solely depend on source parameters.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, that defines the global parameters and their mapping to local source parameters.

calculate_pre_evt_sel_static_data_fields(shg_mgr, pmm)

Calculates the data values of the data fields that should be available for the event selection method and do not depend on any fit parameters.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, that defines the global parameters and their mapping to local source parameters.

calculate_static_data_fields(shg_mgr, pmm)

Calculates the data values of the data fields that do not depend on any source or fit parameters.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, that defines the global parameters and their mapping to local source parameters.

calculate_global_fitparam_data_fields(shg_mgr, pmm, global_fitparams_dict)

Calculates the data values of the data fields that depend on global fit parameter values.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, that defines the global parameters and their mapping to local source parameters.
global_fitparams_dict (dict) – The dictionary holding the current global fit parameter names and values.

get_data(name)

Gets the data for the given data field name. The data is stored either in the raw events DataFieldRecordArray or in one of the additional defined data fields. Data from the raw events DataFieldRecordArray is prefered.

Parameters:: name (str) – The name of the data field for which to retrieve the data.
Returns:: data (instance of numpy ndarray) – The numpy ndarray holding the data of the requested data field. The length of the array is either N_sources, N_selected_events, or N_values.
Raises:: KeyError – If the given data field is not defined.

get_dtype(name)

Gets the data type of the given data field.

Parameters:: name (str) – The name of the data field whose data type should get retrieved.
Returns:: dt (numpy dtype) – The numpy dtype object of the given data field.
Raises:: KeyError – If the given data field is not defined.

is_event_data_field(name)

Checks if the given data field is an events data field, i.e. its length is N_selected_events.

Parameters:: name (str) – The name of the data field.
Returns:: check (bool) – True if the given data field contains event data, False otherwise.

is_source_data_field(name)

Checks if the given data field is a source data field, i.e. its length is N_sources.

Parameters:: name (str) – The name of the data field.
Returns:: check (bool) – True if the given data field contains source data, False otherwise.

is_srcevt_data_field(name)

Checks if the given data field is a source-event data field, i.e. its length is N_values.

Parameters:: name (str) – The name of the data field.
Returns:: check (bool) – True if the given data field contains source-event data, False otherwise.

skyllh.core.types module

This modules defines base types for some of the SkyLLH classes to avoid circular imports when actively checking for types.

class skyllh.core.types.SourceHypoGroup_t(*args, **kwargs): Bases: object