skyllh.i3 package

Subpackages

Submodules

skyllh.i3.background_generation module

class skyllh.i3.background_generation.FixedScrambledExpDataI3BkgGenMethod(data_scrambler, **kwargs)

Bases: BackgroundGenerationMethod

This class implements the background event generation method for the IceCube detector using scrambled experimental data as background hypothesis with a fixed number of background events equal to the number of events in the dataset. This background generation method is the one used in SkyLab.

Creates a new background generation method instance to generate background events from scrambled experimental data with a fixed number of events equal to the number of events in the dataset.

Parameters:

data_scrambler (instance of DataScrambler) – The DataScrambler instance to use to generate scrambled experimental data.

property data_scrambler

The DataScrambler instance that implements the data scrambling.

generate_events(rss, dataset, data, **kwargs)

Generates background events from the given data, by scrambling the experimental data. The number of events is equal to the size of the given dataset.

Parameters:

  • rss (instance of RandomStateService) – The instance of RandomStateService that should be used to generate random numbers from. It is used to scramble the experimental data.

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

Returns:

  • n_bkg (int) – The number of generated background events.

  • bkg_events (instance of DataFieldRecordArray) – The instance of DataFieldRecordArray holding the generated background events.

skyllh.i3.backgroundpdf module

class skyllh.i3.backgroundpdf.BackgroundI3SpatialPDF(data_sin_dec, data_weights, sin_dec_binning, spline_order_sin_dec, **kwargs)

Bases: SpatialPDF, UsesBinning, IsBackgroundPDF

This is the base class for all IceCube specific spatial background PDF models. IceCube spatial background PDFs depend solely on the zenith angle, and hence, on the declination of the event.

The IceCube spatial background PDF is modeled as a 1d spline function in sin(declination).

Creates a new IceCube spatial background PDF object.

Parameters:

  • data_sin_dec (1d ndarray) – The array holding the sin(dec) values of the events.

  • data_weights (1d ndarray) – The array holding the weight of each event used for histogramming.

  • sin_dec_binning (BinningDefinition) – The binning definition for the sin(declination) axis.

  • spline_order_sin_dec (int) – The order of the spline function for the logarithmic values of the spatial background PDF along the sin(dec) axis.

property spline_order_sin_dec

The order (int) of the logarithmic spline function, that splines the background PDF, along the sin(dec) axis.

add_events(events)

Add events to spatial background PDF object and recalculate logarithmic spline function.

Parameters:

events (numpy record ndarray) –

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

sin_decfloat

The sin(declination) value of the event.

reset()

Reset the logarithmic spline to the original function, which was calculated when the object was initialized.

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

Pre-cumputes the probability density values when new trial data is available.

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

Calculates the spatial background probability on the sphere of each event.

Parameters:

  • tdm (instance of TrialDataManager) –

    The TrialDataManager instance holding the trial event data for which to calculate the PDF values. The following data fields must exist:

    sin_decfloat

    The sin(declination) value of the event.

  • params_recarray (None) – Unused interface parameter.

  • tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

  • pd (instance of numpy ndarray) – The (N_events,)-shaped numpy ndarray holding the background probability density value for each event.

  • grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each global fit parameter. The background PDF does not depend on any global fit parameter, hence, this is an empty dictionary.

class skyllh.i3.backgroundpdf.DataBackgroundI3SpatialPDF(data_exp, sin_dec_binning, spline_order_sin_dec=2, **kwargs)

Bases: BackgroundI3SpatialPDF

This is the IceCube spatial background PDF, which gets constructed from experimental data.

Constructs a new IceCube spatial background PDF from experimental data.

Parameters:

  • data_exp (instance of DataFieldRecordArray) –

    The instance of DataFieldRecordArray holding the experimental data. The following data fields must exist:

    sin_decfloat

    The sin(declination) of the data event.

  • sin_dec_binning (BinningDefinition) – The binning definition for the sin(declination).

  • spline_order_sin_dec (int) – The order of the spline function for the logarithmic values of the spatial background PDF along the sin(dec) axis. The default is 2.

class skyllh.i3.backgroundpdf.MCBackgroundI3SpatialPDF(data_mc, physics_weight_field_names, sin_dec_binning, spline_order_sin_dec=2, **kwargs)

Bases: BackgroundI3SpatialPDF

This is the IceCube spatial background PDF, which gets constructed from monte-carlo data.

Constructs a new IceCube spatial background PDF from monte-carlo data.

Parameters:

  • data_mc (instance of DataFieldRecordArray) –

    The array holding the monte-carlo data. The following data fields must exist:

    sin_decfloat

    The sine of the reconstructed declination of the data event.

  • physics_weight_field_names (str | list of str) – The name or the list of names of the monte-carlo data fields, which should be used as event weights. If a list is given, the weight values of all the fields will be summed to construct the final event weight.

  • sin_dec_binning (BinningDefinition) – The binning definition for the sin(declination).

  • spline_order_sin_dec (int) – The order of the spline function for the logarithmic values of the spatial background PDF along the sin(dec) axis. The default is 2.

