skyllh.i3 package

Subpackages

Submodules

skyllh.i3.background_generation module

class skyllh.i3.background_generation.FixedScrambledExpDataI3BkgGenMethod(data_scrambler)

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 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_sinDec, data_weights, sinDec_binning, spline_order_sinDec)

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_sinDec (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.

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

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

property spline_order_sinDec

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_dec’float

    The sin(declination) value of the event.

reset()

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

get_prob(tdm, fitparams=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_dec’float

      The sin(declination) value of the event.

  • fitparams (None) – Unused interface parameter.

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

Returns:

prob (1d ndarray) – The spherical background probability of each data event.

class skyllh.i3.backgroundpdf.DataBackgroundI3SpatialPDF(data_exp, sinDec_binning, spline_order_sinDec=2)

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:

    • ’dec’float

      The declination of the data event.

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

  • spline_order_sinDec (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, sinDec_binning, spline_order_sinDec=2)

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_dec’float

      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.

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

  • spline_order_sinDec (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, logE_binning, sinDec_binning, smoothing_filter=None)

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_energy’float

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

    • ’sin_dec’float

      The sine of the reconstructed declination of the data event.

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

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

class skyllh.i3.backgroundpdf.MCBackgroundI3EnergyPDF(data_mc, physics_weight_field_names, logE_binning, sinDec_binning, smoothing_filter=None)

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_energy’float

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

    • ’sin_dec’float

      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.

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

  • sinDec_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.coords module

IceCube specific coordinate utility functions.

skyllh.i3.coords.azi_to_ra_transform(azi, mjd)

Rotates the given IceCube azimuth angles into right-ascention angles for the given MJD times. This function is IceCube specific and assumes that the detector is located excently at the South Pole and neglects all astronomical effects like Earth’s precession.

Parameters:

  • azi (ndarray) – The array with the azimuth angles.

  • mjd (ndarray) – The array with the MJD times for each azimuth angle.

skyllh.i3.coords.ra_to_azi_transform(ra, mjd)

Rotates the given right-ascention angles to local IceCube azimuth angles.

Parameters:

  • ra (ndarray) – The array with the right-ascention angles.

  • mjd (ndarray) – The array with the MJD times for each right-ascention angle.

skyllh.i3.coords.hor_to_equ_transform(azi, zen, mjd)

Transforms the coordinate from the horizontal system (azimuth, zenith) into the equatorial system (right-ascention, declination) for detector at the South Pole and neglecting all astronomical effects like Earth precession.

Parameters:

  • azi (ndarray) – The azimuth angle.

  • zen (ndarray) – The zenith angle.

  • mjd (ndarray) – The time in MJD.

Returns:

(ra, dec) ((ndarray, ndarray)) – The two-element tuple with the arrays of right-ascention and declination.

skyllh.i3.dataset module

class skyllh.i3.dataset.I3Dataset(grl_pathfilenames=None, *args, **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:

grl_pathfilenames (str | sequence of str) –

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

  • data_grl (DataFieldRecordArray instance | None) – The DataFieldRecordArray instance 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(implmethod, dataset, fluxmodel, livetime, sin_dec_binning)

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.

property sin_dec_binning

The BinningDefinition instance defining the sin(dec) binning definition.

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

Bases: DetSigYieldImplMethod

Abstract base class for an IceCube specific detector signal yield implementation method class.

Constructor of the IceCube specific detector signal yield implementation base class.

Parameters:

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

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.PointLikeSourceI3DetSigYieldImplMethod(sin_dec_binning=None, **kwargs)

Bases: I3DetSigYieldImplMethod

Abstract base class for all IceCube specific detector signal yield implementation methods for a point-like source. All IceCube detector signal yield implementation methods require a sinDec binning definition for the effective area. By default it is taken from the binning definitios stored in the dataset, but a user-defined sinDec binning can be specified if needed.

Initializes a new detector signal yield implementation method 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.

source_to_array(sources)

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

Parameters:

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

Returns:

arr (numpy record ndarray) – The generated numpy record ndarray holding the spatial information for each source.

class skyllh.i3.detsigyield.FixedFluxPointLikeSourceI3DetSigYield(implmethod, dataset, fluxmodel, livetime, sin_dec_binning, log_spl_sinDec)

Bases: I3DetSigYield

The detector signal yield class for the FixedFluxPointLikeSourceI3DetSigYieldImplMethod detector signal yield implementation method.

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

Parameters:

  • implmethod (FixedFluxPointLikeSourceI3DetSigYieldImplMethod instance) – The instance of the detector signal yield implementation method.

  • 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, src_flux_params=None)

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

Parameters:

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

  • src_flux_params (None) – Unused interface argument, because this implementation does not depend on any source flux fit parameters.

Returns:

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

  • grads (None) – Because with this implementation the detector signal yield does not depend on any fit parameters. So there are no gradients and None is returned.

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

Bases: PointLikeSourceI3DetSigYieldImplMethod

This detector signal yield implementation method 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 flux 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 implementation method 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 implementation method 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 class method of this implementation method 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_detsigyield(dataset, data, fluxmodel, livetime, ppbar=None)

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

Parameters:

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

  • data (DatasetData instance) –

    The DatasetData instance 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.

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

  • livetime (float | Livetime) – The live-time in days to use for the detector signal yield.

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

Returns:

detsigyield (FixedFluxPointLikeSourceI3DetSigYield instance) – The DetSigYield instance for point-like source with a fixed flux.

class skyllh.i3.detsigyield.PowerLawFluxPointLikeSourceI3DetSigYield(implmethod, dataset, fluxmodel, livetime, sin_dec_binning, log_spl_sinDec_gamma)

Bases: I3DetSigYield

The detector signal yield class for the PowerLawFluxPointLikeSourceI3DetSigYieldImplMethod detector signal yield implementation method.

Constructs the detector signal yield instance.

property log_spl_sinDec_gamma

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

__call__(src, src_flux_params)

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

Parameters:

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

  • src_flux_params ((N_sources,)-shaped numpy record ndarray) – The numpy record ndarray containing the flux parameter gamma for the sources. gamma can be different for the different sources.

Returns:

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

  • grads (numpy (N_sources,N_fitparams)-shaped 2D ndarray) – The array containing the gradient values for each source and fit parameter. Since, this implementation depends on only one fit parameter, i.e. gamma, the array is (N_sources,1)-shaped.

class skyllh.i3.detsigyield.PowerLawFluxPointLikeSourceI3DetSigYieldImplMethod(gamma_grid, sin_dec_binning=None, spline_order_sinDec=2, spline_order_gamma=2, ncpu=None)

Bases: PointLikeSourceI3DetSigYieldImplMethod, IsParallelizable

This detector signal yield implementation method constructs a detector signal yield for a variable power law flux model, which has the spectral index gamma as fit parameter, assuming a point-like source. It constructs a two-dimensional spline function in sin(dec) and gamma, using a scipy.interpolate.RectBivariateSpline. Hence, the detector signal yield can vary with the declination and the spectral index, gamma, of the source.

This detector signal yield implementation method works with a PowerLawFlux 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 implementation method object for a power law flux model. It requires a sinDec binning definition to compute the sin(dec) dependency of the detector effective area, and a gamma parameter grid to compute the gamma dependency of the detector signal yield.

Parameters:

  • gamma_grid (ParameterGrid instance) – The ParameterGrid instance which defines the grid of gamma values.

  • sin_dec_binning (BinningDefinition | None) – The BinningDefinition instance 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. Global setting will take place if not specified, i.e. set to None.

property gamma_grid

The ParameterGrid instance for the gamma grid that should be used for computing the gamma 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_gamma

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

construct_detsigyield(dataset, data, fluxmodel, livetime, ppbar=None)

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

Parameters:

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

  • data (DatasetData instance) –

    The DatasetData instance 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.

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

  • livetime (float | Livetime instance) – The live-time in days or an instance of Livetime to use for the detector signal yield.

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

Returns:

detsigyield (PowerLawFluxPointLikeSourceI3DetSigYield instance) – The DetSigYield instance for a point-like source with a power law flux with variable gamma parameter.

skyllh.i3.livetime module

class skyllh.i3.livetime.I3Livetime(uptime_mjd_intervals_arr)

Bases: Livetime

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

Creates a new Livetime object from a (N,2)-shaped ndarray holding the uptime intervals.

Parameters:

uptime_mjd_intervals_arr ((N,2)-shaped ndarray) –

The (N,2)-shaped ndarray holding the start and end times of each up-time interval.

Note 1: The intervals must be sorted ascedent in time.

Note 2: By definition the lower edge is included in the interval,

whereas the upper edge is excluded from the interval.

Note 3: The intervals must not overlap.

The integrity of the internal mjd interval array will be ensured by the property setter method of uptime_mjd_intervals_arr by calling the assert_mjd_intervals_integrity method.

static 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 (I3Livetime instance) – The created I3Livetime instance 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 (I3Livetime instance) – The created I3Livetime instance for the GRL data from the provided dataset.

skyllh.i3.pdf module

class skyllh.i3.pdf.I3EnergyPDF(data_logE, data_sinDec, data_mcweight, data_physicsweight, logE_binning, sinDec_binning, smoothing_filter)

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:

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

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

  • logE_binning (BinningDefinition) – The binning definition for the log(E) axis.

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

  • smoothing_filter (SmoothingFilter instance | 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_exp_data(data_exp)

Checks if this energy PDF is valid for all the given experimental data. It checks if all the data is within the logE and sin(dec) binning range.

Parameters:

data_exp (numpy record ndarray) –

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

  • ’log_energy’float

    The logarithm of the energy value of the data event.

  • ’dec’float

    The declination of the data event.

Raises:

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

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

Calculates the energy probability (in logE) of each event.

Parameters:

  • tdm (instance of TrialDataManager) –

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

    • ’log_energy’float

      The logarithm of the energy value of the event.

    • ’sin_dec’float

      The sin(declination) value of the event.

  • fitparams (None) – Unused interface parameter.

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

Returns:

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

skyllh.i3.pdfratio module

class skyllh.i3.pdfratio.I3EnergySigSetOverBkgPDFRatioSpline(signalpdfset, backgroundpdf, fillmethod=None, interpolmethod=None, ncpu=None, ppbar=None)

Bases: SigSetOverBkgPDFRatio, IsParallelizable

This class implements a signal over background PDF ratio spline for I3EnergyPDF enegry PDFs. It takes an object, which is derived from PDFSet for I3EnergyPDF PDF types, and which is derived from IsSignalPDF, as signal PDF. Furthermore, it takes an object, 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 fit parameters, which are defined by the signal PDF set.

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

Parameters:

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

  • backgroundpdf (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 (class of GridManifoldInterpolationMethod) – The class implementing the fit 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, fitparams, 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.

  • fitparams (dict) – The dictionary with the fit parameter values.

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

Returns:

ratio (1d ndarray of float) – The PDF ratio value for each given event.

get_gradient(tdm, fitparams, fitparam_name)

Retrieves the PDF ratio gradient for the pidx’th fit parameter.

Parameters:

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

  • fitparams (dict) – The dictionary with the fit parameter values.

  • fitparam_name (str) – The name of the fit parameter for which the gradient should get calculated.

skyllh.i3.scrambling module

class skyllh.i3.scrambling.I3TimeScramblingMethod(timegen)

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

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

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

Bases: SignalGenerationMethod

This class provides a signal generation method for a point-like source 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.

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.

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. The unit of the signal flux must be 1/(GeV cm^2 s sr).

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:

  • indices_list (list of 1D ndarrays) – The list of event indices arrays specifying which MC events have been selected as signal candidate events for each source of the given source hypothesis group. Hence, the length of that list is the number of sources of the source hypothesis group. The length of the different 1D ndarrays is variable and depends on the source.

  • flux_list (list of 1D ndarrays) – The list of 1D ndarrays holding the flux value of the selected signal candidate events. One array for each source of the given source hypothesis group. Hence, the length of that list is the number of sources of the source hypothesis group. The length of the different 1D ndarrays is variable and depends on the source.

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.

class skyllh.i3.signal_generation.MultiPointLikeSourceI3SignalGenerationMethod(src_sin_dec_half_bandwidth=0.01745240643728351, src_sin_dec_shift_func=None, energy_range=None, batch_size=200)

Bases: PointLikeSourceI3SignalGenerationMethod

This class provides a signal generation method for a multiple 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.

  • batch_size (int, optional) – Batch size for signal generation.

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. The unit of the signal flux must be 1/(GeV cm^2 s sr).

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_indices (1D ndarray) – Event indices array specifying which MC events have been selected as signal candidate events for each source of the given source hypothesis group. The length of the 1D ndarray is variable and depends on the source.

  • src_indices (1D ndarray) – Source indices array specifying which source corresponds to the event in ev_indices array.

  • flux_list (list of 1D ndarrays) – The list of 1D ndarrays holding the flux value of the selected signal candidate events. One array for each source of the given source hypothesis group. Hence, the length of that list is the number of sources of the source hypothesis group. The length of the different 1D ndarrays is variable and depends on the source.

skyllh.i3.signalpdf module

class skyllh.i3.signalpdf.SignalI3EnergyPDFSet(data_mc, logE_binning, sinDec_binning, fluxmodel, fitparam_grid_set, smoothing_filter=None, ncpu=None, ppbar=None)

Bases: PDFSet, IsSignalPDF, 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 are the parameters that influence the source flux model.

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

Parameters:

  • data_mc (instance of DataFieldRecordArray) –

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

    • ’true_energy’float

      The true energy value of the data event.

    • ’log_energy’float

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

    • ’dec’float

      The declination of the data event.

    • ’mcweight’float

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

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

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

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

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

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

  • ncpu (int | None (default)) – The number of CPUs to use to create the different I3EnergyPDF objects for the different fit parameter grid values.

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

assert_is_valid_for_exp_data(data_exp)

Checks if this signal energy PDF is valid for all the given experimental data. It checks if all the data is within the logE and sin(dec) binning range.

Parameters:

data_exp (numpy record ndarray) –

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

  • ’log_energy’float

    The logarithm of the energy value of the data event.

  • ’dec’float

    The declination of the data event.

Raises:

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

get_prob(tdm, gridfitparams)

Calculates the signal energy probability (in logE) of each event for a given set of signal fit parameters on a grid.

Parameters:

  • tdm (instance of TrialDataManager) –

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

    • ’log_energy’float

      The logarithm of the energy value of the event.

    • ’sin_dec’float

      The sin(declination) value of the event.

  • gridfitparams (dict) – The dictionary holding the signal parameter values for which the signal energy probability should be calculated. Note, that the parameter values must match a set of parameter grid values for which an I3EnergyPDF object has been created at construction time of this SignalI3EnergyPDF object. There is no interpolation method defined at this point to allow for arbitrary parameter values!

Returns:

prob (1d ndarray) – The array with the signal energy probability for each event.

Raises:

KeyError – If no energy PDF can be found for the given signal parameter values.