skyllh.i3 package

Subpackages

Submodules

skyllh.i3.background_generation module

class skyllh.i3.background_generation.FixedScrambledExpDataI3BkgGenMethod(data_scrambler: DataScrambler, **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 – The DataScrambler instance to use to generate scrambled experimental data.

__annotations_cache__ = {}
__firstlineno__ = 15
__static_attributes__ = ('_data_scrambler', 'data_scrambler')
property data_scrambler

The DataScrambler instance that implements the data scrambling.

generate_events(rss: RandomStateService, dataset: Dataset, data: DatasetData, **kwargs) → tuple[int, DataFieldRecordArray]

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 – The instance of RandomStateService that should be used to generate random numbers from. It is used to scramble the experimental data.

  • dataset – The Dataset instance describing the dataset for which background events should get generated.

  • data – The DatasetData instance holding the data of the dataset for which background events should get generated.

Returns:

  • n_bkg – The number of generated background events.

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

skyllh.i3.backgroundpdf module

class skyllh.i3.backgroundpdf.BackgroundI3SpatialPDF(data_sin_dec: ndarray, data_weights: ndarray, sin_dec_binning: BinningDefinition, spline_order_sin_dec: int, **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 – The array holding the sin(dec) values of the events.

  • data_weights – The array holding the weight of each event used for histogramming.

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

  • spline_order_sin_dec – 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: ndarray)

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

Parameters:

events –

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

sin_dec

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: TrialDataManager, params_recarray: None = None, tl: TimeLord | None = None) → tuple[ndarray, dict]

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

Parameters:

  • tdm –

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

    sin_dec

    The sin(declination) value of the event.

  • params_recarray – Unused interface parameter.

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

Returns:

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

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