class skyllh.i3.backgroundpdf.DataBackgroundI3EnergyPDF(data_exp, log10_energy_binning, sin_dec_binning, smoothing_filter=None, **kwargs)

Bases: I3EnergyPDF, IsBackgroundPDF

This is the IceCube energy background PDF, which gets constructed from experimental data. This class is derived from I3EnergyPDF.

Constructs a new IceCube energy background PDF from experimental data.

Parameters:

  • data_exp (instance of DataFieldRecordArray) –

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

    log_energyfloat

    The logarithm of the reconstructed energy value of the data event.

    sin_decfloat

    The sine of the reconstructed declination of the data event.

  • log10_energy_binning (instance of BinningDefinition) – The binning definition for the binning in log10(E).

  • sin_dec_binning (instance of BinningDefinition) – The binning definition for the sin(declination).

  • smoothing_filter (instance of SmoothingFilter | None) – The smoothing filter to use for smoothing the energy histogram. If None, no smoothing will be applied.

class skyllh.i3.backgroundpdf.MCBackgroundI3EnergyPDF(data_mc, physics_weight_field_names, log10_energy_binning, sin_dec_binning, smoothing_filter=None, **kwargs)

Bases: I3EnergyPDF, IsBackgroundPDF

This is the IceCube energy background PDF, which gets constructed from monte-carlo data. This class is derived from I3EnergyPDF.

Constructs a new IceCube energy background PDF from monte-carlo data.

Parameters:

  • data_mc (instance of DataFieldRecordArray) –

    The array holding the monte-carlo data. The following data fields must exist:

    log_energyfloat

    The logarithm of the reconstructed energy value of the data event.

    sin_decfloat

    The sine of the reconstructed declination of the data event.

    mcweight: float

    The monte-carlo weight of the event.

  • physics_weight_field_names (str | list of str) – The name or the list of names of the monte-carlo data fields, which should be used as physics event weights. If a list is given, the weight values of all the fields will be summed to construct the final event physics weight.

  • log10_energy_binning (BinningDefinition) – The binning definition for the binning in log10(E).

  • sin_dec_binning (BinningDefinition) – The binning definition for the sin(declination).

  • smoothing_filter (SmoothingFilter instance | None) – The smoothing filter to use for smoothing the energy histogram. If None, no smoothing will be applied.

skyllh.i3.config module

This file defines IceCube specific global configuration.

skyllh.i3.config.add_icecube_specific_analysis_required_data_fields(cfg)

Adds IceCube specific data fields required by an IceCube analysis to the given local configuration.

Parameters:

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

skyllh.i3.dataset module

class skyllh.i3.dataset.I3Dataset(livetime=None, grl_pathfilenames=None, **kwargs)

Bases: Dataset

The I3Dataset class is an IceCube specific Dataset class that adds IceCube specific properties to the Dataset class. These additional properties are:

  • good-run-list (GRL)

Creates a new IceCube specific dataset, that also can hold a list of GRL data files.

Parameters:

  • livetime (float | None) – The live-time of the dataset in days. It can be None, if good-run-list data files are provided.

  • grl_pathfilenames (str | sequence of str) – The sequence of pathfilenames pointing to the good-run-list (GRL) data files.

static get_combined_grl_pathfilenames(datasets)

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

Parameters:

datasets (sequence of I3Dataset) – The sequence of I3Dataset instances.

Returns:

grl_pathfilenames (list) – The combined list of grl pathfilenames.

property grl_pathfilename_list

The list of file names of the good-run-list (GRL) data files 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 grl_abs_pathfilename_list

(read-only) The list of absolute path file names of the good-run-list data files.

property grl_field_name_renaming_dict

The dictionary specifying the field names of the good-run-list data which need to get renamed just after loading the data. The dictionary keys are the old names and their 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.

load_grl(efficiency_mode=None, tl=None)

Loads the good-run-list and returns a DataFieldRecordArray instance which should contain the following data fields:

runint

The run number.

startfloat

The MJD start time of the run.

stopfloat

The MJD stop time of the run.

livetimefloat

The livetime in days of the run.

eventsint

The number of experimental events in the run.

Parameters:

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

grl_data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance holding the good-run-list information of the dataset.

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. If a good-run-list (GRL) is provided for this dataset, only experimental data will be selected which matches the GRL.

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) as livetime for the DatasetData instance, otherwise uses the live time from the Dataset instance or, if available, the livetime from the good-run-list (GRL).

  • 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 that should be used to time the data load operation.

Returns:

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

prepare_data(data, tl=None)

Prepares the data for IceCube by pre-calculating the following experimental data fields:

  • sin_dec: float

    The sin value of the declination coordinate.

and monte-carlo data fields:

  • sin_true_dec: float

    The sin value of the true declination coordinate.

Parameters:

  • data (DatasetData instance) – The DatasetData instance holding the data as numpy record ndarray.

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

class skyllh.i3.dataset.I3DatasetData(data, data_grl)

Bases: DatasetData

The class provides the container for the loaded experimental and monto-carlo data of a data set. It’s the IceCube specific class that also holds the good-run-list (GRL) data.

