skyllh.core package

skyllh.core.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.

Submodules

skyllh.core.analysis module

The analysis module provides classes for pre-defined analyses.

class skyllh.core.analysis.Analysis(src_hypo_group_manager, src_fitparam_mapper, test_statistic, bkg_gen_method=None, custom_sig_generator=None)

Bases: object

This is the abstract base class for all analysis classes. It contains common properties required by all analyses and defines the overall analysis interface howto set-up and run an analysis.

Note: This analysis base class assumes the analysis to be a log-likelihood: ratio test, i.e. 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 add_dataset() method.

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

Call the do_trial() or unblind() method to perform a random trial or to unblind the data. 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.

Constructor of the analysis base class.

Parameters:

src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal efficiency implementation method.
src_fitparam_mapper (instance of SourceFitParameterMapper) – The SourceFitParameterMapper instance managing the global fit parameters and their relation to the individual sources.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_gen_method (instance of BackgroundGenerationMethod | None) – The instance of BackgroundGenerationMethod that should be used to generate background events for pseudo data. This can be set to None, if there is no need to generate background events.
custom_sig_generator (SignalGenerator class | None) – The signal generator class used to create _sig_generator instance. Uses default SignalGenerator implementation if set to None.

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

property src_fitparam_mapper: The SourceFitParameterMapper instance that manages the global fit parameters and their relation to the sources.

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

property bkg_gen_method: The BackgroundGenerationMethod instance that implements the background event generation. This can be None if no background generation method has been defined.

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 fitparamset: (read-only) The instance of FitParameterSet holding all the global fit parameters of the log-likelihood ratio function.

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

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 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 total_livetime: (read-only) The total live-time in days of the loaded data.

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

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

Parameters:

dataset (Dataset instance) – The Dataset instance that should get added.
data (DatasetData instance) – The DatasetData instance holding the original (prepared) data of the dataset.
tdm (TrialDataManager instance | 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.

calculate_test_statistic(log_lambda, fitparam_values, *args, **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 ((N_fitparam+1)-shaped 1D ndarray) – The 1D ndarray holding the fit parameter values of the log-likelihood ratio function for the given log_lambda value.
arguments (Additional arguments and keyword) –
------------------------------------------ –
the (Any additional arguments and keyword arguments are passed to) –
instance. (evaluate method of the TestStatistic class) –

Returns:

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

abstract construct_llhratio(): This method is supposed to construct the log-likelihood ratio function and sets it as the _llhratio property.

construct_background_generator(): 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(): 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 maximize_llhratio(rss, tl=None)

This method is supposed to maximize the log-likelihood ratio function, by calling the maximize method of the LLHRatio class.

Parameters:

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

Returns:

fitparamset (FitParameterSet instance) – The instance of FitParameterSet holding the global fit parameter definitions used in the maximization process.
log_lambda_max (float) – The value of the log-likelihood ratio function at its maximum.
fitparam_values ((N_fitparam,)-shaped 1D ndarray) – The ndarray holding the global fit parameter values. By definition, the first element is the value of the fit parameter ns.
status (dict) – The dictionary with status information about the maximization process, i.e. from the minimizer.

unblind(rss)

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

Parameters:

rss (RandomStateService instance) – The RandomStateService instance that should be used draw random numbers from.

Returns:

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

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

Generates background events utilizing the background generator.

Parameters:

rss (RandomStateService) – The 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.
tl (instance of TimeLord | None) – The 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 DataFieldRecordArray instances) – 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.

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 (RandomStateService) – The RandomStateService instance 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 SignalGenerator 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 DataFieldRecordArray instances | 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 events that have been generated for each pseudo data set.
events_list (list of DataFieldRecordArray instances) – The list of DataFieldRecordArray instances containing the pseudo 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 (RandomStateService) – The 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. 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 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 DataFieldRecordArray instances) – 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_with_given_pseudo_data(rss, mean_n_sig, n_sig, n_events_list, events_list, mean_n_sig_0=None, minimizer_status_dict=None, tl=None)

Performs an analysis trial on the given pseudo data.

Parameters:

rss (RandomStateService) – The 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_events_list (list of int) – The total number of events for each data set of the pseudo data.
events_list (list of DataFieldRecordArray instances) – The list of DataFieldRecordArray instances 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.
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.
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.

Returns:

result (structured numpy ndarray) – The structured numpy 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.
[<fitparam_name> …float ]: Any additional fit parameters of the LLH function.

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, mean_n_sig_0=None, minimizer_status_dict=None, tl=None)

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 (RandomStateService) – The 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 DataFieldRecordArray instances) – The list of DataFieldRecordArray instances containing the background pseudo data events for each data set.
sig_events_list (list of DataFieldRecordArray instances or None) – The list of DataFieldRecordArray instances 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.
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.
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.

Returns:

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

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

Performs an analysis trial by generating a pseudo data sample with background events and possible signal events, and performs the LLH analysis on that random pseudo data sample.

Parameters:

rss (RandomStateService) – The 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. The actual number of generated events will be drawn from a Poisson distribution with this given signal mean as mean.
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.
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 instance of TimeLord that should be used to time individual tasks.

Returns:

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

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.
[<fitparam_name> …float ]: Any additional fit parameters of the LLH function.

do_trials(rss, n, mean_n_bkg_list=None, mean_n_sig=0, mean_n_sig_0=None, bkg_kwargs=None, sig_kwargs=None, ncpu=None, tl=None, ppbar=None)

Executes do_trial method N times with possible multi-processing. One trial performs an analysis trial by generating a pseudo data sample with background events and possible signal events, and performs the LLH analysis on that random pseudo data sample.

Parameters:

rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
n (int) – Number of trials to generate using the do_trial method.
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 number of data events of each data sample will be used as mean.
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.
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.
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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean number of signal events. If set to False, the argument mean_n_sig specifies the actual number of generated signal events.
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 instance of TimeLord that should be used to time individual tasks.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.

Returns:

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

n_sigint: The actual number of injected signal events.
tsfloat: The test-statistic value.
[<fitparam_name> …float ]: Any additional fit parameters of the LLH function.

class skyllh.core.analysis.TimeIntegratedMultiDatasetSingleSourceAnalysis(src_hypo_group_manager, src_fitparam_mapper, fitparam_ns, test_statistic, bkg_gen_method=None, custom_sig_generator=None)

Bases: Analysis

This is an analysis class that implements a time-integrated LLH ratio analysis for multiple datasets assuming a single source.

To run this analysis the following procedure applies:

Add the datasets and their spatial and energy PDF ratio instances via the 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_llhratio() method.

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

Parameters:

src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal efficiency implementation method.
src_fitparam_mapper (instance of SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters.
fitparam_ns (FitParameter instance) – The FitParameter instance defining the fit parameter ns.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_gen_method (instance of BackgroundGenerationMethod | None) – The instance of BackgroundGenerationMethod that will be used to generate background events for a new analysis trial. This can be set to None, if no background events have to get generated.
custom_sig_generator (SignalGenerator class | None) – The signal generator class used to create _sig_generator instance. Uses default SignalGenerator implementation if set to None.

property fitparam_ns: The FitParameter instance for the fit parameter ns.

add_dataset(dataset, data, pdfratios, tdm=None, event_selection_method=None)

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

Parameters:

dataset (Dataset instance) – The Dataset instance that should get added.
data (DatasetData instance) – The DatasetData instance holding the original (prepared) data of the dataset.
pdfratios (PDFRatio instance | sequence of PDFRatio instances) – The PDFRatio instance or the sequence of PDFRatio instances for the to-be-added data set.
tdm (TrialDataManager instance | 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.

construct_llhratio(minimizer, ppbar=None)

Constructs the log-likelihood-ratio (LLH-ratio) function of the analysis. This setups all the necessary analysis objects like detector signal efficiencies 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 (ProgressBar instance | 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 (SourceModel instance) – The SourceModel instance describing the new source.

change_sources(sources)

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

Parameters:: sources (list of SourceModel instances) – The SourceModel instances describing new sources.

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

This method initializes the multi-dataset 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 (TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

maximize_llhratio(rss, tl=None)

Maximizes the log-likelihood ratio function, by minimizing its negative.

Parameters:

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

Returns:

fitparamset (FitParameterSet instance) – The instance of FitParameterSet holding the global fit parameter definitions used in the maximization process.
log_lambda_max (float) – The value of the log-likelihood ratio function at its maximum.
fitparam_values ((N_fitparam,)-shaped 1D ndarray) – The ndarray holding the global fit parameter values. By definition, the first element is the value of the fit parameter ns.
status (dict) – The dictionary with status information about the maximization process, i.e. from the minimizer.

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 ((N_fitparams,)-shaped 1D ndarray) – The ndarray holding the fit parameter values that should be used for the flux calculation.

Returns:

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

class skyllh.core.analysis.TimeIntegratedMultiDatasetMultiSourceAnalysis(src_hypo_group_manager, src_fitparam_mapper, fitparam_ns, test_statistic, bkg_gen_method=None, custom_sig_generator=None)

Bases: TimeIntegratedMultiDatasetSingleSourceAnalysis

This is an analysis class that implements a time-integrated LLH ratio analysis for multiple datasets assuming multiple sources.

To run this analysis the following procedure applies:

Add the datasets and their spatial and energy PDF ratio instances via the 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_llhratio() method.

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

Parameters:

src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses, their flux model, and their detector signal efficiency implementation method.
src_fitparam_mapper (instance of SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters.
fitparam_ns (FitParameter instance) – The FitParameter instance defining the fit parameter ns.
test_statistic (TestStatistic instance) – The TestStatistic instance that defines the test statistic function of the analysis.
bkg_gen_method (instance of BackgroundGenerationMethod | None) – The instance of BackgroundGenerationMethod that will be used to generate background events for a new analysis trial. This can be set to None, if no background events have to get generated.
custom_sig_generator (SignalGenerator class | None) – The signal generator class used to create _sig_generator instance. Uses default SignalGenerator implementation if set to None.

construct_llhratio(minimizer, ppbar=None)

Constructs the log-likelihood-ratio (LLH-ratio) function of the analysis. This setups all the necessary analysis objects like detector signal efficiencies 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 (ProgressBar instance | 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.

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

This method initializes the multi-dataset 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 (TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

skyllh.core.analysis_utils module

skyllh.core.analysis_utils.pointlikesource_to_data_field_array(tdm, src_hypo_group_manager)

Function to transform a list of PointLikeSource sources into a numpy record ndarray. The resulting numpy record ndarray contains the following fields:

ra: float
The right-ascention of the point-like source.

dec: float
The declination of the point-like source.

src_w: float
The nomalized detector weight of the point-like source.

src_w_grad: float
The normalized weight gradient of the point-like source.

src_w_W: float
The nomalized hypothesis weight of the point-like source.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance.
src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the sources.

Returns:

arr ((N_sources,)-shaped numpy record ndarray) – The numpy record ndarray holding the source parameters ra and dec.

skyllh.core.analysis_utils.calculate_pval_from_trials(ts_vals, ts_threshold)

Calculates the percentage (p-value) of test-statistic trials that are above the given test-statistic critical value. In addition it calculates the standard deviation of the p-value assuming binomial statistics.

Parameters:

ts_vals ((n_trials,)-shaped 1D ndarray of float) – The ndarray holding the test-statistic values of the trials.
ts_threshold (float) – The critical test-statistic value.

skyllh.core.analysis_utils.truncated_gamma_logpdf(a, scale, eta, ts_above_eta, N_above_eta)

Calculates the -log(likelihood) of a sample of random numbers generated from a gamma pdf truncated from below at x=eta.

Parameters:

a (float) – Shape parameter.
scale (float) – Scale parameter.
eta (float) – Test-statistic value at which the gamma function is truncated from below.
ts_above_eta ((n_trials,)-shaped 1D ndarray) – The ndarray holding the test-statistic values falling in the truncated gamma pdf.
N_above_eta (int) – Number of test-statistic values falling in the truncated gamma pdf.

Returns:

-logl (float)

skyllh.core.analysis_utils.calculate_critical_ts_from_gamma(ts, h0_ts_quantile, eta=3.0)

Calculates the critical test-statistic value corresponding to h0_ts_quantile by fitting the ts distribution with a truncated gamma function.

Parameters:

ts ((n_trials,)-shaped 1D ndarray) – The ndarray holding the test-statistic values of the trials.
h0_ts_quantile (float) – Null-hypothesis test statistic quantile.
eta (float, optional) – Test-statistic value at which the gamma function is truncated from below.

Returns:

critical_ts (float)

skyllh.core.analysis_utils.polynomial_fit(ns, p, p_weight, deg, p_thr)

Performs a polynomial fit on the p-values of test-statistic trials associated to each ns.. Using the fitted parameters it computes the number of signal events correponding to the given p-value critical value.

Parameters:

ns (1D array_like object) – x-coordinates of the sample.
p (1D array_like object) – y-coordinates of the sample.
p_weight (1D array_like object) – Weights to apply to the y-coordinates of the sample points. For gaussian uncertainties, use 1/sigma.
deg (int) – Degree of the fitting polynomial function.
p_thr (float within [0,1]) – The critical p-value.

Returns:

ns (float)

skyllh.core.analysis_utils.estimate_mean_nsignal_for_ts_quantile(ana, rss, p, eps_p, mu_range, critical_ts=None, h0_trials=None, h0_ts_quantile=None, min_dmu=0.5, bkg_kwargs=None, sig_kwargs=None, ppbar=None, tl=None, pathfilename=None)

Calculates the mean number of signal events needed to be injected to reach a test statistic distribution with defined properties for the given analysis.

Parameters:

ana (Analysis instance) – The Analysis instance to use for the calculation.
rss (instance of RandomStateService) – The RandomStateService instance to use for generating random numbers.
p (float) – Desired probability of signal test statistic for exceeding h0_ts_quantile part of null-hypothesis test statistic threshold.
eps_p (float) – Precision in p as stopping condition for the calculation.
mu_range (2-element sequence) – The range of mu (lower,upper) to search for mean number of signal events.
critical_ts (float | None) – The critical test-statistic value that should be overcome by the signal distribution. If set to None, the null-hypothesis test-statistic distribution will be used to compute the critical TS value.
h0_trials ((n_h0_trials,)-shaped ndarray | None) – The structured ndarray holding the trials for the null-hypothesis. If set to None, the number of trials is calculated from binomial statistics via h0_ts_quantile*(1-h0_ts_quantile)/eps**2, where eps is min(5e-3, h0_ts_quantile/10).
h0_ts_quantile (float | None) – Null-hypothesis test statistic quantile. If set to None, the critical test-statistic value that should be overcome by the signal distribution MUST be given.
min_dmu (float) – The minimum delta mu to use for calculating the derivative dmu/dp. The default is 0.5.
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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the mean number of signal events, mu.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to collect timing information about this function.
pathfilename (string | None) – Trial data file path including the filename. If set to None, generatedtrials won’t be saved.

Returns:

mu (float) – Estimated mean number of signal events.
mu_err (None) – Error estimate needs to be implemented.

skyllh.core.analysis_utils.estimate_sensitivity(ana, rss, h0_trials=None, h0_ts_quantile=0.5, p=0.9, eps_p=0.005, mu_range=None, min_dmu=0.5, bkg_kwargs=None, sig_kwargs=None, ppbar=None, tl=None, pathfilename=None)

Estimates the mean number of signal events that whould have to be injected into the data such that the test-statistic value of p*100% of all trials are larger than the critical test-statistic value c, which corresponds to the test-statistic value where h0_ts_quantile*100% of all null hypothesis test-statistic values are larger than c.

For sensitivity h0_ts_quantile, and p are usually set to 0.5, and 0.9, respectively.

Parameters:

ana (Analysis) – The Analysis instance to use for sensitivity estimation.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
h0_trials ((n_h0_ts_vals,)-shaped ndarray | None) – The strutured ndarray holding the trials for the null-hypothesis. If set to None, the number of trials is calculated from binomial statistics via h0_ts_quantile*(1-h0_ts_quantile)/eps**2, where eps is min(5e-3, h0_ts_quantile/10).
h0_ts_quantile (float, optional) – Null-hypothesis test statistic quantile that defines the critical value.
p (float, optional) – Desired probability of the signal test statistic value to exceed the null-hypothesis test statistic value threshold, which is defined through the h0_ts_quantile value.
eps_p (float, optional) – Precision in p for execution to break.
mu_range (2-element sequence | None) – Range to search for the mean number of signal events. If set to None, the range (0, 10) will be used.
min_dmu (float) – The minimum delta mu to use for calculating the derivative dmu/dp. The default is 0.5.
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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the mean number of signal events, mu.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to collect timing information about this function.
pathfilename (string | None) – Trial data file path including the filename. If set to None, generated trials won’t be saved.

Returns:

mu (float) – Estimated median number of signal events to reach desired sensitivity.
mu_err (float) – The uncertainty of the estimated mean number of signal events.

skyllh.core.analysis_utils.estimate_discovery_potential(ana, rss, h0_trials=None, h0_ts_quantile=5.733e-07, p=0.5, eps_p=0.005, mu_range=None, min_dmu=0.5, bkg_kwargs=None, sig_kwargs=None, ppbar=None, tl=None, pathfilename=None)

Estimates the mean number of signal events that whould have to be injected into the data such that the test-statistic value of p*100% of all trials are larger than the critical test-statistic value c, which corresponds to the test-statistic value where h0_ts_quantile*100% of all null hypothesis test-statistic values are larger than c.

For the 5 sigma discovery potential h0_ts_quantile, and p are usually set to 5.733e-7, and 0.5, respectively.

Parameters:

ana (Analysis) – The Analysis instance to use for discovery potential estimation.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
h0_trials ((n_h0_ts_vals,)-shaped ndarray | None) – The structured ndarray holding the trials for the null-hypothesis. If set to None, the number of trials is calculated from binomial statistics via h0_ts_quantile*(1-h0_ts_quantile)/eps**2, where eps is min(5e-3, h0_ts_quantile/10).
h0_ts_quantile (float, optional) – Null-hypothesis test statistic quantile that defines the critical value.
p (float, optional) – Desired probability of the signal test statistic value to exceed the critical value.
eps_p (float, optional) – Precision in p for execution to break.
mu_range (2-element sequence | None) – Range to search for the mean number of signal events. If set to None, the range (0, 10) will be used.
min_dmu (float) – The minimum delta mu to use for calculating the derivative dmu/dp. The default is 0.5.
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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the mean number of signal events, mu.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to collect timing information about this function.
pathfilename (string | None) – Trial data file path including the filename. If set to None, generated trials won’t be saved.

Returns:

mu (float) – Estimated mean number of injected signal events to reach the desired discovery potential.
mu_err (float) – Estimated error of mu.

skyllh.core.analysis_utils.generate_mu_of_p_spline_interpolation(ana, rss, h0_ts_vals, h0_ts_quantile, eps_p, mu_range, mu_step, kind='cubic', bkg_kwargs=None, sig_kwargs=None, ppbar=None, tl=None)

Generates a spline interpolation for mu(p) function for a pre-defined range of mu, where mu is the mean number of injected signal events and p the probability for the ts value larger than the ts value corresponding to the given quantile, h0_ts_quantile, of the null hypothesis test-statistic distribution.

Parameters:

ana (instance of Analysis) – The Analysis instance to use for the calculation.
rss (instance of RandomStateService) – The RandomStateService instance to use for generating random numbers.
h0_ts_vals ((n_h0_ts_vals,)-shaped 1D ndarray | None) – The 1D ndarray holding the test-statistic values for the null-hypothesis. If set to None, 100/(1-h0_ts_quantile) null-hypothesis trials will be generated.
h0_ts_quantile (float) – Null-hypothesis test statistic quantile, which should be exceeded by the alternative hypothesis ts value.
eps_p (float) – The one sigma precision in p as stopping condition for the calculation for a single mu value.
mu_range (2-element sequence) – The range (lower,upper) of mean number of injected signal events to create the interpolation spline for.
mu_step (float) – The step size of the mean number of signal events.
kind (str) – The kind of spline to generate. Possble values are ‘linear’ and ‘cubic’ (default).
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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the mean number of signal events, mu.
ppbar (instance of ProgressBar | None) – The possible parent ProgressBar instance.
tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to collect timing information about this function.

Returns:

spline (callable) – The spline function mu(p).

skyllh.core.analysis_utils.create_trial_data_file(ana, rss, n_trials, mean_n_sig=0, mean_n_sig_null=0, mean_n_bkg_list=None, bkg_kwargs=None, sig_kwargs=None, pathfilename=None, ncpu=None, ppbar=None, tl=None)

Creates and fills a trial data file with n_trials generated trials for each mean number of injected signal events from ns_min up to ns_max for a given analysis.

Parameters:

ana (instance of Analysis) – The Analysis instance to use for the trial generation.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
n_trials (int) – The number of trials to perform for each hypothesis test.
mean_n_sig (ndarray of float | float | 2- or 3-element sequence of float) – The array of mean number of injected signal events (MNOISEs) for which to generate trials. If this argument is not a ndarray, an array of MNOISEs is generated based on this argument. If a single float is given, only this given MNOISEs are injected. If a 2-element sequence of floats is given, it specifies the range of MNOISEs with a step size of one. If a 3-element sequence of floats is given, it specifies the range plus the step size of the MNOISEs.
mean_n_sig_null (ndarray of float | float | 2- or 3-element sequence of) – float The array of the fixed mean number of signal events (FMNOSEs) for the null-hypothesis for which to generate trials. If this argument is not a ndarray, an array of FMNOSEs is generated based on this argument. If a single float is given, only this given FMNOSEs are used. If a 2-element sequence of floats is given, it specifies the range of FMNOSEs with a step size of one. If a 3-element sequence of floats is given, it specifies the range plus the step size of the FMNOSEs.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. This parameter is passed to the do_trials method of the Analysis class. If set to None (the default), the background generation method needs to obtain this number itself.
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.
pathfilename (string | None) – Trial data file path including the filename. If set to None generated trials won’t be saved.
ncpu (int | None) – The number of CPUs to use.
ppbar (instance of ProgressBar | None) – The optional instance of the parent progress bar.
tl (instance of TimeLord | None) – The instance of TimeLord that should be used to measure individual tasks.

Returns:

seed (int) – The seed used to generate the trials.
mean_n_sig (1d ndarray) – The array holding the mean number of signal events used to generate the trials.
mean_n_sig_null (1d ndarray) – The array holding the fixed mean number of signal events for the null-hypothesis used to generate the trials.
trial_data (structured numpy ndarray) – The generated trial data.

skyllh.core.analysis_utils.extend_trial_data_file(ana, rss, n_trials, trial_data, mean_n_sig=0, mean_n_sig_null=0, mean_n_bkg_list=None, bkg_kwargs=None, sig_kwargs=None, pathfilename=None)

Appends to the trial data file n_trials generated trials for each mean number of injected signal events up to ns_max for a given analysis.

Parameters:

ana (Analysis) – The Analysis instance to use for sensitivity estimation.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
n_trials (int) – The number of trials the trial data file needs to be extended by.
trial_data (structured numpy ndarray) – The structured numpy ndarray holding the trials.
mean_n_sig (ndarray of float | float | 2- or 3-element sequence of float) – The array of mean number of injected signal events (MNOISEs) for which to generate trials. If this argument is not a ndarray, an array of MNOISEs is generated based on this argument. If a single float is given, only this given MNOISEs are injected. If a 2-element sequence of floats is given, it specifies the range of MNOISEs with a step size of one. If a 3-element sequence of floats is given, it specifies the range plus the step size of the MNOISEs.
mean_n_sig_null (ndarray of float | float | 2- or 3-element sequence of) – float The array of the fixed mean number of signal events (FMNOSEs) for the null-hypothesis for which to generate trials. If this argument is not a ndarray, an array of FMNOSEs is generated based on this argument. If a single float is given, only this given FMNOSEs are used. If a 2-element sequence of floats is given, it specifies the range of FMNOSEs with a step size of one. If a 3-element sequence of floats is given, it specifies the range plus the step size of the FMNOSEs.
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.
pathfilename (string | None) – Trial data file path including the filename.

Returns:

trial_data – Trial data file extended by the required number of trials for each mean number of injected signal events..

skyllh.core.analysis_utils.calculate_upper_limit_distribution(analysis, rss, pathfilename, N_bkg=5000, n_bins=100)

Function to calculate upper limit distribution. It loads the trial data file containing test statistic distribution and calculates 10 percentile value for each mean number of injected signal event. Then it finds upper limit values which correspond to generated background trials test statistic values by linearly interpolated curve of 10 percentile values distribution.

Parameters:

analysis (Analysis) – The Analysis instance to use for sensitivity estimation.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
pathfilename (string) – Trial data file path including the filename.
N_bkg (int, optional) – Number of times to perform background analysis trial.
n_bins (int, optional) – Number of returned test statistic histograms bins.

Returns:

result (dict) – Result dictionary which contains the following fields:

ullist of float
List of upper limit values.
meanfloat
Mean of upper limit values.
medianfloat
Median of upper limit values.
varfloat
Variance of upper limit values.
ts_histnumpy ndarray
2D array of test statistic histograms calculated by axis 1.
extentlist of float
Test statistic histogram boundaries.
q_valueslist of float
q percentile values of test statistic for different injected events means.

skyllh.core.background_generation module

class skyllh.core.background_generation.BackgroundGenerationMethod

Bases: object

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

Constructs a new background generation method instance.

change_source_hypo_group_manager(src_hypo_group_manager)

Notifies the background generation method about an updated SourceHypoGroupManager instance.

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance.

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 (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, unique_events=False, data_scrambler=None, mc_inplace_scrambling=False, keep_mc_data_fields=None, pre_event_selection_method=None)

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 and data are Dataset and DatasetData instances 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 and data are Dataset and DatasetData instances 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 an event selection method is provided, this argument cannot be None.
unique_events (bool) – Flag if unique events should be drawn from the monte-carlo (True), or if events can be drawn several times (False). Default is False.
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 droped 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 unique_events: Flag if unique events should be drawn from the monto-carlo (True), or if the same event can be drawn multiple times from the monte-carlo.

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 droped 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_source_hypo_group_manager(src_hypo_group_manager)

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

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance.

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 value 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(bkg_gen_method, dataset_list, data_list)

Bases: object

This is the general background generator class, which provides a method to generate background events. It does not depend on the detector or background hypothesis. These dependencies are out-sourced to a class derived from the BackgroundGenerationMethod class.

Constructs a new background generator instance.

Parameters:

bkg_gen_method (instance of BackgroundGenerationMethod) – The background event generation method, which should be used to generate events.
dataset_list (list of Dataset instances) – The list of Dataset instances for which background 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.

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

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.

change_source_hypo_group_manager(src_hypo_group_manager)

Changes the SourceHypoGroupManager instance of the background generation method.

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

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

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

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from.
dataset_idx (int) – The index of the dataset for which background events should get generated for.
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 (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 can be less than n_bkg if an event selection method is used.

skyllh.core.backgroundpdf module

The backgroundpdf module contains possible background PDF models for the likelihood function.

class skyllh.core.backgroundpdf.BackgroundMultiDimGridPDF(axis_binnings, path_to_pdf_splinetable=None, pdf_grid_data=None, norm_factor_func=None)

Bases: MultiDimGridPDF, IsBackgroundPDF

This class provides a multi-dimensional background 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 background PDF instance for a multi-dimensional PDF given as 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.

Parameters:

axis_binnings (sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.
path_to_pdf_splinetable (str) – The path to the file containing the spline table. The spline table contains a pre-computed fit to pdf_grid_data.
pdf_grid_data (n-dimensional numpy ndarray) – 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.
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, events, fitparams), where pdf is this PDF instance, events is a numpy record ndarray holding the events for which to calculate the PDF values, and fitparams is a dictionary with the current fit parameter names and values.

class skyllh.core.backgroundpdf.BackgroundNDPhotosplinePDF(axis_binnings, param_set, path_to_pdf_splinefit, norm_factor_func=None)

Bases: NDPhotosplinePDF, IsBackgroundPDF

This class provides a multi-dimensional background PDF created from a n-dimensional photospline fit. The photospline package is used to evaluate the PDF fit.

Creates a new background PDF instance for a n-dimensional photospline PDF fit.

Parameters:

axis_binnings (BinningDefinition | sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.
param_set (Parameter | ParameterSet) – The Parameter instance or ParameterSet instance defining the parameters of this PDF. The ParameterSet holds the information which parameters are fixed and which are floating (i.e. fitted).
path_to_pdf_splinefit (str) – The path to the file containing the photospline fit.
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), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the event data for which to calculate the PDF values, and params is a dictionary with the current parameter names and values.

skyllh.core.binning module

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

Bases: object

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

Creates a new binning definition object.

Parameters:

name (str) – The name of the binning definition.
binedges (sequence) – 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 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_binning_range(data)

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

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

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:

new_binning (BinningDefinition instance) – The new BinningDefinition instance 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 (class instance derived from 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 (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 (BinningDefinition) – The binning definition of the given name.

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.CFGClass(*args, **kwargs)

Bases: dict

This class holds the global config state.

The class behaves like a dict, delegating all methods of the dict interface to the underlying config dictionary.

from_yaml(yaml_file: str) → None

Update config with yaml file.

Parameters:: yaml_file – str Path to yaml file.

from_dict(user_dict: Dict[Any, Any]) → None

Creates a config from dictionary.

Parameters:: user_dict – dict

skyllh.core.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.

skyllh.core.config.set_wd(path)

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

Parameters:: path (str) – 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.
Returns:: wd (str) – The project’s working directory.

skyllh.core.config.add_analysis_required_exp_data_field_names(fieldnames)

Adds the given data field names to the set of data field names of the experimental data that are required by the analysis.

Parameters:: fieldnames (str | sequence of str) – The field name or sequence of field names that should get added for the experimental data.

skyllh.core.config.set_analysis_required_exp_data_field_names(fieldnames)

Sets the data field names of the experimental data that are required by the analysis.

Parameters:: fieldnames (str | sequence of str) – The field name or sequence of field names for the experimental data.

skyllh.core.config.set_analysis_required_mc_data_field_names(fieldnames)

Sets the data field names of the monte-carlo data that are required by the analysis.

Parameters:: fieldnames (str | sequence of str) – The field name or sequence of field names for the monte-carlo data.

skyllh.core.coords module

skyllh.core.coords.rotate_spherical_vector(ra1, dec1, ra2, dec2, ra3, dec3)

Calculates the rotation matrix R to rotate the spherical vector (ra1,dec1) onto the direction (ra2,dec2), and performs this rotation on the spherical vector (ra3,dec3).

In practice (ra1,dec1) refers to the true location of a MC event, (ra2,dec2) the true location of the signal source, and (ra3,dec3) the reconstructed location of the MC event, which should get rotated according to the rotation of the two true directions.

skyllh.core.dataset module

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)

Bases: object

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.

Independet 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) – The file name(s), including paths, of the monte-carlo data file(s).
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 uppon 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 CFG['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.

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 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 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 loading_extra_exp_field_name_list: The list of extra field names that should get loaded when loading experimental data. These should only be field names that are required during the data preparation of this specific data set.

property loading_extra_mc_field_name_list: The list of extra field names that should get loaded when loading monte-carlo data. These should only be field names that are required during the data preparation of this specific data set.

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 data set 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.

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.

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.

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

Loads the data, which is described by the dataset.

Note: This does not call the prepare_data method! It only loads: the data as the method names says.

Parameters:

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.
livetime (float | None) – If not None, uses this livetime (in days) for the DatasetData instance, otherwise uses the Dataset livetime property value for the DatasetData instance.
dtc_dict (dict | None) – This dictionary defines how data fields of specific data types should get converted into other data types. This can be used to use less memory. If set to None, no data convertion 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 (TimeLord instance | None) – The TimeLord instance to use to time the data loading procedure.

Returns:

data (DatasetData) – A DatasetData instance 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 (TimeLord instance | 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 (DatasetData instance) – The DatasetData instance holding the data.
tl (TimeLord instance | None) – The TimeLord instance that should be used to time the data preparation.

load_and_prepare_data(livetime=None, keep_fields=None, compress=False, 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.
compress (bool) – Flag if the float64 data fields of the data should get converted, i.e. compressed, into float32 data fields, in order to save main memory. The only field, which will not get converted is the ‘mcweight’ field, in order to ensure reliable calculations. Default is False.
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 (TimeLord instance | None) – The TimeLord instance that should be used to time the data loading and preparation.

Returns:

data (DatasetData) – The DatasetData instance 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 (BinningDefinition instance) – The requested BinningDefinition instance.

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 (BinningDefinition) – The BinningDefinition object which was created and added to this season.

replace_binning_definition(binning)

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

Parameters:: binning (BinningDefinition instance) – The instance of BinningDefinition that will replace the data set’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. 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.

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.

remove_aux_data_definition(name)

Removes the auxiliary data definition from the dataset.

Parameters:: name (str) – The name of the dataset 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)

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.
Returns:: data (unspecified) – The retrieved auxiliary data.
Raises:: KeyError – If no auxiliary data is stored with the given name.

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.

__iadd__(ds): Implementation of the self += dataset operation to add a Dataset object to this dataset collection.

add_datasets(datasets)

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

Parameters:: datasets (Dataset | sequence of Dataset) – The Dataset object or the sequence of Dataset objects that should be added to the dataset collection.
Returns:: self (DatasetCollection) – This DatasetCollection object in order to be able to chain several add_dataset 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(index=-1)

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

Parameters:: index (int, optional) – Index of which data preparation function to remove. Default value is the last added function.

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

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

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 (TimeLord instance | None) – The TimeLord instance that should be used to time the data load operation.
ppbar (instance of ProgressBar | None) – The optional parent progress bar.

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)

Bases: object

This class provides the container for the actual experimental and monto-carlo data. It also holds a reference to the Dataset instance, which holds the data’s meta information.

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 monto-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.

property livetime: The integrated livetime in days of the data.

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.

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 (numpy record ndarray) – The numpy record ndarray 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 (numpy record ndarray) – The array holding the experimental data events with the specified events removed.

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}’

‘{<verqualifiers_key>:d}’

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.

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

Gets DatasetData and Livetime objects with data subsets between the given time range from t_start to t_end.

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:

dataset_data_subset (DatasetData) – DatasetData object with subset of the data between the given time range from t_start to t_end.
livetime_subset (Livetime) – Livetime object with subset of the data between the given time range from t_start to t_end.

skyllh.core.debugging module

skyllh.core.debugging.enable_tracing(): Enables the tracing log debug messages of SkyLLH.

skyllh.core.debugging.disable_tracing(): Disables the tracing log debug messages of SkyLLH.

skyllh.core.debugging.is_tracing_enabled(): Returns True, if tracing is enabled, False otherwise.

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(name, log_level=None, log_format=None, stream=None)

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

Parameters:

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(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:

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.

class skyllh.core.debugging.QueueHandler(queue)

Bases: Handler

This handler sends events to a queue. Typically, it would be used together with a multiprocessing Queue to centralise logging to file in one process (in a multi-process application), so as to avoid file write contention between processes.

This code is new in Python 3.2, but this class can be copy pasted into user code for use with earlier Python versions.

Initialise an instance, using the passed queue.

enqueue(record)

Enqueue a record.

The base implementation uses put_nowait. You may want to override this method if you want to use blocking, timeouts or custom queue implementations.

prepare(record)

Prepares a record for queuing. The object returned by this method is enqueued.

The base implementation formats the record to merge the message and arguments, and removes unpickleable items from the record in-place.

You might want to override this method if you want to convert the record to a dict or JSON string, or send a modified copy of the record while leaving the original intact.

emit(record)

Emit a record.

Writes the LogRecord to the queue, preparing it for pickling first.

skyllh.core.detsigyield module

skyllh.core.detsigyield.get_integrated_livetime_in_days(livetime)

Gets the integrated live-time in days from the given livetime argument.

Parameters:: livetime (float | Livetime instance) – The live-time in days as float, or an instance of Livetime.
Returns:: livetime_days (float) – The integrated live-time in days.

class skyllh.core.detsigyield.DetSigYield(implmethod, dataset, fluxmodel, livetime)

Bases: object

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

The detector signal yield, Y_s(x_s,p_s), is defined as the expected mean number of signal events detected by the detector from a given source at position x_s with flux fit 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 live time, and an implementation method that knows howto contruct 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:

implmethod (instance of DetSigYieldImplMethod) – The implementation method to use for constructing and receiving the detector signal yield. The appropriate method depends on the used flux model.
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 implmethod

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.

property n_fitparams: (read-only) The number of fit parameters this detector signal yield depends on.

property fitparam_names: (read-only) The list of fit parameter names this detector signal yield depends on.

source_to_array(source)

Converts the (sequence of) source(s) into a numpy record array needed for the __call__ method. This convertion is intrinsic to the implementation method.

Parameters:: source (SourceModel | sequence of SourceModel) – The source model containing the spatial information of the source.
Returns:: arr (numpy record ndarray) – The generated numpy record ndarray holding the spatial information for each source.

abstract __call__(src, src_flux_params)

Abstract method to retrieve the detector signal yield for the given sources and source flux parameters.

Parameters:

src (numpy record ndarray) – The numpy record array containing the spatial information of the signal sources. The required fields of this record array are implementation method dependent. In the most generic case for a point-like source, it must contain the following three fields: ra, dec, time.
src_flux_params (numpy record ndarray) – The numpy record ndarray containing the flux parameters of the sources. The flux parameters can be different for the different sources.

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 (None | (N_sources,N_fitparams)-shaped 2D ndarray) – The gradient of the detector signal yield w.r.t. each fit parameter for each source. If the detector signal yield depends on no fit parameter, None is returned.

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

Bases: object

Abstract base class for an implementation method 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.

property supported_sourcemodels: The tuple with the SourceModel classes, which are supported by this detector signal yield implementation method.

property supported_fluxmodels: The tuple with the FluxModel classes, which are supported by this detector signal yield implementation method.

property n_signal_fitparams: (read-only) The number of signal fit parameters the detector signal yield depends on.

property signal_fitparam_names: (read-only) The list of fit parameter names the detector signal yield depends on. An empty list indicates that it does not depend on any fit parameter.

supports_sourcemodel(sourcemodel): Checks if the given source model is supported by this detected signal yield implementation method.

supports_fluxmodel(fluxmodel): Checks if the given flux model is supported by this detector signal yield implementation method.

abstract construct_detsigyield(dataset, data, fluxmodel, livetime)

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 (Dataset) – The Dataset instance holding possible dataset specific settings.
data (DatasetData) – The DatasetData 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.

Returns:

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

abstract source_to_array(source)

This method is supposed to convert a (list of) source model(s) into a numpy record array that is understood by the implementation method. 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:: source (SourceModel | sequence of SourceModel) – The source model containing the spatial information of the source.
Returns:: arr (numpy record ndarray) – The generated numpy record ndarray holding the spatial information for each source.

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.interpolate module

This module provides functionality for interpolation.

class skyllh.core.interpolate.GridManifoldInterpolationMethod(f, param_grid_set)

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:

f (callable R^d -> R) –
The function that takes d parameters as input and returns the value of the d-dimensional manifold at this point for each given event. The call signature of f must be:

__call__(tdm, gridparams, eventdata)

where tdm is the TrialDataManager instance holding the trial data, gridparams is the dictionary with the parameter values on the grid, and eventdata is a 2-dimensional (N,V)-shaped numpy ndarray holding the event data, where N is the number of events, and V the dimensionality of the event data.
param_grid_set (ParameterGrid instance | ParameterGridSet instance) – The set of d parameter grids. This defines the grid of the manifold.

property f: The R^d -> R manifold function.

property param_grid_set: The ParameterGridSet object defining the set of d parameter grids. This defines the grid of the manifold.

property ndim: (read-only) The dimensionality of the manifold.

abstract get_value_and_gradients(tdm, eventdata, params)

Retrieves the interpolated value of the manifold at the d-dimensional point params for all given events, along with the d gradients, i.e. partial derivatives.

Parameters:

tdm (TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (numpy (N_events,V)-shaped 2D ndarray) – The 2D (N_events,V)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params (dict) – The dictionary with the parameter values, defining the point on the manifold for which the value should get calculated.

Returns:

value ((N,) ndarray of float) – The interpolated manifold value for the N given events.
gradients ((D,N) ndarray of float) – The D manifold gradients for the N given events, 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(f, param_grid_set)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method performes no interpolation. When the get_value_and_gradients 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:

f (callable R^D -> R) –
The function that takes the parameter grid value as input and returns the value of the n-dimensional manifold at this point for each given event.

__call__(tdm, gridparams, eventdata)

where gridparams is the dictionary with the parameter names and values on the grid, and eventdata is a 2-dimensional (N,V)-shaped numpy ndarray holding the event data, where N is the number of events, and V the dimensionality of the event data. The return value of f must be a (N,)-shaped 1d ndarray of float.
param_grid_set (ParameterGrid instance | ParameterGridSet instance) – The set of parameter grids. This defines the grid of the D-dimensional manifold.

get_value_and_gradients(tdm, eventdata, params)

Calculates the non-interpolated manifold value and its gradient (zero) for each given event at the point params. By definition the D values of params must coincide with the parameter grid values.

Parameters:

tdm (TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (numpy (N_events,V)-shaped 2D ndarray) – The 2D (N_events,V)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params (dict) – The dictionary with the D parameter values, defining the point on the manifold for which the value should get calculated.

Returns:

value ((N,) ndarray of float) – The interpolated manifold value for the N given events.
gradients ((D,N) ndarray of float) – The D manifold gradients for the N given events, where D is the number of parameters. By definition, all gradients are zero.

class skyllh.core.interpolate.Linear1DGridManifoldInterpolationMethod(f, param_grid_set)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method interpolates the 1-dimensional grid manifold using a line.

Creates a new Linear1DGridManifoldInterpolationMethod instance.

Parameters:

f (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 event.

__call__(tdm, gridparams, eventdata)

where gridparams is the dictionary with the parameter names and values on the grid, and eventdata is a 2-dimensional (N,V)-shaped numpy ndarray holding the event data, where N is the number of events, and V the dimensionality of the event data. The return value of f must be a (N,)-shaped 1d ndarray of float.
param_grid_set (ParameterGrid instance | ParameterGridSet instance) – The set of parameter grids. This defines the grid of the 1-dimensional manifold. By definition, only the first parameter grid is considered.

get_value_and_gradients(tdm, eventdata, params)

Calculates the interpolated manifold value and its gradient for each given event at the point params.

Parameters:

tdm (TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (numpy (N_events,V)-shaped 2D ndarray) – The 2D (N_events,V)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params (dict) – The dictionary with the parameter values, defining the point on the manifold for which the value should get calculated.

Returns:

value ((N,) ndarray of float) – The interpolated manifold value for the N given events.
gradients ((D,N) ndarray of float) – The D manifold gradients for the N given events, where D is the number of parameters.

class skyllh.core.interpolate.Parabola1DGridManifoldInterpolationMethod(f, param_grid_set)

Bases: GridManifoldInterpolationMethod

This grid manifold interpolation method interpolates the 1-dimensional grid manifold using a parabola.

Creates a new Parabola1DGridManifoldInterpolationMethod instance.

Parameters:

f (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 event. The call signature of f must be:

__call__(tdm, gridparams, eventdata)

where gridparams is the dictionary with the parameter names and values on the grid, and eventdata is a 2-dimensional (N,V)-shaped numpy ndarray holding the event data, where N is the number of events, and V the dimensionality of the event data.
param_grid_set (instance of ParameterGridSet) – The set of parameter grids. This defines the grid of the 1-dimensional manifold. By definition, only the first parameter grid is considered.

get_value_and_gradients(tdm, eventdata, params)

Calculates the interpolated manifold value and its gradient for each given event at the point params.

Parameters:

tdm (TrialDataManager) – The TrialDataManager instance holding the trial data.
eventdata (numpy (N_events,V)-shaped 2D ndarray) – The 2D (N_events,V)-shaped numpy ndarray holding the event data, where N_events is the number of events, and V the dimensionality of the event data.
params (dict) – The dictionary with the parameter values, defining the point on the manifold for which the value should get calculated.

Returns:

value ((N,) ndarray of float) – The interpolated manifold value for the N given events.
gradients ((D,N) 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)

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.

assert_mjd_intervals_integrity()

Checks if the internal MJD interval array conforms with all its data requirements.

Raises TypeError if the data array is not a float64 array. Raises 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 of the detector live-time.

property time_end: (read-only) The end of the detector live-time.

load_from_ontime_mjd_intervals(intervals)

Loads the internal MJD uptime intervals from the given interval array.

Parameters:: intervals (Nx2 ndarray holding the MJD edges of the on-time intervals.) –

get_ontime_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_ontime_upto(mjd)

Calculates the cumulative detector on-time up to the given time.

Parameters:: mjd (float | array of floats) – The time in MJD up to which the detector on-time should be calculated.
Returns:: ontimes (float | ndarray of floats) – The ndarray holding the cumulative detector on-time 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)

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.

Returns:

ontimes (ndarray) – The 1d array holding the generated MJD times.

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(minimizer)

Bases: object

Abstract base class for a log-likelihood (LLH) ratio function.

Creates a new LLH ratio function instance.

Parameters:: minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.

property minimizer: The Minimizer instance used to minimize the negative of the log-likelihood ratio function.

initialize_for_new_trial(tl=None)

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 (TimeLord | None) – The optional TimeLord instance to use for timing measurements.

abstract evaluate(fitparam_values, tl=None)

This method evaluates the LLH ratio function for the given set of fit parameter values.

Parameters:

fitparam_values (numpy 1D ndarray) – The ndarray holding the current values of the (global) fit parameters.
tl (TimeLord | None) – The optional TimeLord instance to use for measuring timeing.

Returns:

log_lambda (float) – The calculated log-lambda value.
grads ((N_fitparams,)-shaped 1D ndarray) – The ndarray holding the gradient value for each (global) fit parameter.

maximize(rss, fitparamset, tl=None)

Maximize the log-likelihood ratio function, by using the evaluate method.

Parameters:

rss (RandomStateService instance) – The RandomStateService instance to draw random numbers from. This is needed to generate random parameter initial values.
fitparamset (FitParameterSet instance) – The instance of FitParameterSet holding the global fit parameter definitions used in the maximization process.
tl (TimeLord instance | None) – The optional TimeLord instance 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 ((N_fitparam)-shaped 1D ndarray) – The 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.TCLLHRatio(minimizer, mean_n_sig_0)

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:: 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(fitparam_values)

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 (numpy (N_fitparams,)-shaped 1D ndarray) – The ndarray holding the current values of the fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
Returns:: nsgrad2 (float) – The second derivative w.r.t. ns of the log-likelihood ratio function for the given fit parameter values.

maximize(rss, fitparamset, 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 (RandomStateService instance) – The RandomStateService instance that should be used to draw random numbers from. It is used by the minimizer to generate random fit parameter initial values.
fitparamset (FitParameterSet instance) – The instance of FitParameterSet holding the global fit parameter definitions used in the maximization process.
tl (TimeLord instance | None) – The optional TimeLord instance 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 ((N_fitparam)-shaped 1D ndarray) – The 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(minimizer, src_hypo_group_manager, src_fitparam_mapper, tdm, mean_n_sig_0)

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:

minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance that defines the source hypotheses.
src_fitparam_mapper (SourceFitParameterMapper) – The instance of SourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters. The order of the fit parameters defines the order of the fit values during the maximization process of the log-likelihood-ratio function. The names of the source fit parameters must coincide with the signal fit parameter names of the PDF instances.
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 src_hypo_group_manager: The SourceHypoGroupManager instance that defines the source hypotheses.

property src_fitparam_mapper: The SourceFitParameterMapper instance defining the global fit parameters and their mapping to the source fit parameters.

property tdm: The TrialDataManager instance that holds the trial event data and additional data fields for this LLH ratio function.

change_source_hypo_group_manager(src_hypo_group_manager)

Changes the source hypothesis group manager of this two-component LLH ratio function.

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance.

class skyllh.core.llhratio.ZeroSigH0SingleDatasetTCLLHRatio(minimizer, src_hypo_group_manager, src_fitparam_mapper, tdm, pdfratios)

Bases: SingleDatasetTCLLHRatio

This class implements a two-component (TC) log-likelihood (LLH) ratio function for a single data assuming zero signal for the null-hypothesis. The log-likelihood-ratio function uses a list of independent PDF ratio instances.

Constructor of the two-component log-likelihood ratio function.

Parameters:

minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance that defines the source hypotheses.
src_fitparam_mapper (SourceFitParameterMapper) – The instance of SourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters. The order of the fit parameters defines the order of the fit values during the maximization process of the log-likelihood-ratio function. The names of the source fit parameters must coincide with the signal fit parameter names of the PDF ratio instances.
tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.
pdfratios (sequence of PDFRatio) – The sequence of PDFRatio instances. 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_list: The list of PDFRatio instances.

calculate_log_lambda_and_grads(fitparam_values, N, ns, Xi, dXi_ps)

Calculates the log(Lambda) value and its gradient for each global fit parameter. This calculation is source and detector independent.

Parameters:

fitparam_values (numpy (N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the current values of the fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns. 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 current fit parameter value for ns.
Xi (numpy (n_selected_events,)-shaped 1D ndarray) – The X value of each selected event.
dXi_ps (numpy (N_fitparams,n_selected_events)-shaped 2D ndarray) – The derivative value for each fit parameter ps of each event’s X value.

Returns:

log_lambda (float) – The value of the log-likelihood ratio function.
grads (1D numpy (N_fitparams+1,)-shaped ndarray) – The gradient value of log_lambda for each fit parameter. The first element is the gradient for ns.

calculate_ns_grad2(fitparam_values)

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 fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
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.SingleSourceZeroSigH0SingleDatasetTCLLHRatio(minimizer, src_hypo_group_manager, src_fitparam_mapper, tdm, pdfratios)

Bases: ZeroSigH0SingleDatasetTCLLHRatio

This class implements a 2-component, i.e. signal and background, log-likelihood ratio function for a single data set. The log-likelihood-ratio function assumes a zero signal null-hypothesis and uses a list of independent PDFRatio instances assuming a single source.

Constructor for creating a 2-component, i.e. signal and background, log-likelihood ratio function assuming a single source.

Parameters:

minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance that defines the source hypotheses.
src_fitparam_mapper (SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters. The order of the fit parameters defines the order of the fit values during the maximization process. The names of the source fit parameters must coincide with the signal fit parameter names of the PDF ratio objects.
tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.
pdfratios (list of PDFRatio) – The list of PDFRatio instances. A PDFRatio instance might depend on none, one, or several fit parameters.

initialize_for_new_trial(tl=None)

Initializes the log-likelihood ratio function for a new trial.

Parameters:: tl (TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

evaluate(fitparam_values, tl=None)

Evaluates the log-likelihood ratio function for the given set of data events.

Parameters:

fitparam_values (numpy (N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the current values of the fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
tl (TimeLord instance | None) – The optional TimeLord instance to measure the timing of evaluating the LLH ratio function.

Returns:

log_lambda (float) – The calculated log-lambda value.
grads ((N_fitparams+1,)-shaped 1D ndarray) – The ndarray holding the gradient value of log_lambda for each fit parameter and ns. The first element is the gradient for ns.

class skyllh.core.llhratio.MultiSourceZeroSigH0SingleDatasetTCLLHRatio(minimizer, src_hypo_group_manager, src_fitparam_mapper, tdm, pdfratios, detsigyields)

Bases: SingleSourceZeroSigH0SingleDatasetTCLLHRatio

This class implements a 2-component, i.e. signal and background, log-likelihood ratio function for a single data set assuming zero signal for the null-hypothesis. It uses a list of independent PDFRatio instances assuming multiple sources (stacking).

Constructor for creating a 2-component, i.e. signal and background, log-likelihood ratio function assuming a single source.

Parameters:

minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance that defines the source hypotheses.
src_fitparam_mapper (SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters. The order of the fit parameters defines the order of the fit values during the maximization process. The names of the source fit parameters must coincide with the signal fit parameter names of the PDF ratio objects.
tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data and additional data fields for this LLH ratio function.
pdfratios (list of PDFRatio) – The list of PDFRatio instances. A PDFRatio instance might depend on none, one, or several fit parameters.
detsigyields ((N_source_hypo_groups,)-shaped 1D ndarray of DetSigYield) – instances The collection of DetSigYield instances for each source hypothesis group.

evaluate(fitparam_values, tl=None)

Evaluates the log-likelihood ratio function for the given set of data events.

Parameters:

fitparam_values (numpy (N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the current values of the fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
tl (TimeLord instance | None) – The optional TimeLord instance to measure the timing of evaluating the LLH ratio function.

Returns:

log_lambda (float) – The calculated log-lambda value.
grads ((N_fitparams+1,)-shaped 1D ndarray) – The ndarray holding the gradient value of log_lambda for each fit parameter and ns. The first element is the gradient for ns.

class skyllh.core.llhratio.DatasetSignalWeights(src_hypo_group_manager, src_fitparam_mapper, detsigyields)

Bases: object

Abstract base class for a dataset signal weight calculator class.

Base class constructor.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of the SourceHypoGroupManager managing the source hypothesis groups.
src_fitparam_mapper (SourceFitParameterMapper) – The SourceFitParameterMapper instance that defines the global fit parameters and their mapping to the source fit parameters.
detsigyields (2D (N_source_hypo_groups,N_datasets)-shaped ndarray of) – DetSigYield instances The collection of DetSigYield instances for each dataset and source group combination. The detector signal yield instances are used to calculate the dataset signal weight factors. The order must follow the definition order of the log-likelihood ratio functions, i.e. datasets, and the definition order of the source hypothesis groups.

property src_hypo_group_manager: The instance of SourceHypoGroupManager, which defines the source hypothesis groups.

property src_fitparam_mapper: The SourceFitParameterMapper instance defining the global fit parameters and their mapping to the source fit parameters.

property detsigyield_arr: The 2D (N_source_hypo_groups,N_datasets)-shaped ndarray of DetSigYield instances.

property n_datasets: (read-only) The number of datasets this DatasetSignalWeights instance is for.

change_source_hypo_group_manager(src_hypo_group_manager)

Changes the SourceHypoGroupManager instance of this DatasetSignalWeights instance. This will also recreate the internal source numpy record arrays needed for the detector signal efficiency calculation.

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance, that should be used for this dataset signal weights instance.

abstract __call__(fitparam_values)

This method is supposed to calculate the dataset signal weights and their gradients.

Parameters:

fitparam_values ((N_fitparams+1,)-shaped 1D numpy ndarray) – The ndarray holding the current values of the fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

f ((N_datasets,)-shaped 1D ndarray) – The dataset signal weight factor for each dataset.
f_grads ((N_datasets,N_fitparams)-shaped 2D ndarray) – The gradients of the dataset signal weight factors, one for each fit parameter.

class skyllh.core.llhratio.SingleSourceDatasetSignalWeights(src_hypo_group_manager, src_fitparam_mapper, detsigyields)

Bases: DatasetSignalWeights

This class calculates the dataset signal weight factors for each dataset assuming a single source.

Constructs a new DatasetSignalWeights instance assuming a single source.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of the SourceHypoGroupManager managing the source hypothesis groups.
src_fitparam_mapper (SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters.
detsigyields (2D (N_source_hypo_groups,N_datasets)-shaped ndarray of) – DetSigYield instances The collection of DetSigYield instances for each dataset and source group combination. The detector signal yield instances are used to calculate the dataset signal weight factors. The order must follow the definition order of the log-likelihood ratio functions, i.e. datasets, and the definition order of the source hypothesis groups.

__call__(fitparam_values)

Calculates the dataset signal weight and its fit parameter gradients for each dataset.

Parameters:

fitparam_values ((N_fitparams+1,)-shaped 1D numpy ndarray) – The ndarray holding the current values of the fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

f ((N_datasets,)-shaped 1D ndarray) – The dataset signal weight factor for each dataset.
f_grads ((N_datasets,N_fitparams)-shaped 2D ndarray | None) – The gradients of the dataset signal weight factors, one for each fit parameter. None is returned if there are no fit parameters beside ns.

class skyllh.core.llhratio.MultiSourceDatasetSignalWeights(src_hypo_group_manager, src_fitparam_mapper, detsigyields)

Bases: SingleSourceDatasetSignalWeights

This class calculates the dataset signal weight factors for each dataset assuming multiple sources.

Constructs a new DatasetSignalWeights instance assuming multiple sources.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of the SourceHypoGroupManager managing the source hypothesis groups.
src_fitparam_mapper (SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters.
detsigyields (2D (N_source_hypo_groups,N_datasets)-shaped ndarray of) – DetSigYield instances The collection of DetSigYield instances for each dataset and source group combination. The detector signal yield instances are used to calculate the dataset signal weight factors. The order must follow the definition order of the log-likelihood ratio functions, i.e. datasets, and the definition order of the source hypothesis groups.

__call__(fitparam_values)

Calculates the dataset signal weight and its fit parameter gradients for each dataset.

Parameters:

fitparam_values ((N_fitparams+1,)-shaped 1D numpy ndarray) – The ndarray holding the current values of the fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

f ((N_datasets,)-shaped 1D ndarray) – The dataset signal weight factor for each dataset.
f_grads ((N_datasets,N_fitparams)-shaped 2D ndarray | None) – The gradients of the dataset signal weight factors, one for each fit parameter. None is returned if there are no fit parameters beside ns.

class skyllh.core.llhratio.SourceWeights(src_hypo_group_manager, src_fitparam_mapper, detsigyields)

Bases: object

Abstract base class for a source weight calculator class.

Constructs a new SourceWeights instance.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of the SourceHypoGroupManager managing the source hypothesis groups.
src_fitparam_mapper (SourceFitParameterMapper) – The SourceFitParameterMapper instance that defines the global fit parameters and their mapping to the source fit parameters.
detsigyields ((N_source_hypo_groups,)-shaped 1D ndarray of DetSigYield) – instances The collection of DetSigYield instances for each source hypothesis group.

property src_hypo_group_manager: The instance of SourceHypoGroupManager, which defines the source hypothesis groups.

property src_fitparam_mapper: The SourceFitParameterMapper instance defining the global fit parameters and their mapping to the source fit parameters.

property detsigyield_arr: The (N_source_hypo_groups,)-shaped 1D ndarray of DetSigYield instances.

change_source_hypo_group_manager(src_hypo_group_manager)

Changes the SourceHypoGroupManager instance of this DatasetSignalWeights instance. This will also recreate the internal source numpy record arrays needed for the detector signal efficiency calculation.

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance, that should be used for this dataset signal weights instance.

abstract __call__(fitparam_values)

This method is supposed to calculate source weights and their gradients.

Parameters:

fitparam_values ((N_fitparams+1,)-shaped 1D numpy ndarray) – The ndarray holding the current values of the fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

f ((N_sources,)-shaped 1D ndarray) – The source weight factor for each source.
f_grads ((N_sources,)-shaped 1D ndarray | None) – The gradients of the source weight factors. None is returned if there are no fit parameters beside ns.

class skyllh.core.llhratio.MultiPointSourcesRelSourceWeights(src_hypo_group_manager, src_fitparam_mapper, detsigyields)

Bases: SourceWeights

This class calculates the relative source weights for a group of point sources.

Constructs a new MultiPointSourcesRelSourceWeights instance assuming multiple sources.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of the SourceHypoGroupManager managing the source hypothesis groups.
src_fitparam_mapper (SingleSourceFitParameterMapper) – The instance of SingleSourceFitParameterMapper defining the global fit parameters and their mapping to the source fit parameters.
detsigyields ((N_source_hypo_groups,)-shaped 1D ndarray of) – DetSigYield instances The collection of DetSigYield instances for each source hypothesis group.

__call__(fitparam_values)

Calculates the source weights and its fit parameter gradients for each source.

Parameters:

fitparam_values ((N_fitparams+1,)-shaped 1D numpy ndarray) – The ndarray holding the current values of the fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

f ((N_sources,)-shaped 1D ndarray) – The source weight factor for each source.
f_grads ((N_sources,)-shaped 1D ndarray | None) – The gradients of the source weight factors. None is returned if there are no fit parameters beside ns.

class skyllh.core.llhratio.MultiDatasetTCLLHRatio(minimizer, dataset_signal_weights, llhratios)

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:

minimizer (instance of Minimizer) – The Minimizer instance that should be used to minimize the negative of this log-likelihood ratio function.
dataset_signal_weights (DatasetSignalWeights) – An instance of DatasetSignalWeights, which calculates the relative dataset weight factors.
llhratios (sequence of SingleDatasetTCLLHRatio instances) – The sequence of the two-component log-likelihood ratio functions, one for each dataset.

property dataset_signal_weights: The DatasetSignalWeights instance that provides the relative dataset 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_source_hypo_group_manager(src_hypo_group_manager): Changes the source hypo group manager of all objects of this LLH ratio function, hence, calling the change_source_hypo_group_manager method of all TCLLHRatio objects of this LLHRatio instance.

initialize_for_new_trial(tl=None): Initializes the log-likelihood-ratio function for a new trial.

evaluate(fitparam_values, tl=None)

Evaluates the composite log-likelihood-ratio function and returns its value and global fit parameter gradients.

Parameters:

fitparam_values ((N_fitparams)-shaped numpy 1D ndarray) – The ndarray holding the current values of the global fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

log_lambda (float) – The calculated log-lambda value of the composite log-likelihood-ratio function.
grads ((N_fitparams,)-shaped 1D ndarray) – The ndarray holding the gradient value of the composite log-likelihood-ratio function for ns and each global fit parameter. By definition the first element is the gradient for ns.

calculate_ns_grad2(fitparam_values)

Calculates the second derivative w.r.t. ns of the log-likelihood ratio function. This method tries to use cached values for the dataset signal weight factors. 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 fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
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(minimizer, mean_n_sig_0, llhratio)

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_s) = \frac{L(n_s)}{L(n_s=n_{s,0})},\]

where \(n_{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 ns is fixed to mean_n_sig_0.

Parameters:

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_source_hypo_group_manager(src_hypo_group_manager): Changes the source hypo group manager of all objects of this LLH ratio function, hence, calling the change_source_hypo_group_manager method of the underlaying MultiDatasetTCLLHRatio instance of this LLHRatio instance.

initialize_for_new_trial(tl=None)

Initializes the log-likelihood-ratio function for a new trial.

Parameters:: tl (TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

evaluate(fitparam_values)

Evaluates the log-likelihood-ratio function and returns its value and global fit parameter gradients.

Parameters:

fitparam_values ((N_fitparams)-shaped numpy 1D ndarray) – The ndarray holding the current values of the global fit parameters. The first element of that array is, by definition, the number of signal events, ns.

Returns:

log_lambda (float) – The calculated log-lambda value of this log-likelihood-ratio function.
grads ((N_fitparams,)-shaped 1D ndarray) – The ndarray holding the gradient value of this log-likelihood-ratio for ns. By definition the first element is the gradient for ns.

calculate_ns_grad2(fitparam_values)

Calculates the second derivative w.r.t. ns of the log-likelihood ratio function.

Parameters:: fitparam_values (numpy (N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the current values of the fit parameters. By definition, the first element is the fit parameter for the number of signal events, ns.
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.

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

Bases: object

Abstract base class for a minimizer implementation. It defines the interface between the implementation and the Minimizer class.

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)

Bases: MinimizerImpl

Wrapper for scipy.optimize.minimize

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.
underlaying (Any additional keyword arguments are passed on to the) –

:param scipy.optimize.minimize() 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.
res (scipy.optimize.OptimizeResult) – 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)

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.
underlaying (Any additional keyword arguments are passed on to the) –

:param 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)

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.MinuitMinimizerImpl(maxls=100)

Bases: MinimizerImpl

The MinuitMinimizerImpl class provides the minimizer implementation for minuit minimizer.

Creates a new minimizer instance.

Parameters:: 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) –
implementation. –

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.NRNsScan2dMinimizerImpl(p2_scan_step, ns_tol=0.001)

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)

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, fitparamset, 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.
fitparamset (instance of FitParameterSet) – The set of FitParameter instances defining fit 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)

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)

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)

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.

Raises:

TypeError – If the cast fails.

Returns:

modelcollection (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)

Bases: Model

This class provides a base class for a detector model. It can be used in combination with the ModelParameterMapper class.

Creates a new DetectorModel instance.

Parameters:: name (str) – The name of the detector model.

skyllh.core.multiproc module

skyllh.core.multiproc.get_ncpu(local_ncpu)

Determines the number of CPUs to use for functions that support multi-processing.

Parameters:: 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(ncpu=None, *args, **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.optimize module

class skyllh.core.optimize.EventSelectionMethod(src_hypo_group_manager)

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:: src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances.

property src_hypo_group_manager: The SourceHypoGroupManager instance, which defines the list of sources.

change_source_hypo_group_manager(src_hypo_group_manager)

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

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – The new SourceHypoGroupManager instance, that should be used for this event selection method.

abstract source_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) – The generated numpy record ndarray holding the necessary information for each source.

abstract select_events(events, retidxs=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 holding the events.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

class skyllh.core.optimize.AllEventSelectionMethod(src_hypo_group_manager)

Bases: EventSelectionMethod

This event selection method selects all events.

Creates a new event selection method instance.

Parameters:: src_hypo_group_manager (SourceHypoGroupManager instance) – 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.

source_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) – The generated numpy record ndarray holding the necessary information for each source.

select_events(events, retidxs=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.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

class skyllh.core.optimize.SpatialEventSelectionMethod(src_hypo_group_manager)

Bases: EventSelectionMethod

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

Creates a new event selection method instance.

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

source_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.optimize.DecBandEventSectionMethod(src_hypo_group_manager, 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:

src_hypo_group_manager (SourceHypoGroupManager instance) – 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, retidxs=False, ret_mask_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.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
ret_mask_idxs (bool) – Flag if also the indices of the selected events mask should get returned as a mask_idxs 1d ndarray. Default is False.
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.
idxs (where idxs is one of the following:) –
- (src_idxs, ev_idxs)1d ndarrays of ints
  The indices of sources and selected events, in case retidxs is set to True.
- mask_idxs1d ndarrays of ints
  The indices of selected events mask, in case ret_mask_idxs is set to True.
- None
  In case both retidxs and ret_mask_idxs are set to False.

class skyllh.core.optimize.RABandEventSectionMethod(src_hypo_group_manager, 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:

src_hypo_group_manager (SourceHypoGroupManager instance) – 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, retidxs=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.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

class skyllh.core.optimize.SpatialBoxEventSelectionMethod(src_hypo_group_manager, 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:

src_hypo_group_manager (SourceHypoGroupManager instance) – 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, retidxs=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.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

class skyllh.core.optimize.PsiFuncEventSelectionMethod(src_hypo_group_manager, 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:

src_hypo_group_manager (SourceHypoGroupManager instance) – 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.

source_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 (None) – Because this event selection method does not depend directly on the source (only indirectly through the psi values), no source array is required.

select_events(events, retidxs=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_list>float
  The name of the axis required for the function func to be evaluated.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

class skyllh.core.optimize.SpatialBoxAndPsiFuncEventSelectionMethod(src_hypo_group_manager, delta_angle, psi_name, func, axis_name_list, psi_floor=None)

Bases: SpatialBoxEventSelectionMethod

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:

src_hypo_group_manager (SourceHypoGroupManager instance) – 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) – 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.
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 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.

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

select_events(events, retidxs=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.
retidxs (bool) – Flag if also the indices of the selected events should get returned as a (src_idxs, ev_idxs) tuple of 1d ndarrays. Default is False.
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, ev_idxs) (1d ndarrays of ints | None) – The indices of sources and selected events, in case retidxs is set to True. Returns None, in case retidxs is set to False.

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.

skyllh.core.parameters.make_params_hash(params)

Utility function to create a hash value for a given parameter dictionary.

Parameters:: params (dict | None) – The dictionary holding the parameter (name: value) pairs. If set to None, an empty dictionary is used.
Returns:: hash (int) – The hash of the parameter dictionary.

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 fixed_params: (read-only) The 1D ndarray holding the Parameter instances, whose values are fixed.

property fixed_params_mask: (read-only) The 1D ndarray holding the mask for the fixed parameters of this parameter set.

property floating_params: (read-only) The 1D ndarray holding the Parameter instances, whose values are floating.

property floating_params_mask: (read-only) The 1D ndarray holding the mask for the floating parameters of this parameter set.

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_name_list: (read-only) The list of the fixed parameter names.

property floating_param_name_list: (read-only) The list of the floating parameter names.

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.

__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.

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.

floating_param_values_to_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:: param_dict (dict) – The dictionary with the floating and fixed parameter names and values.

class skyllh.core.parameters.ParameterSetArray(paramsets)

Bases: object

This class provides a data holder for an array of ParameterSet instances. Given an array of global floating parameter values, it can split that array into floating parameter value sub arrays, one for each ParameterSet instance of this ParameterSetArray instance. This functionality is required in order to be able to map the global floating parameter values from the minimizer to their parameter names.

Creates a new ParameterSetArray instance, which will hold a list of constant ParameterSet instances.

Parameters:: paramsets (const instance of ParameterSet | sequence of const instances) – of ParameterSet The sequence of constant ParameterSet instances holding the global parameters.
Raises:: TypeError – If the given paramsets argument ist not a sequence of constant instances of ParameterSet.

property paramset_list: (read-only) The list of ParameterSet instances holding the global parameters.

property n_params: (read-only) The total number of parameters hold by this ParameterSetArray instance.

property n_fixed_params: (read-only) The total number of fixed parameters hold by this ParameterSetArray instance.

property n_floating_params: (read-only) The total number of floating parameters hold by this ParameterSetArray instance.

property floating_param_initials: (read-only) The 1D (n_floating_params,)-shaped ndarray holding the initial values of all the floating parameters.

property floating_param_bounds: (read-only) The 2D (n_floating_params,2)-shaped ndarray holding the boundaries for all the floating parameters.

generate_random_initials(rss)

Generates a set of random initials for all global 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.

split_floating_param_values(floating_param_values)

Splits the given floating parameter values into their specific ParameterSet part.

Parameters:: floating_param_values ((n_floating_params,)-shaped 1D ndarray) – The ndarray holding the values of all the floating parameters for all ParameterSet instances. The order must match the order of ParameterSet instances and their order of floating parameters.
Returns:: floating_param_values_list (list of (n_floating_params,)-shaped 1D) – ndarray The list of ndarray objects, where each ndarray holds only the floating values of the particular ParameterSet instance. The order matches the order of ParameterSet instances defined for this ParameterSetArray.

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.

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 (ParameterGrid instance) – 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)

Bases: NamedObjectCollection

Describes a set of parameter grids.

Constructs a new ParameterGridSet object.

Parameters:: param_grids (sequence of ParameterGrid instances |) – ParameterGrid instance | None The ParameterGrid instances this ParameterGridSet instance 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 parameter_names: (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.ModelParameterMapper(name, models)

Bases: object

This abstract base class defines the interface of a model parameter mapper. A model parameter 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:

name (str) – The name of the model parameter mapper. In practice this is a representative name for the set of global parameters this model parameter mapper holds. For a two-component signal-background likelihood model, “signal”, or “background” could be useful names.
models (sequence of Model instances.) – The sequence of Model instances the parameter mapper can map global parameters to.

property name: The name of this ModelParameterMapper instance. In practice this is a representative name for the set of global parameters this mapper holds.

property models: 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.

finalize(): Finalizes this ModelParameterMapper instance by declaring its ParameterSet instance as constant. No new global parameters can be added after calling this method.

abstract def_param(param, model_param_name=None, models=None)

This method is supposed to add the given Parameter instance to the parameter mapper and maps the global parameter to the given sequence of models the parameter mapper knows about.

Parameters:

param (instance of Parameter) – The global parameter which should get mapped to one or more models.
model_param_name (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.
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.

abstract get_model_param_dict(global_floating_param_values, model_idx=None)

This method is supposed to create a dictionary with the fixed and floating parameter names and their values for the given model.

Parameters:

global_floating_param_values (1D ndarray instance) – The ndarray instance holding the current values of the global floating parameters.
model_idx (int | None) – The index of the model as it was defined at construction time of this ModelParameterMapper instance.

Returns:

model_param_dict (dict) – The dictionary holding the fixed and floating parameter names and values of the specified model.

class skyllh.core.parameters.SingleModelParameterMapper(name, model)

Bases: ModelParameterMapper

This class provides a model parameter mapper for a single model, like a single source, or a single background model.

Constructs a new model parameter mapper for a single model.

Parameters:

name (str) – The name of the model parameter mapper. In practice this is a representative name for the set of global parameters this model parameter mapper holds. For a two-component signal-background likelihood model, “signal”, or “background” could be useful names.
model (instance of Model) – The instance of Model the parameter mapper can map global parameters to.

def_param(param, model_param_name=None)

Adds the given Parameter instance to the parameter mapper.

Parameters:

param (instance of Parameter) – The global parameter which should get mapped to the single model.
model_param_name (str | None) – The parameter name of the model. Hence, the global parameter name can be different to the parameter name of the model. If set to None, the name of the global parameter will be used as model parameter name.

Returns:

self (SingleModelParameterMapper) – The instance of this SingleModelParameterMapper, so that several def_param calls can be concatenated.

Raises:

KeyError – If there is already a model parameter with the given name defined.

get_model_param_dict(global_floating_param_values, model_idx=None)

Creates a dictionary with the fixed and floating parameter names and their values for the single model.

Parameters:

global_floating_param_values (1D ndarray instance) – The ndarray instance holding the current values of the global floating parameters. The values must be in the same order as the floating parameters were defined.
model_idx (None) – The index of the model as it was defined at construction time of this ModelParameterMapper instance. Since this is a ModelParameterMapper for a single model, this argument is ignored.

Returns:

model_param_dict (dict) – The dictionary holding the fixed and floating parameter names and values of the single model.

class skyllh.core.parameters.MultiModelParameterMapper(name, models)

Bases: ModelParameterMapper

This class provides a model parameter mapper for multiple models, like multiple sources, or multiple background models.

Constructs a new multi model parameter mapper for mapping global parameters to the given models.

Parameters:

name (str) – The name of the model parameter mapper. In practice this is a representative name for the set of global parameters this model parameter mapper holds. For a two-component signal-background likelihood model, “signal”, or “background” could be useful names.
models (sequence of Model instances.) – The sequence of Model instances the parameter mapper can map global parameters to.

def_param(param, model_param_name=None, models=None)

Adds the given Parameter instance to this parameter mapper and maps the parameter to the given sequence of models this model parameter mapper knows about.

Parameters:

param (instance of Parameter) – The global parameter which should get mapped to one or multiple models.
model_param_name (str | None) – The parameter name of the models. The parameter name of the models must be the same for all the models this global parameter should get mapped to. The global parameter name can be different to the parameter name of the models. If set to None, the name of the global parameter will be used as model parameter name.
models (sequence of Model instances | None) – 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. If set to None the global parameter will be mapped to all known models.

Returns:

self (MultiModelParameterMapper) – The instance of this MultiModelParameterMapper, so that several def_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.

get_model_param_dict(global_floating_param_values, model_idx)

Creates a dictionary with the fixed and floating parameter names and their values for the given model.

Parameters:

global_floating_param_values (1D ndarray instance) – The ndarray instance holding the current values of the global floating parameters.
model_idx (int) – The index of the model as it was defined at construction time of this ModelParameterMapper instance.

Returns:

model_param_dict (dict) – The dictionary holding the fixed and floating parameter names and values of the specified model.

class skyllh.core.parameters.HypoParameterDefinition(model_param_mappers)

Bases: NamedObjectCollection

This class provides a data holder for a list of model parameter mappers, where each parameter mapper defines a set of global parameters for the likelihood function, and their mapping to local model parameters. In addition this class provides a method to create a copy of itself, where floating parameters can get fixed to a certain values.

Creates a new instance of HypoParameterDefinition with the given list of ModelParameterMapper instances.

Parameters:: model_param_mappers (instance of ModelParameterMapper | sequence of) – ModelParameterMapper instances The list of ModelParameterMapper instances defining the global parameters and their mapping to local parameters of individual models.

property model_param_mapper_list: (read-only) The list of ModelParameterMapper instances defining the global parameters and their mapping to the individual local model parameters.

copy(fix_params=None)

Creates a deep copy of this HypoParameterDefinition instance and fixes the given global parameters to the given values.

Parameters:: fix_params (dict | None) – The dictionary defining the global parameters that should get fixed in the copy.
Returns:: copy (instance of HypoParameterDefinition) – The copy of this HypoParameterDefinition instance with the given global parameters fixed to the given values.

create_ParameterSetArray()

Creates a ParameterSetArray instance for all the ModelParameterMapper instances of this HypoParameterDefinition instance.

Returns:: paramsetarray (ParameterSetArray) – The instance of ParameterSetArray holding references to the ParameterSet instances of all the ModelParameterMapper instances of this HypoParameterDefinition instance.

class skyllh.core.parameters.FitParameter(name, valmin, valmax, initial)

Bases: object

This class is DEPRECATED! Use class Parameter instead!

This class describes a single fit parameter. A fit parameter has a name, a value range, an initial value, and a current value. The current value will be updated in the fitting process.

Creates a new fit parameter object.

Parameters:

name (str) – The name of the fit parameter.
valmin (float) – The minimal bound value of the fit parameter.
valmax (float) – The maximal bound value of the fit parameter.
initial (float) – The (initial) value (guess) of the parameter, which will be used as start point for the fitting procedure.

property name: The name of the fit parameter.

property valmin: The minimal bound value of the fit parameter.

property valmax: The maximal bound value of the fit parameter.

property initial: The initial value of the fit parameter.

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.

class skyllh.core.parameters.FitParameterSet

Bases: object

This class is DEPRECATED, use ParameterSet instead!

This class describes a set of FitParameter instances.

Constructs a fit parameter set instance.

property fitparams: The 1D ndarray holding the FitParameter instances.

property fitparam_list: (read-only) The list of the global FitParameter instances.

property fitparam_name_list: (read-only) The list of the fit parameter names.

property initials: (read-only) The 1D ndarray holding the initial values of all the global fit parameters.

property bounds: (read-only) The 2D (N_fitparams,2)-shaped ndarray holding the boundaries for all the global fit parameters.

copy()

Creates a deep copy of this FitParameterSet instance.

Returns:: copy (FitParameterSet instance) – The copied instance of this FitParameterSet instance.

add_fitparam(fitparam, atfront=False)

Adds the given FitParameter instance to the list of fit parameters.

Parameters:

fitparam (instance of FitParameter) – The fit parameter, which should get added.
atfront (bool) – Flag if the fit parameter should be added at the front of the parameter list. If set to False (default), it will be added at the back.

fitparam_values_to_dict(fitparam_values)

Converts the given fit parameter values into a dictionary with the fit parameter names and values.

Parameters:: fitparam_values (1D ndarray) – The ndarray holding the fit parameter values in the order that the fit parameters are defined.
Returns:: fitparam_dict (dict) – The dictionary with the fit parameter names and values.

fitparam_dict_to_values(fitparam_dict)

Converts the given fit parameter dictionary into a 1D ndarray holding the fit parameter values in the order the fit parameters are defined.

Parameters:: fitparam_dict (dict) – The dictionary with the fit parameter names and values.
Returns:: fitparam_values (1D ndarray) – The ndarray holding the fit parameter values in the order that the fit parameters are defined.

generate_random_initials(rss)

Generates a set of random initials for all global fit 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.

class skyllh.core.parameters.SourceFitParameterMapper

Bases: object

This abstract base class defines the interface of the source fit parameter mapper. This mapper provides the functionality to map a global fit parameter to a source fit parameter.

Constructor of the source fit parameter mapper.

property fitparamset: (read-only) The FitParameterSet instance holding the list of global fit parameters.

property n_global_fitparams: (read-only) The number of defined global fit parameters.

get_src_fitparam_name(fitparam_idx)

Returns the name of the source fit parameter for the given global fit parameter index.

Parameters:: fitparam_idx (int) – The index of the global fit parameter.
Returns:: src_fitparam_name (str) – The name of the source fit parameter.

abstract def_fit_parameter(fit_param, src_param_name=None, sources=None)

This method is supposed to define a new fit parameter that maps to a given source fit parameter for a list of sources. If no list of sources is given, it maps to all sources.

Parameters:

fit_param (FitParameter) – The FitParameter instance defining the fit parameter.
src_param_name (str | None) – The name of the source parameter. It must match the name of a source model property. If set to None (default) the name of the fit parameter will be used.
sources (sequence of SourceModel | None) – The sequence of SourceModel instances for which the fit parameter applies. If None (the default) is specified, the fit parameter will apply to all sources.

abstract get_src_fitparams(fitparam_values, src_idx=0)

This method is supposed to create a dictionary of source fit parameter names and values for the requested source based on the given fit parameter values.

Parameters:

fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
src_idx (int) – The index of the source for which the parameters should get retrieved.

Returns:

src_fitparams (dict) – The dictionary holding the translated source parameters that are beeing fitted.

abstract get_fitparams_array(fitparam_values)

This method is supposed to create a numpy record ndarray holding the unique source fit parameter names as key and their value for each source. The returned array must be (N_sources,)-shaped.

Parameters:: fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
Returns:: fitparams_arr ((N_sources,)-shaped numpy record ndarray | None) – The numpy record ndarray holding the fit parameter names as keys and their value for each source in each row. None must be returned if no global fit parameters were defined.

class skyllh.core.parameters.SingleSourceFitParameterMapper

Bases: SourceFitParameterMapper

This class provides the functionality to map the global fit parameters to the source fit parameters of the single source. This class assumes a single source, hence the mapping can be performed faster than in the multi-source case.

Constructs a new source fit parameter mapper for a single source.

def_fit_parameter(fitparam, src_param_name=None)

Define a new fit parameter that maps to a given source fit parameter.

Parameters:

fitparam (FitParameter) – The FitParameter instance defining the fit parameter.
src_param_name (str | None) – The name of the source parameter. It must match the name of a source model property. If set to None (default) the name of the fit parameter will be used.

get_src_fitparams(fitparam_values)

Create a dictionary of source fit parameter names and values based on the given fit parameter values.

Parameters:: fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
Returns:: src_fitparams (dict) – The dictionary holding the translated source parameters that are beeing fitted. An empty dictionary is returned if no fit parameters were defined.

get_fitparams_array(fitparam_values)

Creates a numpy record ndarray holding the fit parameters names as key and their value for each source. The returned array is (1,)-shaped since there is only one source defined for this mapper class.

Parameters:: fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
Returns:: fitparams_arr ((1,)-shaped numpy record ndarray | None) – The numpy record ndarray holding the fit parameter names as keys and their value for the one single source. None is returned if no fit parameters were defined.

class skyllh.core.parameters.MultiSourceFitParameterMapper(sources)

Bases: SourceFitParameterMapper

This class provides the functionality to map the global fit parameters to the source fit parameters of the sources. Sometimes it’s necessary to define a global fit parameter, which relates to a source model fit parameter for a set of sources, while another global fit parameter relates to the same source model fit parameter, but for another set of sources.

At construction time this manager takes the collection of sources. Each source gets an index, which is defined as the position of the source within the collection.

Constructs a new source fit parameter mapper for multiple sources.

Parameters:: sources (sequence of SourceModel) – The sequence of SourceModel instances defining the list of sources.

property sources: The SourceCollection defining the sources.

property N_sources: (read-only) The number of sources.

def_fit_parameter(fitparam, src_param_name=None, sources=None)

Defines a new fit parameter that maps to a given source parameter for a list of sources. If no list of sources is given, it maps to all sources.

Parameters:

fitparam (FitParameter) – The FitParameter instance defining the fit parameter.
src_param_name (str | None) – The name of the source parameter. It must match the name of a source model property. If set to None (default) the name of the fit parameter will be used.
sources (SourceCollection | None) – The instance of SourceCollection with the sources for which the fit parameter applies. If None (the default) is specified, the fit parameter will apply to all sources.

get_src_fitparams(fitparam_values, src_idx)

Constructs a dictionary with the source parameters that are beeing fitted. As values the given global fit parameter values will be used. Hence, this method translates the global fit parameter values into the source parameters.

Parameters:

fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
src_idx (int) – The index of the source for which the parameters should get retieved.

Returns:

src_fitparams (dict) – The dictionary holding the translated source parameters that are beeing fitted.

get_fitparams_array(fitparam_values)

Creates a numpy record ndarray holding the fit parameters names as key and their value for each source. The returned array is (N_sources,)-shaped.

Parameters:: fitparam_values (1D ndarray) – The array holding the current global fit parameter values.
Returns:: fitparams_arr ((N_sources,)-shaped numpy record ndarray | None) – The numpy record ndarray holding the unique source fit parameter names as keys and their value for each source per row. None is returned if no fit parameters were defined.

skyllh.core.pdf module

class skyllh.core.pdf.PDFAxis(name, vmin, vmax)

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)

Bases: ObjectCollection

This class describes the set of PDFAxis objects defining the dimensionality of a PDF.

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) – The type of the objects, which can be added to the collection.

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.

property axis_name_list: (read-only) The list of the names of all the axes of this PDFAxes instance.

get_axis(name)

Retrieves the PDFAxis object with the given name.

Parameters:: name (str | int) – The name of the axis to retrieve. If an integer is given, it specifies the index of the axis.
Returns:: axis (PDFAxis) – The PDFAxis object.
Raises:: KeyError – If the axis could not be found.

has_axis(name)

Checks if an axis of the given name is present in this PDFAxes instance.

Parameters:: name (str) – The name of this axis.
Returns:: check (bool) – True, if this Axis object has an axis of the given name, False otherwise.

is_same_as(axes)

Checks if this PDFAxes object has the same axes and range then the given PDFAxes object.

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(param_set=None, **kwargs)

Bases: object

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 :math::`f(

ec{x}| ec{p})`, where :math::` ec{x}` is the

event data and :math::`

ec{p}` is the set of parameters the PDF is given: for.

Creates a new PDF instance.

Parameters:: param_set (Parameter instance | sequence of Parameter instances |) – ParameterSet instance | 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 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.

assert_is_valid_for_trial_data(tdm): 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.

abstract get_prob(tdm, params=None, tl=None)

This abstract method is supposed to calculate the probability density for the specified events given the specified parameter values.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance holding the data events for which the probability should be calculated for. What data fields are required is defined by the derived PDF class and depends on the application.
params (dict | None) – The dictionary containing the parameter names and values for which the probability should get calculated. This can be Ǹone for PDFs that do not depend on any parameters.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

prob ((N_events,)-shaped numpy ndarray) – The 1D numpy ndarray with the probability density for each event.
grads ((N_fitparams,N_events)-shaped ndarray | None) – The 2D numpy ndarray holding the gradients of the PDF w.r.t. each fit parameter for each event. The order of the gradients is the same as the order of floating parameters specified through the param_set property. It is None, if this PDF does not depend on any parameters.

class skyllh.core.pdf.PDFProduct(pdf1, pdf2)

Bases: PDF

The PDFProduct class represents the product of two PDF instances. 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 op pdf2.
pdf2 (instance of PDF) – The right-hand-side PDF in the operation pdf1 op pdf2.

property pdf1: The left-hand-side PDF in the operation pdf1 op pdf2. It must be an instance of PDF.

property pdf2: The right-hand-side PDF in the operation pdf1 op pdf2. It must be an instance of PDF.

assert_is_valid_for_trial_data(tdm)

Calls the assert_is_valid_for_trial_data method of pdf1 and pdf2.

Parameters:: tdm (TrialDataManager instance) – The TrialDataManager instance that should be used to get the trial data from.
Raises:: ValueError – If this PDF does not cover the trial data.

get_prob(tdm, params=None, tl=None)

Calculates the probability density for the trial events given the specified parameters by calling the get_prob 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 (dict | None) – The dictionary containing the parameter names and values for which the probability should get calculated.
tl (TimeLord instance | None) – The optional TimeLord instance to use for measuring timing information.

Returns:

prob ((N_events,)-shaped numpy ndarray) – The 1D numpy ndarray with the probability for each trial event.
grads ((N_fitparams,N_events)-shaped numpy ndarray) – The gradients of the PDF product w.r.t. the fit parameter of this PDFProduct instance.

class skyllh.core.pdf.SignalPDFProduct(pdf1, pdf2)

Bases: PDFProduct, IsSignalPDF

This class provides a signal PDF that is the product of two signal PDF instances.

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 op pdf2.
pdf2 (instance of PDF) – The right-hand-side PDF in the operation pdf1 op pdf2.

class skyllh.core.pdf.BackgroundPDFProduct(pdf1, pdf2)

Bases: PDFProduct, IsBackgroundPDF

This class provides a background PDF that is the product of two background PDF instances.

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 op pdf2.
pdf2 (instance of PDF) – The right-hand-side PDF in the operation pdf1 op pdf2.

class skyllh.core.pdf.SpatialPDF(ra_range, dec_range, *args, **kwargs)

Bases: PDF

This is the abstract base class for a spatial PDF model. A spatial PDF has two axes, right-ascention (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-ascention range this PDF covers.
dec_range (2-element tuple) – The tuple specifying the declination range this PDF covers.

assert_is_valid_for_exp_data(data_exp)

Checks if this spatial PDF is valid for all the given experimental data. It checks if all the data is within the right-ascention and declination range.

Parameters:

data_exp (numpy record ndarray) –

The array holding the experimental data. The following data fields must exist:

’ra’float
The right-ascention of the data event.
’dec’float
The declination of the data event.

Raises:

ValueError – If some of the data is outside the right-ascention or declination range.

class skyllh.core.pdf.EnergyPDF(*args, **kwargs)

Bases: PDF

This is the abstract base class for an energy PDF model.

Creates a new PDF instance.

Parameters:: param_set (Parameter instance | sequence of Parameter instances |) – ParameterSet instance | 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(*args, **kwargs)

Bases: PDF

This is the abstract base class for a time PDF model.

Creates a new PDF instance.

Parameters:: param_set (Parameter instance | sequence of Parameter instances |) – ParameterSet instance | 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.MultiDimGridPDF(axis_binnings, path_to_pdf_splinetable=None, pdf_grid_data=None, norm_factor_func=None)

Bases: PDF

This class provides a multi-dimensional PDF 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. The grid data is interpolated with a scipy.interpolate.RegularGridInterpolator instance. As grid points the bin edges of the axis binning definitions are used.

Parameters:

axis_binnings (BinningDefinition | sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance 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. The spline table contains a pre-computed fit to pdf_grid_data.
pdf_grid_data (n-dimensional 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.
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), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the event data for which to calculate the PDF values, and params is a dictionary with the current parameter names and values.

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 norm_factor_func: The function that calculates the possible required normalization factor. The call signature of this function must be __call__(pdf, tdm, fitparams), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the events for which to calculate the PDF values, and fitparams is a dictionary with the current fit parameter names and values. This property can be set to None. In that case a unity returning function is used.

assert_is_valid_for_trial_data(tdm)

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 (TrialDataManager instance) – The instance of TrialDataManager that holds the data which is going to be evaluated.
Raises:: ValueError – If any of the evaluation data is out of its axis range.

get_prob_with_eventdata(tdm, params, eventdata, tl=None)

Calculates the probability for the trial events given the specified parameters. This method has the additional argument eventdata which must be a 2d ndarray containing the trial event data in the correct order for the evaluation of the RegularGridInterpolator or photospline table instance. This method is usefull when PDF values for the same trial data need to get evaluated.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance holding the trial event data for which the PDF values should get calculated.
params (dict | None) – The dictionary containing the parameters the probability should get calculated for. By definition, this PDF does not depend on any parameters.
eventdata (2D (N_events,V)-shaped ndarray) – The 2D numpy ndarray holding the V data attributes for each event needed for the evaluation of the PDF.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

prob ((N_events,)-shaped numpy ndarray) – The 1D numpy ndarray with the probability for each event.

get_prob(tdm, params=None, tl=None)

Calculates the probability for the trial events given the specified parameters.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance holding the trial event data for which the PDF values should get calculated.
params (dict | None) – The dictionary containing the parameter names and values the probability should get calculated for. Since this PDF does not depend on any parameters, this could be None.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

prob ((N_events,)-shaped numpy ndarray) – The 1D numpy ndarray with the probability for each event.
grads (None) – Because this PDF does not depend on any parameters, no gradients w.r.t. the parameters are returned.

class skyllh.core.pdf.NDPhotosplinePDF(axis_binnings, param_set, path_to_pdf_splinefit, norm_factor_func=None)

Bases: PDF

This class provides a multi-dimensional PDF created from a n-dimensional photospline fit. The photospline package is used to evaluate the PDF fit.

Creates a new PDF instance for a n-dimensional photospline PDF fit.

Parameters:

axis_binnings (BinningDefinition | sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.
param_set (Parameter | ParameterSet) – The Parameter instance or ParameterSet instance defining the parameters of this PDF. The ParameterSet holds the information which parameters are fixed and which are floating (i.e. fitted).
path_to_pdf_splinefit (str) – The path to the file containing the photospline fit.
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), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the event data for which to calculate the PDF values, and params is a dictionary with the current parameter names and values.

property norm_factor_func: The function that calculates the possible required normalization factor. The call signature of this function must be __call__(pdf, tdm, fitparams), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the events for which to calculate the PDF values, and fitparams is a dictionary with the current fit parameter names and values. This property can be set to None. In that case a unity returning function is used.

assert_is_valid_for_trial_data(tdm)

Checks if the PDF is valid for all values of the given trial data. The trial data values must be within the ranges of the PDF axes.

Parameters:: tdm (TrialDataManager instance) – The instance of TrialDataManager that holds the trial data which is going to be evaluated.
Raises:: ValueError – If any of the trial data is out of its axis range.

get_prob(tdm, params=None, tl=None)

Calculates the probability for the trial events given the specified parameters.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance holding the trial event data for which the PDF values should get calculated.
params (dict | None) – The dictionary containing the parameter names and values the probability should get calculated for.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

prob ((N_events,)-shaped numpy ndarray) – The 1D numpy ndarray with the probability for each event.
grads ((N_fitparams,N_events)-shaped ndarray | None) – The 2D numpy ndarray holding the gradients of the PDF w.r.t. each fit parameter for each event. The order of the gradients is the same as the order of floating parameters specified through the param_set property. It is None, if this PDF does not depend on any parameters.

class skyllh.core.pdf.PDFSet(pdf_type, fitparams_grid_set, *args, **kwargs)

Bases: object

This class describes a set of PDF objects which are related to each other via different values of a set of fit parameters. A signal PDF usually consists of multiple same-kind PDFs for different signal fit parameters. In general background PDFs could have fit parameters, too.

This class has the fitparams_grid_set property holding the set of fit parameter grids. Also it holds a dictionary with the PDFs for the different sets of fit parameter values. The type of the PDF objects is defined through the pdf_type property. PDF objects of type pdf_type can be added via the add_pdf method and retrieved via the get_pdf method.

Constructor method. Gets called when the an instance of a class is created which derives from this PDFSet class.

Parameters:

pdf_type (type) – The PDF class that can be added to the set.
fitparams_grid_set (ParameterGridSet | ParameterGrid) – The ParameterGridSet with the fit parameter grids defining the descrete fit parameter values for which the PDFs of this PDF set are made for.

property pdf_type: (read-only) The PDF type which can be added to the PDF set.

property fitparams_grid_set: DEPRECATED (Use param_grid_set instead!) The ParameterGridSet object defining the value grids of the different fit parameters.

property param_grid_set

property gridfitparams_list: (read-only) The list of dictionaries of all the fit parameter permutations on the grid.

property pdf_keys: (read-only) The list of stored PDF object keys.

property pdf_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.

items(): Returns the list of 2-element tuples for the PDF stored in this PDFSet object.

add_pdf(pdf, gridfitparams)

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 (pdf_type) – The object derived from pdf_type that should be added.
gridfitparams (dict) – The dictionary with the grid fit 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(gridfitparams)

Retrieves the PDF object for the given set of fit parameters.

Parameters:: gridfitparams (dict | int) – The dictionary with the grid fit parameters for which the PDF object should get retrieved. If an integer is given, it is assumed to be the PDF key.
Returns:: pdf (pdf_type) – The pdf_type object for the given parameters.
Raises:: KeyError – If no PDF object was created for the given set of parameters.

class skyllh.core.pdf.MultiDimGridPDFSet(param_set, param_grid_set, gridparams_pdfs, interpolmethod=None, pdf_type=<class 'skyllh.core.pdf.MultiDimGridPDF'>, **kwargs)

Bases: PDF, PDFSet

Creates a new MultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for each point of a parameter grid set.

Parameters:

param_set (Parameter instance | sequence of Parameter instances |) – ParameterSet instance The set of parameters defining the model 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.
interpolmethod (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.
pdf_type (type) – The PDF class that can be added to the set.

property interpolmethod: The class derived from GridManifoldInterpolationMethod implementing the interpolation of the PDF grid manifold.

assert_is_valid_for_trial_data(tdm): Checks if this PDF set is valid for all the given trial data. Since the PDFs have the same axes, we just need to check the first PDFs.

get_prob(tdm, params, tl=None)

Calculates the probability density for each event, given the given parameter values.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance that will be used to get the data from the trial events.
params (dict) – The dictionary holding the parameter names and values for which the probability should get calculated. Because this PDF is a PDFSet, there should be at least one parameter.
tl (TimeLord instance | None) – The optional TimeLord instance to use for measuring timing information.

Returns:

prob ((N_events,)-shaped 1D ndarray) – The probability values for each event.
grads ((N_fitparams,N_events)-shaped 2D ndarray) – The PDF gradients w.r.t. the PDF fit parameters for each event.

class skyllh.core.pdf.MappedMultiDimGridPDFSet(param_grid_set, gridparams_pdfs, src_hypo_group_manager, pdf_type=<class 'skyllh.core.pdf.MultiDimGridPDF'>, **kwargs)

Bases: PDF, PDFSet

Creates a new MappedMultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for each point of a parameter grid set.

Parameters:

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.
src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of SourceHypoGroupManager that defines the list of sources, i.e. the list of SourceModel instances and flux models.
pdf_type (type) – The PDF class that can be added to the set.

property fluxmodel_to_source_mapping: The fluxmodel to source indices mapping list used for MappedMultiDimGridPDFSet evaluation to get the corresponding KDE PDF.

assert_is_valid_for_trial_data(tdm): Checks if this PDF set is valid for all the given trial data. Since the PDFs have the same axes, we just need to check the first PDFs.

get_prob(tdm, params, tl=None)

Calculates the probability density for each event, given the given parameter values.

Parameters:

tdm (TrialDataManager instance) – The TrialDataManager instance that will be used to get the data from the trial events.
params (dict) – The dictionary holding the parameter names and values for which the probability should get calculated. Because this PDF is a PDFSet, there should be at least one parameter.
tl (TimeLord instance | None) – The optional TimeLord instance to use for measuring timing information.

Returns:

prob ((N_events,)-shaped 1D ndarray) – The probability values for each event.
grads ((N_fitparams,N_events)-shaped 2D ndarray) – The PDF gradients w.r.t. the PDF fit parameters for each event.

skyllh.core.pdfratio module

class skyllh.core.pdfratio.PDFRatio(pdf_type, *args, **kwargs)

Bases: object

Abstract base class for a PDF ratio class. It defines the interface of a PDF ratio class.

Constructor for a PDF ratio class.

Parameters:: pdf_type (type) – The Python type of the PDF object the PDF ratio is made for.

property n_fitparams: (read-only) The number of fit parameters the PDF ratio depends on. This is the sum of signal and background fit parameters. At the moment only signal fit parameters are supported, so this property is equivalent to the n_signal_fitparams property. But this might change in the future.

property fitparam_names: (read-only) The list of fit parameter names this PDF ratio is a function of. This is the superset of signal and background fit parameter names. At the moment only signal fit parameters are supported, so this property is equivalent to the signal_fitparam_names property. But this might change in the future.

property n_signal_fitparams: (read-only) The number of signal fit parameters the PDF ratio depends on.

property signal_fitparam_names: (read-only) The list of signal fit parameter names this PDF ratio is a function of.

property pdf_type: (read-only) The Python type of the PDF object for which the PDF ratio is made for.

abstract get_ratio(tdm, params=None, tl=None)

Retrieves the PDF ratio value for each given trial data event, given the given set of fit parameters. This method is called during the likelihood maximization process.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
params (dict | None) – The dictionary with the parameter name-value pairs. It can be None, if the PDF ratio does not depend on any parameters.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios ((N_events,)-shaped 1d numpy ndarray of float) – The PDF ratio value for each trial event.

abstract get_gradient(tdm, params, fitparam_name)

Retrieves the PDF ratio gradient for the parameter fitparam_name for each given trial event, given the given set of fit parameters. This method is called during the likelihood maximization process.

Parameters:

tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial data events for which the PDF ratio values should get calculated.
params (dict) – The dictionary with the parameter names and values.
fitparam_name (str) – The name of the fit parameter for which the gradient should get calculated.

Returns:

gradient ((N_events,)-shaped 1d numpy ndarray of float) – The PDF ratio gradient value for each trial event.

class skyllh.core.pdfratio.SingleSourcePDFRatioArrayArithmetic(pdfratios, fitparams)

Bases: object

This class provides arithmetic methods for arrays of PDFRatio instances. It has methods to calculate the product of the ratio values for a given set of PDFRatio objects. This class assumes a single source.

The rational is that in the calculation of the derivates of the log-likelihood-ratio function for a given fit parameter, the product of the PDF ratio values of the PDF ratio objects which do not depend on that fit parameter is needed.

Constructs a PDFRatio array arithmetic object assuming a single source.

Parameters:

pdfratios (list of PDFRatio) – The list of PDFRatio instances.
fitparams (list of FitParameter) – The list of fit parameters. The order must match the fit parameter order of the minimizer.

property pdfratio_list: The list of PDFRatio objects.

property fitparam_list: The list of FitParameter instances.

initialize_for_new_trial(tdm)

Initializes the PDFRatio array arithmetic for a new trial. For a new trial the data events change, hence we need to recompute the PDF ratio values of the fit parameter independent PDFRatio instances.

Parameters:: tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data for that this PDFRatioArrayArithmetic instance should get initialized.

get_pdfratio(idx)

Returns the PDFRatio instance that corresponds to the given fit parameter index.

Parameters:: fitparam_idx (int) – The index of the fit parameter.
Returns:: pdfratio (PDFRatio) – The PDFRatio instance which corresponds to the given fit parameter index.

calculate_pdfratio_values(tdm, fitparams, tl=None)

Calculates the PDF ratio values for the PDF ratio objects which depend on fit parameters.

Parameters:

tdm (instance of TrialDataManager) – The instance of TrialDataManager that holds the trial event data for which the PDF ratio values should get calculated.
fitparams (dict) – The dictionary with the fit parameter name-value pairs.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

get_ratio_product(excluded_idx=None)

Calculates the product of the of the PDF ratio values of each event, but excludes the PDF ratio values that correspond to the given excluded fit parameter index. This is useful for calculating the derivates of the log-likelihood ratio function.

Parameters:: excluded_fitparam_idx (int | None) – The index of the fit parameter whose PDF ratio values should get excluded from the product. If None, the product over all PDF ratio values will be computed.
Returns:: product (1D (N_events,)-shaped ndarray) – The product of the PDF ratio values for each event.

class skyllh.core.pdfratio.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 fill_ratios(ratios, sig_prob_h, bkg_prob_h, sig_mask_mc_covered, sig_mask_mc_covered_zero_physics, bkg_mask_mc_covered, bkg_mask_mc_covered_zero_physics)

The fill_ratios method is supposed to fill the ratio bins (array) with the signal / background division 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_prob_h (ndarray of float) – The multi-dimensional array (histogram) holding the signal probabilities.
bkg_prob_h (ndarray of float) – The multi-dimensional array (histogram) holding the background probabilities.
sig_mask_mc_covered (ndarray of bool) – The mask array indicating which array elements of sig_prob_h have monte-carlo coverage.
sig_mask_mc_covered_zero_physics (ndarray of bool) – The mask array indicating which array elements of sig_prob_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_prob_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_prob_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.Skylab2SkylabPDFRatioFillMethod

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!

fill_ratios(ratio, sig_prob_h, bkg_prob_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.

class skyllh.core.pdfratio.MostSignalLikePDFRatioFillMethod(signallike_percentile=99.0)

Bases: PDFRatioFillMethod

PDF ratio fill method to set the PDF ratio to the most signal like PDF ratio for bins, where there is signal MC coverage but no background (MC) 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.

fill_ratios(ratio, sig_prob_h, bkg_prob_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.

class skyllh.core.pdfratio.MinBackgroundLikePDFRatioFillMethod

Bases: PDFRatioFillMethod

PDF ratio fill method to set the PDF ratio to the minimal background like value for bins, where there is signal MC coverage but no background (MC) 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.

fill_ratios(ratio, sig_prob_h, bkg_prob_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.

class skyllh.core.pdfratio.SigOverBkgPDFRatio(sig_pdf, bkg_pdf, pdf_type=None, same_axes=True, zero_bkg_ratio_value=1.0, *args, **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.
pdf_type (type | None) – The python type of the PDF object for which the PDF ratio is for. If set to None, the default class PDF will be used.
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.

get_ratio(tdm, params=None, 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.
params (dict | None) – The dictionary holding the parameter names and values for which the probability ratio should get calculated. This can be None, if the signal and background PDFs do not depend on any parameters.
tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratios ((N_events)-shaped numpy ndarray) – The ndarray holding the probability ratio for each event (and each source). The dimensionality of the returned ndarray depends on the dimensionality of the probability ndarray returned by the get_prob method of the signal PDF object.

get_gradient(tdm, params, fitparam_name)

Retrieves the gradient of the PDF ratio w.r.t. the given fit parameter. This method must be called after the get_ratio method.

Parameters:

tdm (TrialDataManager instance) – The instance of TrialDataManager that should be used to get the trial data from.
params (dict) – The dictionary with the parameter names and values.
fitparam_name (str) – The name of the fit parameter for which the gradient should get calculated.

Returns:

gradient ((N_events,)-shaped 1d numpy ndarray of float) – The PDF ratio gradient value for each trial event.

class skyllh.core.pdfratio.SpatialSigOverBkgPDFRatio(sig_pdf, bkg_pdf, *args, **kwargs)

Bases: SigOverBkgPDFRatio

This class implements a signal-over-background PDF ratio for spatial PDFs. It takes a signal PDF of type SpatialPDF and a background PDF of type SpatialPDF and calculates the PDF ratio.

Creates a new signal-over-background PDF ratio instance for spatial PDFs.

Parameters:

sig_pdf (class instance derived from SpatialPDF, IsSignalPDF) – The instance of the spatial signal PDF.
bkg_pdf (class instance derived from SpatialPDF, IsBackgroundPDF) – The instance of the spatial background PDF.

class skyllh.core.pdfratio.SigSetOverBkgPDFRatio(pdf_type, signalpdfset, backgroundpdf, interpolmethod=None, *args, **kwargs)

Bases: PDFRatio

Class for a PDF ratio class that takes a PDFSet of PDF type pdf_type as signal PDF and a PDF of type pdf_type as background PDF. The signal PDF depends on signal fit parameters and a interpolation method defines how the PDF ratio gets interpolated between the fit parameter values.

Constructor called by creating an instance of a class which is derived from this PDFRatio class.

Parameters:

pdf_type (type) – The Python type of the PDF object for which the PDF ratio is for.
signalpdfset (class instance derived from PDFSet (for PDF type) – pdf_type), and IsSignalPDF The PDF set, which provides signal PDFs for a set of discrete signal fit parameters.
backgroundpdf (class instance derived from pdf_type, and) – IsBackgroundPDF The background PDF instance.
interpolmethod (class of GridManifoldInterpolationMethod | None) – The class implementing the fit parameter interpolation method for the PDF ratio manifold grid. If set to None (default), the Parabola1DGridManifoldInterpolationMethod will be used for 1-dimensional parameter manifolds.

property backgroundpdf: The background PDF object, derived from pdf_type and IsBackgroundPDF.

property signalpdfset: The signal PDFSet object for pdf_type PDF objects.

property interpolmethod: The class derived from GridManifoldInterpolationMethod implementing the interpolation of the fit parameter manifold.

convert_signal_fitparam_name_into_index(signal_fitparam_name)

Converts the given signal fit parameter name into the parameter index, i.e. the position of parameter in the signal parameter grid set.

Parameters:: signal_fitparam_name (str) – The name of the signal fit parameter.
Returns:: index (int) – The index of the signal fit parameter.

skyllh.core.progressbar module

class skyllh.core.progressbar.ProgressBar(maxval, startval=0, parent=None)

Bases: object

This class implements a hierarchical progress bar that can serve as a parent for child progress bars to display different levels of processing.

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) – The parent instance of ProgressBar if this progress bar is a sub progress bar.

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 parent: The parent ProgressBar instance of this progress bar, or None if no parent exist.

property progress: (read-only) The progress of this progress bar as a number between 0 and 1.

property gets_shown: (read-only) Flag if the progress bar gets shown. This is True if the program is run in an interactive session, False otherwise.

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_bar(pbar): Removes the given progress bar instance from the list of running sub progress bars of this progress bar.

get_progress_list(): Retrieves the list of progress values of all the sub progress bars and this progress. The value of this progress bar is the last value.

rerender(): Rerenders this progress bar on the display, but only if the rendered progress bar string changed.

trigger_rerendering(): Triggers a rerendering of the most top progress bar.

start()

Starts the progress bar by taking the start time and setting the progress value to the start value. If this progress bar has a parent, it adds itself to the parent’s list of running sub progress bars. Otherwise it will render and print this progress bar for the first time.

Returns:: self (instance of ProgressBar) – The instance of this ProgressBar.

finish(): Finishes this progress bar by setting the current progress value to its max value. If this progress bar has a parent, it triggers a rerendering of the parent and then removes itself from the parent’s list of running sub progress bars. Otherwise it will render and print this progress bar for the last time.

update(val)

Updates the progress value. If this progress bar has no parent progress bar, a rerendering of this progress bar is made.

Parameters:: val (int) – The new current progress value.

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.

skyllh.core.py module

class skyllh.core.py.PyQualifier

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

Bases: PyQualifier

This class defines a PyQualifier for constant Python objects.

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.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 as a sequence!

Return True:: If the given object is a sequence.
Return False:: If the given object is a str object 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 (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.

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): 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.

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) – The type of the objects, which can be added to the collection.

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 to this object collection.

Parameters:: obj (obj_type instance | 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 to this object collection.

Parameters:: obj (obj_type instance | 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)

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.

__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.

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)

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.

skyllh.core.scrambling module

class skyllh.core.scrambling.DataScramblingMethod

Bases: object

Base class (type) for implementing a data scrambling method.

abstract scramble(rss, 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 (RandomStateService) – The random state service providing the random number generator (RNG).
data (instance of DataFieldRecordArray) – The DataFieldRecordArray containing the to be scrambled data.

Returns:

data (DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.UniformRAScramblingMethod(ra_range=None)

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, data)

Scrambles the given data uniformly in right-ascention.

Parameters:

rss (RandomStateService) – The random state service providing the random number generator (RNG).
data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

data (DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.TimeScramblingMethod(timegen, hor_to_equ_transform)

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 (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, 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 (RandomStateService) – The random state service providing the random number generator (RNG).
data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

data (DataFieldRecordArray) – The given DataFieldRecordArray holding the scrambled data.

class skyllh.core.scrambling.DataScrambler(method)

Bases: object

Creates a data scrambler instance with a given defined scrambling method.

Parameters:: method (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, 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 (RandomStateService) – The random state service providing the random number generator (RNG).
data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance 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 (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.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)

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, src_hypo_group)

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.
src_hypo_group (SourceHypoGroup instance) – The source hypothesis group, which defines the list of sources, and their flux model.

Returns:

flux_list (list of 2-element tuples) – The list of 2-element tuples with one tuple for each source. Each tuple must be made of two 1D ndarrays of size N_selected_signal_events, where the first array contains the global MC data event indices and the second array the flux of each selected signal 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_idx’int
  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(src_hypo_group_manager, dataset_list, data_list)

Bases: object

This is the general signal generator class. 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. In case of multiple sources the handling here is very suboptimal. Therefore the MultiSourceSignalGenerator should be used instead!

Constructs a new signal generator instance.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance defining the source groups with their spectra.
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.

property src_hypo_group_manager: The SourceHypoGroupManager instance defining the source groups with their spectra.

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.

change_source_hypo_group_manager(src_hypo_group_manager): 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 1/(GeV cm^2 s).

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)

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) – 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.

Returns:

n_signal (int) – The number of generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instancs 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.MultiSourceSignalGenerator(src_hypo_group_manager, dataset_list, data_list)

Bases: SignalGenerator

More optimal signal generator for multiple sources.

Constructs a new signal generator instance.

Parameters:

src_hypo_group_manager (SourceHypoGroupManager instance) – The SourceHypoGroupManager instance defining the source groups with their spectra.
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.

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, **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

1/(2*pi*sigma^2) * exp(-1/2*(r / 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-ascention 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-ascention 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.

get_prob(tdm, fitparams=None, tl=None)

Calculates the spatial signal probability of each event for all given sources.

Parameters:

tdm (instance of TrialDataManager) –
The TrialDataManager instance holding the trial event data for which to calculate the PDF values. The following data fields need to be present:

’src_array’numpy record ndarray
The numpy record ndarray with the following data fields:

ra: float
The right-ascention of the point-like source.

dec: float
The declination of the point-like source.

’ra’float
The right-ascention in radian of the data event.

’dec’float
The declination in radian of the data event.

’ang_err’: float
The reconstruction uncertainty in radian of the data event.
fitparams (None) – Unused interface argument.
tl (TimeLord instance | None) – The optional TimeLord instance to use for measuring timing information.

Returns:

prob ((N_sources,N_events) shaped 2D ndarray) – The ndarray holding the spatial signal probability on the sphere for each source and event.

class skyllh.core.signalpdf.SignalTimePDF(livetime, time_profile)

Bases: TimePDF, IsSignalPDF

This class provides a time PDF class for a signal source. It consists of a Livetime instance and a TimeProfileModel 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 profile of the source.

Parameters:

livetime (Livetime instance) – An instance of Livetime, which provides the detector live-time information.
time_profile (TimeProfileModel instance) – The time profile of the source.

property livetime: The instance of Livetime, which provides the detector live-time information.

property time_profile: The instance of TimeProfileModel providing the (assumed) physical time profile of the source.

assert_is_valid_for_exp_data(data_exp)

Checks if the time PDF is valid for all the given experimental data. It checks if the time of all events is within the defined time axis of the PDF.

Parameters:

data_exp (numpy record ndarray) –

The array holding the experimental data. The following data fields must exist:

’time’float
The MJD time of the data event.

Raises:

ValueError – If some of the data is outside the time range of the PDF.

get_prob(tdm, fitparams)

Calculates the signal time probability of each event for the given set of signal time fit parameter values.

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.
fitparams (dict) – The dictionary holding the signal time parameter values for which the signal time probability should be calculated.

Returns:

prob (array of float) – The (N,)-shaped ndarray holding the probability for each event.

class skyllh.core.signalpdf.SignalMultiDimGridPDF(axis_binnings, path_to_pdf_splinetable=None, pdf_grid_data=None, norm_factor_func=None)

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 signal PDF instance for a multi-dimensional PDF given as 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.

Parameters:

axis_binnings (sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.
path_to_pdf_splinetable (str) – The path to the file containing the spline table. The spline table contains a pre-computed fit to pdf_grid_data.
pdf_grid_data (n-dimensional numpy ndarray) – 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.
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, events, fitparams), where pdf is this PDF instance, events is a numpy record ndarray holding the events for which to calculate the PDF values, and fitparams is a dictionary with the current fit parameter names and values.

class skyllh.core.signalpdf.SignalMultiDimGridPDFSet(param_set, param_grid_set, gridparams_pdfs, interpolmethod=None, **kwargs)

Bases: MultiDimGridPDFSet, IsSignalPDF

This class extends the MultiDimGridPDFSet PDF class to be a signal PDF. See the documentation of the skyllh.core.pdf.MultiDimGridPDFSet class for what this PDF provides.

Creates a new SignalMultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for each point of a parameter grid set.

Parameters:

param_set (Parameter instance | sequence of Parameter instances |) – ParameterSet instance The set of parameters defining the model 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.
interpolmethod (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.

class skyllh.core.signalpdf.SignalMappedMultiDimGridPDFSet(param_grid_set, gridparams_pdfs, interpolmethod=None, **kwargs)

Bases: MappedMultiDimGridPDFSet, IsSignalPDF

This class extends the MappedMultiDimGridPDFSet PDF class to be a signal PDF. See the documentation of the skyllh.core.pdf.MappedMultiDimGridPDFSet class for what this PDF provides.

Creates a new SignalMappedMultiDimGridPDFSet instance, which holds a set of MultiDimGridPDF instances, one for each point of a parameter grid set.

Parameters:

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.

class skyllh.core.signalpdf.SignalNDPhotosplinePDF(axis_binnings, param_set, path_to_pdf_splinefit, norm_factor_func=None)

Bases: NDPhotosplinePDF, IsSignalPDF

This class provides a multi-dimensional signal PDF created from a n-dimensional photospline fit. The photospline package is used to evaluate the PDF fit.

Creates a new signal PDF instance for a n-dimensional photospline PDF fit.

Parameters:

axis_binnings (BinningDefinition | sequence of BinningDefinition) – The sequence of BinningDefinition instances defining the binning of the PDF axes. The name of each BinningDefinition instance defines the event field name that should be used for querying the PDF.
param_set (Parameter | ParameterSet) – The Parameter instance or ParameterSet instance defining the parameters of this PDF. The ParameterSet holds the information which parameters are fixed and which are floating (i.e. fitted).
path_to_pdf_splinefit (str) – The path to the file containing the photospline fit.
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), where pdf is this PDF instance, tdm is an instance of TrialDataManager holding the event data for which to calculate the PDF values, and params is a dictionary with the current parameter names and values.

skyllh.core.smoothing module

class skyllh.core.smoothing.HistSmoothingMethod

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

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)

Bases: HistSmoothingMethod

This class implements

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)

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)

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.

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)

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.

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_group module

class skyllh.core.source_hypo_group.SourceHypoGroup(sources, fluxmodel, detsigyield_implmethods, sig_gen_method=None, source_weights=None)

Bases: object

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 implementation 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_implmethods (sequence of DetSigYieldImplMethod instances) – The sequence of detector signal yield implementation method instances, which should be used to create the detector signal yield for the sources of this group. Each element is the detector signal yield implementation method for the particular dataset, if several datasets are used. If this list contains only one implementation method, 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.
source_weights (float | sequence of floats | None) – The sequence of relative source weights, normalized to 1.

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_implmethod_list: The list of DetSigYieldImplMethod instances, which should be used to create the detector signal yield for this group of sources. Each element is the detector signal yield implementation method for the particular dataset, if several datasets are used. If this list contains only one implementation method, 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 source_weights: The 1d array of relative source weights.

property n_sources: (read-only) The number of sources within this source hypothesis group.

skyllh.core.source_hypothesis module

The source_hypothesis module provides classes to define groups of source hypotheses. The SourceHypoGroupManager manages the groups of source hypotheses.

class skyllh.core.source_hypothesis.SourceHypoGroupManager(src_hypo_groups=None)

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 assign detector signal efficiency 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: The number of defined source hypothesis groups.

property src_hypo_group_list: (read-only) The list of source hypothesis groups, i.e. SourceHypoGroup instances.

add_source_hypo_group(sources, fluxmodel, detsigyield_implmethods, sig_gen_method=None)

Adds a source hypothesis group to the source hypothesis group manager. A source hypothesis group share sources of the same source model with the same flux model and hence the same detector signal yield and signal generation implementation 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_implmethods (sequence of DetSigYieldImplMethod instances) – The sequence of detector signal yield implementation method instances, which should be used to create the detector signal yield for the sources of the group. Each element is the detector signal yield implementation method for the particular dataset, if several datasets are used. If this list contains only one implementation method, 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_implmethod_list_by_src_idx(src_idx)

Retrieves the list of DetSigYieldImplMethod 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_implmethod_list (list of DetSigYieldImplMethod instances) – The list of DetSigYieldImplMethod instances that apply to the specified source.

get_fluxmodel_to_source_mapping()

Returns the list of tuples mapping fluxmodel to the source indices.

Returns:: fluxmodel_to_source_mapping (list of (hash, src_index_array) tuples) – The list that maps hash of the source hypothesis fluxmodel to the corresponding source indices array in the source hypothesis group.

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 (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 appropiate 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

Initializes 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.

Initializes 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_convertions=None, dtype_convertion_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_convertions (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_convertion_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 (DataFieldRecordArray) – The DataFieldRecordArray holding the loaded data.

Raises:

RuntimeError if a file does not exist. –

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.DataFieldRecordArray(data, keep_fields=None, dtype_convertions=None, dtype_convertion_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 numpy record ndarray.

Parameters:

data (numpy record ndarray | dict | DataFieldRecordArray | None) – The numpy record ndarray that needs to get transformed into the DataFieldRecordArray instance. Alternative a dictionary with field names as keys and numpy ndarrays as values can be provided. If an instance of DataFieldRecordArray is provided, the new DataFieldRecordArray gets constructed from the copy of the data of the provided DataFieldRecordArray instance. If set to None, the DataFieldRecordArray instance is initialized with no data and the length of the array is set to 0.
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_convertions (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_convertion_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 | DataFieldRecordArray) – The requested field data or a DataFieldRecordArray holding the requested selection of the entire data.

__setitem__(name, arr)

Implements data field value assigment. 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.

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 (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(convertions, except_fields=None)

Converts the data type of the data fields of this DataFieldRecordArray. This method can be used to compress the data.

Parameters:

convertions (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 (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(convertions, must_exist=False)

Renames the given fields of this array.

Parameters:

convertions (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

Bases: object

This is the abstract base class for a test statistic class.

Constructs the test-statistic function instance.

abstract evaluate(llhratio, log_lambda, fitparam_values, *args, **kwargs)

This method is supposed to evaluate the test-statistic function.

Parameters:

llhratio (LLHRatio instance) – The log-likelihood ratio function, which should be used for the test-statistic function.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values ((N_fitparams+1)-shaped 1D numpy ndarray) – The numpy ndarray holding the 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.TestStatisticWilks

Bases: TestStatistic

This class implements the standard Wilks theorem test-statistic function:

TS = 2 * sign(ns_best) * log( L(fitparam_best) / L(ns = 0) )

where the sign(ns_best) is negative for ns_best < 0, and positive otherwise.

Constructs the test-statistic function instance.

evaluate(llhratio, log_lambda, fitparam_values)

Evaluates this test-statistic function.

Parameters:

llhratio (LLHRatio instance) – The log-likelihood ratio function, which should be used for the test-statistic function.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values ((N_fitparams+1)-shaped 1D numpy ndarray) – The numpy ndarray holding the fit parameter values of the log-likelihood ratio function for the given log_lambda value. By definition, the first element is the value of ‘ns’.

Returns:

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

class skyllh.core.test_statistic.TestStatisticWilksZeroNsTaylor

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 * sign(ns_best) * log( L(fitparam_best) / L(ns = 0) )

for ns_best != 0, and

TS = 2 * a^2 / (4*b)

for ns_best == 0, with

a = d/dns ( L(fitparam_best) / L(ns = 0) )

being the derivative w.r.t. ns of the log-likelihood ratio function, and

b = d/dns ( a )

being its second derivative w.r.t. ns.

Constructs the test-statistic function instance.

evaluate(llhratio, log_lambda, fitparam_values, grads)

Evaluates this test-statistic function.

Parameters:

llhratio (LLHRatio instance) – The log-likelihood ratio function, which should be used for the test-statistic function.
log_lambda (float) – The value of the log-likelihood ratio function. Usually, this is its maximum.
fitparam_values ((N_fitparams+1)-shaped 1D numpy ndarray) – The numpy ndarray holding the fit parameter values of the log-likelihood ratio function for the given log_lambda value. By definition, the first element is the value of ‘ns’.
grads ((N_fitparams+1)-shaped 1D ndarray) – The ndarray holding the values of the first derivative of the log-likelihood ratio function w.r.t. each global fit parameter. By definition the first element is the first derivative w.r.t. the fit parameter ns.

Returns:

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

skyllh.core.times module

class skyllh.core.times.TimeGenerationMethod

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)

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)

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 (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)

Generates size amount of times by calling the generate_times method of the TimeGenerationMethod class.

Parameters:

rss (RandomStateService) – The random state service providing the random number generator (RNG).
size (int) – The number of time that should get generated.

Returns:

times (ndarray) – The 1d (size,)-shaped ndarray holding the generated times.

skyllh.core.timing module

class skyllh.core.timing.TaskRecord(name, tstart, tend)

Bases: object

Creates a new TaskRecord instance.

Parameters:

name (str) – The name of the task.
tstart (float | 1d ndarray of float) – The start time(s) of the task in seconds.
tend (float | 1d ndarray of float) – The end time(s) 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 (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 (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 (TimeLord instance) – 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.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, fitparam_names=None, dt=None)

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, src_hypo_group_manager, fitparams), where tdm is the TrialDataManager instance holding the event data, src_hypo_group_manager is the SourceHypoGroupManager instance, and fitparams is the dictionary with the current fit parameter names and values. If the data field depends solely on source parameters, the call signature must be __call__(tdm, src_hypo_group_manager) instead.
fitparam_names (sequence of str | None) – The sequence of str instances specifying the names of the 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.

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 values: (read-only) The calculated data values of the data field.

class skyllh.core.trialdata.TrialDataManager(index_field_name=None)

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 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 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.

change_source_hypo_group_manager(src_hypo_group_manager)

Recalculate the source data fields.

Parameters:: src_hypo_group_manager (instance of SourceHypoGroupManager) – The SourceHypoGroupManager manager that defines the groups of source hypotheses.

initialize_trial(src_hypo_group_manager, events, n_events=None, evt_sel_method=None, tl=None, retidxs=False)

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:

src_hypo_group_manager (SourceHypoGroupManager instance) – The instance of SourceHypoGroupManager that defines the source hypothesis groups.
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 (EventSelectionMethod | None) – The optional event selection method that should be used to select potential signal events.
tl (TimeLord | None) – The optional TimeLord instance that should be used for timing measurements.

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, src_hypo_group_manager, fitparams), where tdm is the TrialDataManager instance holding the event data, src_hypo_group_manager is the SourceHypoGroupManager instance, and fitparams is an unused interface argument.
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, fitparam_names=None, dt=None, pre_evt_sel=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, src_hypo_group_manager, fitparams), where tdm is the TrialDataManager instance holding the event data, src_hypo_group_manager is the SourceHypoGroupManager instance, and fitparams is the dictionary with the current fit parameter names and values.
fitparam_names (sequence of str | None) – The sequence of str instances specifying the names of the 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.

calculate_source_data_fields(src_hypo_group_manager)

Calculates the data values of the data fields that solely depend on source parameters.

Parameters:: src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.

calculate_pre_evt_sel_static_data_fields(src_hypo_group_manager)

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:: src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.

calculate_static_data_fields(src_hypo_group_manager)

Calculates the data values of the data fields that do not depend on any source or fit parameters.

Parameters:: src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.

calculate_fitparam_data_fields(src_hypo_group_manager, fitparams)

Calculates the data values of the data fields that depend on fit parameter values.

Parameters:

src_hypo_group_manager (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager, which defines the groups of source hypotheses.
fitparams (dict) – The dictionary holding the 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 record ndarray or in one of the additional defined data fields. Data from the raw events record ndarray is prefered.

Parameters:: name (str) – The name of the data field for which to retrieve the data.
Returns:: data (numpy ndarray) – The data of the requested data field.
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.

skyllh.core package

Subpackages

Submodules

skyllh.core.analysis module

skyllh.core.analysis_utils module

skyllh.core.background_generation module

skyllh.core.background_generator module

skyllh.core.backgroundpdf module

skyllh.core.binning module

skyllh.core.config module

skyllh.core.coords module

skyllh.core.dataset module

skyllh.core.debugging module

skyllh.core.detsigyield module

skyllh.core.display module

skyllh.core.interpolate module

skyllh.core.livetime module

skyllh.core.llhratio module

skyllh.core.math module

skyllh.core.minimizer module

skyllh.core.model module

skyllh.core.multiproc module

skyllh.core.optimize module

skyllh.core.parameters module

skyllh.core.pdf module

skyllh.core.pdfratio module

skyllh.core.progressbar module

skyllh.core.py module

skyllh.core.random module

skyllh.core.scrambling module

skyllh.core.session module

skyllh.core.signal_generation module

skyllh.core.signal_generator module

skyllh.core.signalpdf module

skyllh.core.smoothing module

skyllh.core.source_hypo_group module

skyllh.core.source_hypothesis module

skyllh.core.storage module

skyllh.core.test_statistic module

skyllh.core.times module

skyllh.core.timing module

skyllh.core.trialdata module