__annotations_cache__ = {}
__firstlineno__ = 26
__static_attributes__ = ('_log_spline', '_orig_hist', '_orig_log_spline', '_pd', '_spline_order_sin_dec', 'spline_order_sin_dec')
class skyllh.i3.backgroundpdf.DataBackgroundI3SpatialPDF(data_exp: DataFieldRecordArray, sin_dec_binning: BinningDefinition, spline_order_sin_dec: int = 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 –

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

    sin_dec

    The sin(declination) of the data event.

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

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

__annotations_cache__ = {}
__firstlineno__ = 198
__static_attributes__ = ()
class skyllh.i3.backgroundpdf.MCBackgroundI3SpatialPDF(data_mc: DataFieldRecordArray, physics_weight_field_names: str | list[str], sin_dec_binning: BinningDefinition, spline_order_sin_dec: int = 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 –

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

    sin_dec

    The sine of the reconstructed declination of the data event.

  • physics_weight_field_names – 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 – The binning definition for the sin(declination).

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

__annotations_cache__ = {}
__firstlineno__ = 251
__static_attributes__ = ()
class skyllh.i3.backgroundpdf.DataBackgroundI3EnergyPDF(data_exp: DataFieldRecordArray, log10_energy_binning: BinningDefinition, sin_dec_binning: BinningDefinition, smoothing_filter: SmoothingFilter | None = 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 –

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

    log_energy

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

    sin_dec

    The sine of the reconstructed declination of the data event.

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

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

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

__annotations_cache__ = {}
__firstlineno__ = 324
__static_attributes__ = ()
class skyllh.i3.backgroundpdf.MCBackgroundI3EnergyPDF(data_mc: DataFieldRecordArray, physics_weight_field_names: str | list[str], log10_energy_binning: BinningDefinition, sin_dec_binning: BinningDefinition, smoothing_filter: SmoothingFilter | None = 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 –

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

    log_energy

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

    sin_dec

    The sine of the reconstructed declination of the data event.

    mcweight

    The monte-carlo weight of the event.

  • physics_weight_field_names – 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 – The binning definition for the binning in log10(E).

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

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

__annotations_cache__ = {}
__firstlineno__ = 390
__static_attributes__ = ()

skyllh.i3.config module

This file defines IceCube specific global configuration.

skyllh.i3.config.add_icecube_specific_analysis_required_data_fields(cfg: Config)

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

Parameters:

cfg – The instance of Config holding the local configuration.

skyllh.i3.dataset module

class skyllh.i3.dataset.I3Dataset(livetime: float | None = None, grl_pathfilenames: str | Sequence[str] | None = 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 – The live-time of the dataset in days. It can be None, if good-run-list data files are provided.

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

static get_combined_grl_pathfilenames(datasets: Sequence[I3Dataset]) → list

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

Parameters:

datasets – The sequence of I3Dataset instances.

Returns:

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

create_file_list() → list[str]

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

Returns:

file_list – The list of files of this dataset.

load_grl(efficiency_mode: str | None = None, tl: TimeLord | None = None) → DataFieldRecordArray

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 –

    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 – The TimeLord instance to use to time the data loading procedure.

Returns:

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

load_data(livetime: Livetime | float | None = None, keep_fields: list[str] | None = None, dtc_dict: dict | None = None, dtc_except_fields: str | Sequence[str] | None = None, efficiency_mode: str | None = None, tl: TimeLord | None = None) → DatasetData

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:

  • livetime – If not None, uses this livetime (if float 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).

  • keep_fields – The list of user-defined data fields that should get loaded and kept in addition to the analysis required data fields.

  • dtc_dict – This dictionary defines how data fields of specific data types (key) should get converted into other data types (value). This can be used to use less memory. If set to None, no data convertion is performed.

  • dtc_except_fields – The sequence of field names whose data type should not get converted.

  • efficiency_mode –

    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 – The TimeLord instance that should be used to time the data load operation.

Returns:

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

__annotations_cache__ = {}
__firstlineno__ = 28
__static_attributes__ = ('_grl_field_name_renaming_dict', '_grl_pathfilename_list', '_logger', 'grl_field_name_renaming_dict', 'grl_pathfilename_list')
prepare_data(data: I3DatasetData, tl: TimeLord | None = 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 – The DatasetData instance holding the data as numpy record ndarray.

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

class skyllh.i3.dataset.I3DatasetData(data: DatasetData, data_grl: DataFieldRecordArray | None)

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 – The instance of DatasetData holding the experimental and monte-carlo data.

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

__annotations_cache__ = {}
__firstlineno__ = 410
__static_attributes__ = ('_grl', 'grl')
property grl: DataFieldRecordArray | None

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: Sequence[str], dataset: Dataset, fluxmodel: FluxModel, livetime: float | Livetime, sin_dec_binning: BinningDefinition, **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 – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.

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

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

  • livetime – The live-time.

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

property sin_dec_binning

The BinningDefinition instance defining the sin(dec) binning.

__annotations_cache__ = {}
__firstlineno__ = 40
__static_attributes__ = ('_sin_dec_binning', 'sin_dec_binning')
class skyllh.i3.detsigyield.I3DetSigYieldBuilder(sin_dec_binning: BinningDefinition | None = 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 – 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.

__annotations_cache__ = {}
__firstlineno__ = 91
__static_attributes__ = ('_sin_dec_binning', 'sin_dec_binning')
class skyllh.i3.detsigyield.PointLikeSourceI3DetSigYield(param_names: Sequence[str], dataset: Dataset, fluxmodel: FluxModel, livetime: float | Livetime, sin_dec_binning: BinningDefinition, **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 – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.

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

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

  • livetime – The livetime in days or an instance of Livetime.

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

sources_to_recarray(sources: SourceModel | Sequence[SourceModel]) → ndarray

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 – The source model(s) containing the information of the source(s).

Returns:

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

__annotations_cache__ = {}
__firstlineno__ = 150
__static_attributes__ = ()
class skyllh.i3.detsigyield.PointLikeSourceI3DetSigYieldBuilder(sin_dec_binning: BinningDefinition | None = 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 – 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.

__annotations_cache__ = {}
__firstlineno__ = 219
__static_attributes__ = ()
class skyllh.i3.detsigyield.FixedFluxPointLikeSourceI3DetSigYield(param_names: Sequence[str], dataset: Dataset, fluxmodel: FluxModel, livetime: float | Livetime, sin_dec_binning: BinningDefinition, log_spl_sinDec: InterpolatedUnivariateSpline, **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 – The sequence of parameter names this detector signal yield depends on. These are either fixed or floating parameters.

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

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

  • livetime – The livetime in days or an instance of Livetime.

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

  • log_spl_sinDec – 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: ndarray, src_params_recarray: None = None) → tuple[ndarray, dict]

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

Parameters:

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

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

Returns:

  • values – The array with the detector signal yield for each source.

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

__annotations_cache__ = {}
__firstlineno__ = 249
__static_attributes__ = ('_log_spl_sinDec', 'log_spl_sinDec')
class skyllh.i3.detsigyield.FixedFluxPointLikeSourceI3DetSigYieldBuilder(sin_dec_binning: BinningDefinition | None = None, spline_order_sinDec: int = 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 – 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 – 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: Dataset, data: DatasetData, shgs: Sequence[SourceHypoGroup], ppbar: ProgressBar | None = None) → list[FixedFluxPointLikeSourceI3DetSigYield]

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

Parameters:

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

  • data –

    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 – 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 – The optional instance of ProgressBar of the parent progress bar.

Returns:

detsigyields – 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: Dataset, data: DatasetData, shg: SourceHypoGroup, ppbar: ProgressBar | None = None) → FixedFluxPointLikeSourceI3DetSigYield

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 – The instance of Dataset holding meta information about the data.

  • data –

    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 – The instance of SourceHypoGroup (i.e. sources and flux model) for which the detector signal yield should get constructed.

  • ppbar – The optional instance of ProgressBar of the parent progress bar.

Returns:

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

get_detsigyield_construction_factory() → Callable

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

Returns:

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

__annotations_cache__ = {}
__firstlineno__ = 349
__static_attributes__ = ('_spline_order_sinDec', 'spline_order_sinDec')
class skyllh.i3.detsigyield.SingleParamFluxPointLikeSourceI3DetSigYield(param_name: str, dataset: Dataset, fluxmodel: FluxModel, livetime: float | Livetime, sin_dec_binning: BinningDefinition, log_spl_sinDec_param: RectBivariateSpline, **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 – The parameter name this detector signal yield depends on. These are either fixed or floating parameter.

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

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

  • livetime – The live-time.

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

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

__annotations_cache__ = {}
__firstlineno__ = 668
__static_attributes__ = ('_log_spl_sinDec_param', 'log_spl_sinDec_param')
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: ndarray, src_params_recarray: ndarray) → tuple[ndarray, dict]

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

Parameters:

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

  • src_params_recarray – 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 – The array with the detector signal yield for each source.

  • grads – 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: ParameterGrid, sin_dec_binning: BinningDefinition | None = None, spline_order_sinDec: int = 2, spline_order_param=2, ncpu: int | None = 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 – 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 – 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 – 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 – The order of the spline function for the logarithmic values of the detector signal yield along the gamma axis. The default is 2.

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

__annotations_cache__ = {}
__firstlineno__ = 820
__static_attributes__ = ('_param_grid', '_spline_order_param', '_spline_order_sinDec', 'param_grid', 'spline_order_param', 'spline_order_sinDec')
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: Dataset, data: DatasetData, shg: SourceHypoGroup, ppbar: ProgressBar | None = None) → SingleParamFluxPointLikeSourceI3DetSigYield

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

Parameters:

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

  • data –

    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 – The instance of SourceHypoGroup for which the detector signal yield should get constructed.

  • ppbar – The instance of ProgressBar of the optional parent progress bar.

Returns:

detsigyield – 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: ndarray) → I3Livetime

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

Parameters:

grl_data –

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

start

The MJD of the run start.

end

The MJD of the run stop.

Returns:

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

static from_grl_files(pathfilenames: str | list[str]) → I3Livetime

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 – The list of fully qualified file name(s) of the GRL data file(s).

Returns:

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

static from_I3Dataset(ds: I3Dataset) → I3Livetime

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

Parameters:

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

Returns:

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

__annotations_cache__ = {}
__firstlineno__ = 14
__static_attributes__ = ()

skyllh.i3.pdf module

class skyllh.i3.pdf.I3EnergyPDF(pmm: ParameterModelMapper | None, data_log10_energy: ndarray, data_sin_dec: ndarray, data_mcweight: ndarray, data_physicsweight: ndarray, log10_energy_binning: BinningDefinition, sin_dec_binning: BinningDefinition, smoothing_filter: SmoothingFilter | None, **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 – 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 – The array holding the log10(E) values of the events.

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

  • data_mcweight – 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 – 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 – The binning definition for the log10(E) axis.

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

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

__annotations_cache__ = {}
__firstlineno__ = 28
__static_attributes__ = ('_hist_log10_energy_sin_dec', '_hist_mask_mc_covered', '_hist_mask_mc_covered_zero_physics', '_hist_smoothing_method', 'hist_smoothing_method')
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: TrialDataManager, tl: TimeLord | None = 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 –

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

    log_energy

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

    dec

    The declination of the data event.

  • tl – 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: TrialDataManager, params_recarray: None = None, tl: TimeLord | None = None) → tuple[ndarray, dict]

Calculates the energy probability density of each event.

Parameters:

  • tdm –

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

    log_energy

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

    sin_dec

    The sin(declination) value of the event.

  • params_recarray – Unused interface parameter.

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

Returns:

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

  • grads – 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: PDFRatioFillMethod | None = None, interpolmethod_cls: type[GridManifoldInterpolationMethod] | None = None, ncpu: int | None = None, ppbar: ProgressBar | None = 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 – I3EnergyPDF), IsSignalPDF, and UsesBinning The PDF set, which provides signal energy PDFs for a set of discrete signal parameters.

  • bkg_pdf – IsBackgroundPDF The background energy PDF object.

  • fillmethod – 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 – The class implementing the parameter interpolation method for the PDF ratio manifold grid.

  • ncpu – The number of CPUs to use to create the ratio splines for the different sets of signal parameters.

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

__annotations_cache__ = {}
__firstlineno__ = 27
__static_attributes__ = ('_cache', '_data_field_names', '_fillmethod', '_gridparams_hash_log_ratio_spline_dict', '_interpol_param_names', '_interpolmethod', 'fillmethod')
get_ratio(tdm: TrialDataManager, src_params_recarray: ndarray, tl: TimeLord | None = None) → ndarray

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 – The TrialDataManager instance holding the trial event data for which the PDF ratio values should get calculated.

  • src_params_recarray – 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 – The optional TimeLord instance that should be used to measure timing information.

Returns:

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

get_gradient(tdm: TrialDataManager, src_params_recarray: ndarray | None, fitparam_id: int, tl: TimeLord | None = None) → ndarray

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

Parameters:

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

  • src_params_recarray – 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 – The ID of the global fit parameter for which the gradient should get calculated.

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

Returns:

grad – 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: TimeGenerator, **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 – The time generator that should be used to generate random MJD times.

scramble(rss: RandomStateService, dataset: Dataset, data: DataFieldRecordArray) → DataFieldRecordArray

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 – The random state service providing the random number generator (RNG).

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

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

Returns:

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

__annotations_cache__ = {}
__firstlineno__ = 18
__static_attributes__ = ()
class skyllh.i3.scrambling.I3SeasonalVariationTimeScramblingMethod(data: I3DatasetData, **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 – The instance of I3DatasetData holding the experimental data and good-run-list information.

scramble(rss: RandomStateService, dataset: Dataset, data: DataFieldRecordArray) → DataFieldRecordArray

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 – The random state service providing the random number generator (RNG).

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

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

Returns:

data – The given DataFieldRecordArray holding the scrambled data.

__annotations_cache__ = {}
__firstlineno__ = 76
__static_attributes__ = ('grl', 'run_weights')

skyllh.i3.signal_generation module

skyllh.i3.signal_generation.source_sin_dec_shift_linear(x: ndarray, w: float, L: float, U: float) → ndarray

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 – The sine of the source declination for each source.

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

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

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

Returns:

S – 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: ndarray, w: float, L: float, U: float) → ndarray

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 – The sine of the source declination for each source.

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

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

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

Returns:

S – 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: float = np.float64(0.01745240643728351), src_sin_dec_shift_func: Callable | None = None, energy_range: tuple[float, float] | None = None, src_batch_size: int = 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 – 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 – 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 – The energy range from which to take MC events into account for signal event generation, specified in true neutrino energy (GeV). If set to None, the entire energy range [0, +inf] is used.

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

__annotations_cache__ = {}
__firstlineno__ = 96
__static_attributes__ = ('_src_batch_size', '_src_sin_dec_half_bandwidth', '_src_sin_dec_shift_func', 'src_batch_size', 'src_sin_dec_half_bandwidth', 'src_sin_dec_shift_func')
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: ndarray, shg: SourceHypoGroup) → tuple[ndarray, ndarray, ndarray]

Calculates the signal flux of each given MC event for each source hypothesis of the given source hypothesis group.

Parameters:

  • data_mc – The numpy record array holding the MC events of a dataset.

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

Returns:

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

  • shg_src_idx_arr – 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 – The (N_selected_signal_events,)-shaped 1D ndarray holding the flux value of each signal candidate event.

signal_event_post_sampling_processing(shg: SourceHypoGroup, shg_sig_events_meta: ndarray, shg_sig_events: ndarray) → ndarray

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

Parameters:

  • shg – The source hypothesis group instance holding the sources and their locations.

  • shg_sig_events_meta –

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

skyllh.i3.signalpdf module

class skyllh.i3.signalpdf.SignalI3EnergyPDFSet(cfg: Config, data_mc: DataFieldRecordArray, log10_energy_binning: BinningDefinition, sin_dec_binning: BinningDefinition, fluxmodel: FluxModel, param_grid_set: ParameterGridSet | ParameterGrid, smoothing_filter: SmoothingFilter | None = None, ncpu: int | None = None, ppbar: ProgressBar | None = 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 – The instance of Config holding the local configuration.

  • data_mc –

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

    true_energy

    The true energy value of the data event.

    log_energy

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

    sin_dec

    The declination of the data event.

    mcweight

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

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

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

  • fluxmodel – The flux model to use to create the signal energy PDF.

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

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

  • ncpu – 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 – The instance of ProgressBar of the optional parent progress bar.

__annotations_cache__ = {}
__firstlineno__ = 36
__static_attributes__ = ()