Constructs a new I3DatasetData instance.

Parameters:

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

  • data_grl (instance of DataFieldRecordArray | None) – The instance of DataFieldRecordArray holding the good-run-list data of the dataset. This can be None, if no GRL data is available.

property grl

The DataFieldRecordArray instance holding the good-run-list (GRL) data of the IceCube data set. It is None, if there is no GRL data available for this IceCube data set.

skyllh.i3.detsigyield module

This module contains classes for IceCube specific detector signal yields, for a variation of source model and flux model combinations.

class skyllh.i3.detsigyield.I3DetSigYield(param_names, dataset, fluxmodel, livetime, sin_dec_binning, **kwargs)

Bases: DetSigYield

Abstract base class for all IceCube specific detector signal yield classes. It assumes that sin(dec) binning is required for calculating the detector effective area and hence the detector signal yield.

Constructor of the IceCube specific detector signal yield base class.

Parameters:

  • param_names (sequence of str) – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.

  • dataset (Dataset instance) – The Dataset instance holding the monte-carlo event data.

  • fluxmodel (FluxModel) – The flux model instance. Must be an instance of FluxModel.

  • livetime (float | Livetime instance) – The live-time.

  • sin_dec_binning (BinningDefinition instance) – The BinningDefinition instance defining the sin(dec) binning.

property sin_dec_binning

The BinningDefinition instance defining the sin(dec) binning.

class skyllh.i3.detsigyield.I3DetSigYieldBuilder(sin_dec_binning=None, **kwargs)

Bases: DetSigYieldBuilder

Abstract base class for an IceCube specific detector signal yield builder class.

Constructor of the IceCube specific detector signal yield builder class.

Parameters:

sin_dec_binning (BinningDefinition instance) – The instance of BinningDefinition defining the sin(dec) binning.

property sin_dec_binning

The BinningDefinition instance for the sin(dec) binning that should be used for computing the sin(dec) dependency of the detector signal yield. If None, the binning is supposed to be taken from the Dataset’s binning definitions.

get_sin_dec_binning(dataset)

Gets the sin(dec) binning definition either as setting from this detector signal yield implementation method itself, or from the given dataset.

class skyllh.i3.detsigyield.PointLikeSourceI3DetSigYield(param_names, dataset, fluxmodel, livetime, sin_dec_binning, **kwargs)

Bases: I3DetSigYield

Abstract base class for all IceCube specific detector signal yield classes for point-like sources.

Constructor of the IceCube specific detector signal yield base class for point-like sources.

Parameters:

  • param_names (sequence of str) – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating 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.

  • sin_dec_binning (BinningDefinition instance) – The BinningDefinition instance defining the sin(dec) binning.

sources_to_recarray(sources)

Converts the sequence of PointLikeSource sources into a numpy record array holding the information of the sources needed for the detector signal yield calculation.

Parameters:

sources (SourceModel | sequence of SourceModel) – The source model(s) containing the information of the source(s).

Returns:

recarr (numpy record ndarray) – The generated (N_sources,)-shaped 1D numpy record ndarray holding the information for each source.

class skyllh.i3.detsigyield.PointLikeSourceI3DetSigYieldBuilder(sin_dec_binning=None, **kwargs)

Bases: I3DetSigYieldBuilder

Abstract base class for all IceCube specific detector signal yield builders for point-like sources. All IceCube detector signal yield builders require a sin(dec) binning definition for the effective area. By default it is taken from the binning definitions stored in the dataset, but a user-defined sin(dec) binning can be specified if needed.

Initializes a new detector signal yield builder object.

Parameters:

sin_dec_binning (BinningDefinition | None) – The BinningDefinition instance defining the sin(dec) binning that should be used to compute the sin(dec) dependency of the detector effective area. If set to None, the binning will be taken from the Dataset binning definitions.

class skyllh.i3.detsigyield.FixedFluxPointLikeSourceI3DetSigYield(param_names, dataset, fluxmodel, livetime, sin_dec_binning, log_spl_sinDec, **kwargs)

Bases: PointLikeSourceI3DetSigYield

The detector signal yield class for a point-source with a fixed flux.

Constructs an IceCube detector signal yield instance for a point-like source with a fixed flux.

Parameters:

  • param_names (sequence of str) – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.

  • dataset (Dataset instance) – The instance of Dataset holding the monte-carlo data this detector signal yield is made for.

  • fluxmodel (FluxModel instance) – The instance of FluxModel with fixed parameters this detector signal yield is made for.

  • livetime (float | Livetime instance) – The livetime in days or an instance of Livetime.

  • sin_dec_binning (BinningDefinition instance) – The binning definition for sin(dec).

  • log_spl_sinDec (scipy.interpolate.InterpolatedUnivariateSpline) – The spline instance representing the log value of the detector signal yield as a function of sin(dec).

property log_spl_sinDec

The scipy.interpolate.InterpolatedUnivariateSpline instance representing the spline for the log value of the detector signal yield as a function of sin(dec).

__call__(src_recarray, src_params_recarray=None)

Retrieves the detector signal yield for the list of given sources.

Parameters:

  • src_recarray (numpy record ndarray) – The numpy record ndarray with the field dec holding the declination of the source.

  • src_params_recarray (None) – Unused interface argument, because this detector signal yield does not depend on any source parameters.

Returns:

  • values (numpy 1d ndarray) – The array with the detector signal yield for each source.

  • grads (dict) – This detector signal yield does not depend on any parameters. So there are no gradients and the dictionary is empty.

class skyllh.i3.detsigyield.FixedFluxPointLikeSourceI3DetSigYieldBuilder(sin_dec_binning=None, spline_order_sinDec=2, **kwargs)

Bases: PointLikeSourceI3DetSigYieldBuilder, IsParallelizable

This detector signal yield builder constructs a detector signal yield for a fixed flux model, assuming a point-like source. This means that the detector signal yield does not depend on any source parameters, hence it is only dependent on the detector effective area. It constructs a one-dimensional spline function in sin(dec), using a scipy.interpolate.InterpolatedUnivariateSpline.

This detector signal yield builder works with all flux models.

It is tailored to the IceCube detector at the South Pole, where the effective area depends soley on the zenith angle, and hence on the declination, of the source.

Creates a new IceCube detector signal yield builder object for a fixed flux model. It requires a sinDec binning definition to compute the sin(dec) dependency of the detector effective area. The construct_detsigyield class method of this builder will create a spline function of a given order in logarithmic space of the effective area.

Parameters:

  • sin_dec_binning (BinningDefinition | None) – The BinningDefinition instance which defines the sin(dec) binning. If set to None, the binning will be taken from the Dataset binning definitions.

  • spline_order_sinDec (int) – The order of the spline function for the logarithmic values of the detector signal yield along the sin(dec) axis. The default is 2.

property spline_order_sinDec

The order (int) of the logarithmic spline function, that splines the detector signal yield, along the sin(dec) axis.

construct_detsigyields(dataset, data, shgs, ppbar=None)

Constructs a set of FixedFluxPointLikeSourceI3DetSigYield instances, one for each provided fluxmodel.

Parameters:

  • dataset (instance of Dataset) – The instance of Dataset holding meta information about the data.

  • data (instance of DatasetData) –

    The instance of DatasetData holding the monte-carlo event data. The numpy record ndarray holding the monte-carlo event data must contain the following data fields:

    • ’true_dec’float

      The true declination of the data event.

    • ’true_energy’float

      The true energy value of the data event.

    • ’mcweight’float

      The monte-carlo weight of the data event in the unit GeV cm^2 sr.

  • shgs (sequence of instance of SourceHypoGroup) – The sequence of instance of SourceHypoGroup specifying the source hypothesis groups (i.e. flux model) for which the detector signal yields should get constructed.

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

Returns:

detsigyields (list of instance of FixedFluxPointLikeSourceI3DetSigYield) – The list of instance of FixedFluxPointLikeSourceI3DetSigYield providing the detector signal yield function for a point-like source with each of the given fixed flux models.

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

Constructs a detector signal yield log spline function for the given fixed flux model.

This method calls the construct_detsigyiels() method of this class.

Parameters:

  • dataset (instance of Dataset) – The instance of Dataset holding meta information about the data.

  • data (instance of DatasetData) –

    The instance of DatasetData holding the monte-carlo event data. The numpy record ndarray holding the monte-carlo event data must contain the following data fields:

    • ’true_dec’float

      The true declination of the data event.

    • ’true_energy’float

      The true energy value of the data event.

    • ’mcweight’float

      The monte-carlo weight of the data event in the unit GeV cm^2 sr.

  • shg (instance of SourceHypoGroup) – The instance of SourceHypoGroup (i.e. sources and flux model) for which the detector signal yield should get constructed.

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

Returns:

detsigyield (instance of FixedFluxPointLikeSourceI3DetSigYield) – The instance of FixedFluxPointLikeSourceI3DetSigYield providing the detector signal yield function for a point-like source with a fixed flux.

get_detsigyield_construction_factory()

Returns the factory callable for constructing a set of instance of FixedFluxPointLikeSourceI3DetSigYield.

Returns:

factory (callable) – The factory callable for constructing a set of instance of FixedFluxPointLikeSourceI3DetSigYield.

class skyllh.i3.detsigyield.SingleParamFluxPointLikeSourceI3DetSigYield(param_name, dataset, fluxmodel, livetime, sin_dec_binning, log_spl_sinDec_param, **kwargs)

Bases: PointLikeSourceI3DetSigYield

The detector signal yield class for a flux that depends on a single source parameter.

Constructs the detector signal yield instance.

Parameters:

  • param_name (str) – The parameter name this detector signal yield depends on. These are either fixed or floating parameter.

  • 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 instance) – The live-time.

  • sin_dec_binning (BinningDefinition instance) – The BinningDefinition instance defining the sin(dec) binning.

  • log_spl_sinDec_param (scipy.interpolate.RectBivariateSpline instance) – The 2D spline in sin(dec) and the parameter this detector signal yield depends on.

property log_spl_sinDec_param

The scipy.interpolate.RectBivariateSpline instance representing the spline for the log value of the detector signal yield as a function of sin(dec) and the floating parameter.

__call__(src_recarray, src_params_recarray)

Retrieves the detector signal yield for the given list of sources and their flux parameters.

Parameters:

  • src_recarray (numpy record ndarray) – The numpy record ndarray with the field dec holding the declination of the source.

  • src_params_recarray ((N_sources,)-shaped numpy record ndarray) – The numpy record ndarray containing the parameter values of the sources. The parameter values can be different for the different sources. The record array needs to contain two fields for each source parameter, one named <name> with the source’s local parameter name holding the source’s local parameter value, and one named <name:gpidx> holding the global parameter index plus one for each source value. For values mapping to non-fit parameters, the index should be negative.

Returns:

  • values (numpy (N_sources,)-shaped 1D ndarray) – The array with the detector signal yield for each source.

  • grads (dict) – The dictionary holding the gradient values for each global floating parameter. The key is the global floating parameter index and the value is the (N_sources,)-shaped numpy ndarray holding the gradient value dY_k/dp_s.

class skyllh.i3.detsigyield.SingleParamFluxPointLikeSourceI3DetSigYieldBuilder(param_grid, sin_dec_binning=None, spline_order_sinDec=2, spline_order_param=2, ncpu=None, **kwargs)

Bases: PointLikeSourceI3DetSigYieldBuilder, IsParallelizable

This detector signal yield builder constructs a detector signal yield for a variable flux model with a single parameter, assuming a point-like source. It constructs a two-dimensional spline function in sin(dec) and the parameter, using a scipy.interpolate.RectBivariateSpline. Hence, the detector signal yield can vary with the declination and the parameter of the flux model.

It is tailored to the IceCube detector at the South Pole, where the effective area depends soley on the zenith angle, and hence on the declination, of the source.

Creates a new IceCube detector signal yield builder instance for a flux model with a single parameter. It requires a sinDec binning definition to compute the sin(dec) dependency of the detector effective area, and a parameter grid to compute the parameter dependency of the detector signal yield.

Parameters:

  • param_grid (instance of ParameterGrid) – The instance of ParameterGrid which defines the grid of the parameter values. The name of the parameter is defined via the name property of the ParameterGrid instance.

  • sin_dec_binning (instance of BinningDefinition | None) – The instance of BinningDefinition which defines the sin(dec) binning. If set to None, the sin(dec) binning will be taken from the dataset’s binning definitions.

  • spline_order_sinDec (int) – The order of the spline function for the logarithmic values of the detector signal yield along the sin(dec) axis. The default is 2.

  • spline_order_gamma (int) – The order of the spline function for the logarithmic values of the detector signal yield along the gamma axis. The default is 2.

  • ncpu (int | None) – The number of CPUs to utilize. If set to None, global setting will take place.

property param_grid

The ParameterGrid instance for the parameter grid that should be used for computing the parameter dependency of the detector signal yield.

property spline_order_sinDec

The order (int) of the logarithmic spline function, that splines the detector signal yield, along the sin(dec) axis.

property spline_order_param

The order (int) of the logarithmic spline function, that splines the detector signal yield, along the parameter axis.

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

Constructs a detector signal yield 2-dimensional log spline function for the given flux model with varying parameter values.

Parameters:

  • dataset (instance of Dataset) – The instance of Dataset holding the sin(dec) binning definition.

  • data (instance of DatasetData) –

    The instance of DatasetData holding the monte-carlo event data. The numpy record array for the monte-carlo data of the dataset must contain the following data fields:

    'true_dec'float

    The true declination of the data event.

    'mcweight'float

    The monte-carlo weight of the data event in the unit GeV cm^2 sr.

    'true_energy'float

    The true energy value of the data event.

  • shg (instance of SourceHypoGroup) – The instance of SourceHypoGroup for which the detector signal yield should get constructed.

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

Returns:

detsigyield (instance of SingleParamFluxPointLikeSourceI3DetSigYield) – The I3DetSigYield instance for a point-like source with a flux model of a single parameter.

skyllh.i3.livetime module

class skyllh.i3.livetime.I3Livetime(*args, **kwargs)

Bases: Livetime

The I3Livetime class provides the functionality to load a Livetime object from a good-run-list data file.

Creates a new instance of I3Livetime.

classmethod from_grl_data(grl_data)

Creates an I3LiveTime instance from the given good-run-list (GRL) data.

Parameters:

grl_data (instance of numpy structured ndarray.) –

The numpy structured ndarray of length N_runs holding the start end end times of the good runs. The following fields need to exist:

startfloat

The MJD of the run start.

endfloat

The MJD of the run stop.

Returns:

livetime (instance of I3Livetime) – The created instance of I3Livetime for the provided GRL data.

static from_grl_files(pathfilenames)

Loads an I3Livetime instance from the given good-run-list (GRL) data file. The data file needs to contain the following data fields:

startfloat

The MJD of the run start.

stopfloat

The MJD of the run stop.

Parameters:

pathfilenames (str | list of str) – The list of fully qualified file names of the GRL data files.

Returns:

livetime (instance of I3Livetime) – The created instance of I3Livetime for the provided GRL data.

static from_I3Dataset(ds)

Loads an I3Livetime instance from a given I3Dataset instance, which must have a good-run-list (GRL) files defined.

Parameters:

ds (I3Dataset instance) – The instance of I3Dataset which defined the good-run-list (GRL) files for the dataset.

Returns:

livetime (instance of I3Livetime) – The created instance of I3Livetime for the GRL data from the provided dataset.

skyllh.i3.pdf module

class skyllh.i3.pdf.I3EnergyPDF(pmm, data_log10_energy, data_sin_dec, data_mcweight, data_physicsweight, log10_energy_binning, sin_dec_binning, smoothing_filter, **kwargs)

Bases: EnergyPDF, UsesBinning

This is the base class for all IceCube specific energy PDF models. IceCube energy PDFs depend soley on the energy and the zenith angle, and hence, on the declination of the event.

The IceCube energy PDF is modeled as a 1d histogram in energy, but for different sin(declination) bins, hence, stored as a 2d histogram.

Creates a new IceCube energy PDF object.

Parameters:

  • pmm (instance of ParameterModelMapper | None) – The instance of ParameterModelMapper defining the global parameters and their mapping to local model/source parameters. It can be None, if the PDF does not depend on any parameters.

  • data_log10_energy (1d ndarray) – The array holding the log10(E) values of the events.

  • data_sin_dec (1d ndarray) – The array holding the sin(dec) values of the events.

  • data_mcweight (1d ndarray) – The array holding the monte-carlo weights of the events. The final data weight will be the product of data_mcweight and data_physicsweight.

  • data_physicsweight (1d ndarray) – The array holding the physics weights of the events. The final data weight will be the product of data_mcweight and data_physicsweight.

  • log10_energy_binning (instance of BinningDefinition) – The binning definition for the log10(E) axis.

  • sin_dec_binning (instance of BinningDefinition) – The binning definition for the sin(declination) axis.

  • smoothing_filter (instance of SmoothingFilter | None) – The smoothing filter to use for smoothing the energy histogram. If None, no smoothing will be applied.

property hist_smoothing_method

The HistSmoothingMethod instance defining the smoothing filter of the energy PDF histogram.

property hist

(read-only) The 2D logE-sinDec histogram array.

property hist_mask_mc_covered

(read-only) The boolean ndarray holding the mask of the 2D histogram bins for which there is monte-carlo coverage.

property hist_mask_mc_covered_zero_physics

(read-only) The boolean ndarray holding the mask of the 2D histogram bins for which there is monte-carlo coverage but zero physics contribution.

property hist_mask_mc_covered_with_physics

(read-only) The boolean ndarray holding the mask of the 2D histogram bins for which there is monte-carlo coverage and has physics contribution.

assert_is_valid_for_trial_data(tdm, tl=None, **kwargs)

Checks if this energy PDF is valid for all the given trial events. It checks if all the data is within the log10(E) and sin(dec) binning range.

Parameters:

  • tdm (instance of TrialDataManager) –

    The instance of TrialDataManager holding the trial data events. The following data fields must exist:

    log_energyfloat

    The base-10 logarithm of the energy value of the data event.

    decfloat

    The declination of the data event.

  • tl (instance of TimeLord | None) – The optional instance of TimeLord for measuring timing information.

Raises:

ValueError – If some of the data is outside the log10(E) or sin(dec) binning range.

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

Calculates the energy probability density of each event.

Parameters:

  • tdm (instance of TrialDataManager) –

    The TrialDataManager instance holding the data events for which the probability density should be calculated. The following data fields must exist:

    log_energyfloat

    The base-10 logarithm of the energy value of the event.

    sin_decfloat

    The sin(declination) value of the event.

  • params_recarray (None) – Unused interface parameter.

  • tl (TimeLord instance | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

  • pd (instance of ndarray) – The 1D (N_events,)-shaped numpy ndarray with the energy probability density for each event.

  • grads (dict) – The dictionary holding the gradients of the probability density w.r.t. each fit parameter. The key of the dictionary is the id of the global fit parameter. Because this energy PDF does not depend on any fit parameters, an empty dictionary is returned.

skyllh.i3.pdfratio module

class skyllh.i3.pdfratio.SplinedI3EnergySigSetOverBkgPDFRatio(sig_pdf_set, bkg_pdf, fillmethod=None, interpolmethod_cls=None, ncpu=None, ppbar=None, **kwargs)

Bases: SigSetOverBkgPDFRatio, IsParallelizable

This class implements a splined signal over background PDF ratio for enegry PDFs of type I3EnergyPDF. It takes an instance, which is derived from PDFSet, and which is derived from IsSignalPDF, as signal PDF. Furthermore, it takes an instance, which is derived from I3EnergyPDF and IsBackgroundPDF, as background PDF, and creates a spline for the ratio of the signal and background PDFs for a grid of different discrete energy signal parameters, which are defined by the signal PDF set.

Creates a new IceCube signal-over-background energy PDF ratio spline instance.

Parameters:

  • sig_pdf_set (class instance derived from PDFSet (for PDF type) – I3EnergyPDF), IsSignalPDF, and UsesBinning The PDF set, which provides signal energy PDFs for a set of discrete signal parameters.

  • bkg_pdf (class instance derived from I3EnergyPDF, and) – IsBackgroundPDF The background energy PDF object.

  • fillmethod (instance of PDFRatioFillMethod | None) – An instance of class derived from PDFRatioFillMethod that implements the desired ratio fill method. If set to None (default), the default ratio fill method MostSignalLikePDFRatioFillMethod will be used.

  • interpolmethod_cls (class of GridManifoldInterpolationMethod) – The class implementing the parameter interpolation method for the PDF ratio manifold grid.

  • ncpu (int | None) – The number of CPUs to use to create the ratio splines for the different sets of signal parameters.

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

Raises:

ValueError – If the signal and background PDFs use different binning.

property fillmethod

The PDFRatioFillMethod object, which should be used for filling the PDF ratio bins.

get_ratio(tdm, src_params_recarray, tl=None)

Retrieves the PDF ratio values for each given trial event data, given the given set of fit parameters. This method is called during the likelihood maximization process. For computational efficiency reasons, the gradients are calculated as well and will be cached.

Parameters:

  • tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial event data for which the PDF ratio values should get calculated.

  • src_params_recarray (instance of numpy record ndarray | None) – The (N_sources,)-shaped numpy record ndarray holding the parameter names and values of the sources. See the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() for more information.

  • tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

ratio (instance of numpy ndarray) – The (N_values,)-shaped numpy ndarray of float holding the PDF ratio value for each source and trial event.

get_gradient(tdm, src_params_recarray, fitparam_id, tl=None)

Retrieves the PDF ratio gradient for the given fit parameter fitparam_id.

Parameters:

  • tdm (instance of TrialDataManager) – The TrialDataManager instance holding the trial event data for which the PDF ratio gradient values should get calculated.

  • src_params_recarray (instance of numpy record ndarray | None) – The (N_sources,)-shaped numpy record ndarray holding the local parameter names and values of all sources. See the skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray() method for more information.

  • fitparam_id (int) – The ID of the global fit parameter for which the gradient should get calculated.

  • tl (instance of TimeLord | None) – The optional TimeLord instance that should be used to measure timing information.

Returns:

grad (instance of ndarray) – The (N_values,)-shaped numpy ndarray holding the gradient values for all sources and trial events w.r.t. the given global fit parameter.

skyllh.i3.scrambling module

class skyllh.i3.scrambling.I3TimeScramblingMethod(timegen, **kwargs)

Bases: TimeScramblingMethod

The I3TimeScramblingMethod class provides a data scrambling method to perform time scrambling of the data, by drawing a MJD time from a given time generator.

Initializes a new I3 time scrambling instance.

Parameters:

timegen (TimeGenerator) – The time generator that should be used to generate random MJD times.

scramble(rss, dataset, data)

Draws a time from the time generator and calculates the right ascention coordinate from the azimuth angle according to the time. Sets the values of the time and ra keys of data.

Parameters:

  • rss (RandomStateService) – The random state service providing the random number generator (RNG).

  • dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.

  • data (DataFieldRecordArray instance) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

data (numpy record ndarray) – The given numpy record ndarray holding the scrambled data.

class skyllh.i3.scrambling.I3SeasonalVariationTimeScramblingMethod(data, **kwargs)

Bases: DataScramblingMethod

The I3SeasonalVariationTimeScramblingMethod class provides a data scrambling method to perform data coordinate scrambling based on a generated time, which follows seasonal variations within the experimental data.

Initializes a new seasonal time scrambling instance.

Parameters:

data (instance of I3DatasetData) – The instance of I3DatasetData holding the experimental data and good-run-list information.

scramble(rss, dataset, data)

Scrambles the given data based on random MJD times, which are generated uniformely within the data runs, where the data runs are weighted based on their amount of events compared to the total events.

Parameters:

  • rss (instance of RandomStateService) – The random state service providing the random number generator (RNG).

  • dataset (instance of Dataset) – The instance of Dataset for which the data should get scrambled.

  • data (instance of DataFieldRecordArray) – The DataFieldRecordArray instance containing the to be scrambled data.

Returns:

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

skyllh.i3.signal_generation module

skyllh.i3.signal_generation.source_sin_dec_shift_linear(x, w, L, U)

Calculates the shift of the sine of the source declination, in order to allow the construction of the source sine declination band with sin(dec_src) +/- w. This shift function, S(x), is implemented as a line with the following points:

S(L) = w S((L+U)/2) = 0 S(U) = -w

Parameters:

  • x (1D numpy ndarray) – The sine of the source declination for each source.

  • w (float) – The half size of the sin(dec)-window.

  • L (float) – The lower value of the allowed sin(dec) range.

  • U (float) – The upper value of the allowed sin(dec) range.

Returns:

S (1D numpy ndarray) – The sin(dec) shift of the sin(dec) values of the given sources, such that sin(dec_src) + S is the new sin(dec) of the source, and sin(dec_src) + S +/- w is always within the sin(dec) range [L, U].

skyllh.i3.signal_generation.source_sin_dec_shift_cubic(x, w, L, U)

Calculates the shift of the sine of the source declination, in order to allow the construction of the source sine declination band with sin(dec_src) +/- w. This shift function, S(x), is implemented as a cubic function with the following points:

S(L) = w S((L+U)/2) = 0 S(U) = -w

Parameters:

  • x (1D numpy ndarray) – The sine of the source declination for each source.

  • w (float) – The half size of the sin(dec)-window.

  • L (float) – The lower value of the allowed sin(dec) range.

  • U (float) – The upper value of the allowed sin(dec) range.

Returns:

S (1D numpy ndarray) – The sin(dec) shift of the sin(dec) values of the given sources, such that sin(dec_src) + S is the new sin(dec) of the source, and sin(dec_src) + S +/- w is always within the sin(dec) range [L, U].

class skyllh.i3.signal_generation.PointLikeSourceI3SignalGenerationMethod(src_sin_dec_half_bandwidth=0.01745240643728351, src_sin_dec_shift_func=None, energy_range=None, src_batch_size=128, **kwargs)

Bases: SignalGenerationMethod

This class provides a signal generation method for point-like sources seen in the IceCube detector.

Constructs a new signal generation method instance for a point-like source detected with IceCube.

Parameters:

  • src_sin_dec_half_bandwidth (float) – The half-width of the sin(dec) band to take MC events from around a source. The default is sin(1deg), i.e. a 1deg half-bandwidth.

  • src_sin_dec_shift_func (callable | None) – The function that provides the source sin(dec) shift needed for constructing the source declination bands from where to draw monte-carlo events from. If set to None, the default function source_sin_dec_shift_linear will be used.

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

  • src_batch_size (int) – The source processing batch size used for the signal event flux calculation.

property src_sin_dec_half_bandwidth

The half-width of the sin(dec) band to take MC events from around a source.

property src_sin_dec_shift_func

The function that provides the source sin(dec) shift needed for constructing the source declination bands from where to draw monte-carlo events from.

property src_batch_size

The source processing batch size used for the signal event flux calculation.

calc_source_signal_mc_event_flux(data_mc, shg)

Calculates 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 the MC events of a dataset.

  • shg (SourceHypoGroup instance) – The source hypothesis group, which defines the list of sources, and their flux model.

Returns:

  • ev_idx_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the index of the MC event.

  • shg_src_idx_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the index of the source within the given source hypothesis group for each signal candidate event.

  • flux_arr (ndarray) – The (N_selected_signal_events,)-shaped 1D ndarray holding the flux value of each signal candidate event.

signal_event_post_sampling_processing(shg, shg_sig_events_meta, shg_sig_events)

Rotates the generated signal events to their source location for a given source hypothesis group.

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 ndarray) – The numpy record ndarray with the processed MC signal events.

skyllh.i3.signalpdf module

class skyllh.i3.signalpdf.SignalI3EnergyPDFSet(cfg, data_mc, log10_energy_binning, sin_dec_binning, fluxmodel, param_grid_set, smoothing_filter=None, ncpu=None, ppbar=None, **kwargs)

Bases: PDFSet, IsSignalPDF, PDF, IsParallelizable

This is the signal energy PDF for IceCube. It creates a set of I3EnergyPDF objects for a discrete set of energy signal parameters. Energy signal parameters influence the source’s flux model.

Creates a new IceCube energy signal PDF for a given flux model and a set of parameter grids for the flux model. It creates a set of I3EnergyPDF objects for each signal parameter value permutation and stores it in an internal dictionary, where the hash of the parameters dictionary is the key.

Parameters:

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

  • data_mc (instance of DataFieldRecordArray) –

    The instance of DataFieldRecordArray holding the monte-carlo data. The following data fields must exist:

    true_energyfloat

    The true energy value of the data event.

    log_energyfloat

    The base10-logarithm of the reconstructed energy value of the data event.

    sin_decfloat

    The declination of the data event.

    mcweightfloat

    The monte-carlo weight value of the data events in unit GeV cm^2 sr.

  • log10_energy_binning (instance of BinningDefinition) – The binning definition for the reconstructed energy binning in log10(E).

  • sin_dec_binning (instance of BinningDefinition) – The binning definition for the binning in sin(declination).

  • fluxmodel (instance of FluxModel) – The flux model to use to create the signal energy PDF.

  • param_grid_set (instance of ParameterGridSet |) – instance of ParameterGrid The set of parameter grids. A ParameterGrid instance for each energy parameter, for which an I3EnergyPDF object needs to be created.

  • smoothing_filter (instance of SmoothingFilter | None) – The smoothing filter to use for smoothing the energy histogram. If None, no smoothing will be applied.

  • ncpu (int | None) – The number of CPUs to use to create the different I3EnergyPDF instances for the different parameter grid values. If set to None, the configured default number of CPUs will be used.

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