skyllh.p1 package

Submodules

skyllh.p1.detector_model module

This module defines the P-ONE detector model class.

class skyllh.p1.detector_model.PONEDetectorModel(**kwargs)

Bases: DetectorModel

Definition of the P-ONE detector.

For the time being we use the position of STRAW-a. As depth we use the sea floor at -2658m and a detector half height of 500m.

Creates a new DetectorModel instance.

Parameters:

name (str) – The name of the detector model.
location (instance of astropy.coordinates.EarthLocation) – The Earth location of the detector.

skyllh.p1.signal_generation module

class skyllh.p1.signal_generation.PointLikeSourceSignalGenerationMethod(equ_to_hor_transform, band_deg_alt_range=1.0, src_batch_size=128, energy_range=None, **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:

equ_to_hor_transform (callable) –
The transformation function to transform coordinates from the equatorial system into the horizontal system.

The call signature must be:

__call__(ra, dec, mjd)

The return signature must be: (azi, alt)
band_deg_alt_range (float) – The width of the alt band to take MC events from around a source altitude position in AltAz coordinates.
energy_range (2-element tuple of float | None) – The energy range from which to take MC events into account for signal event generation. If set to None, the entire energy range [0, +inf] is used.
src_batch_size (int) – The source processing batch size used for the signal event flux calculation.

calc_source_signal_mc_event_flux(data_mc, shg, obstime)

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

Parameters:

data_mc (numpy record ndarray) – The numpy record array holding the MC events of a dataset.
shg (SourceHypoGroup instance) – The source hypothesis group, which defines the list of sources, and their flux model.
obs_time (float) – The mjd random observation time from detector livetime drawn in generate events

Returns:

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

signal_event_post_sampling_processing(shg, obstime, 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.
obstime (float) – The mjd random observation time from detector livetime drawn in generate events
shg_sig_events (numpy record ndarray) – The numpy record ndarray holding the generated signal events for the given source hypothesis group and in the format of the original MC events.

Returns:

shg_sig_events (numpy record ndarray) – The numpy record ndarray with the processed MC signal events.

skyllh.p1.signal_generator module

class skyllh.p1.signal_generator.SignalGenerator(shg_mgr, **kwargs)

Bases: HasConfig

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

Constructs a new signal generator instance.

Parameters:: shg_mgr (instance of SourceHypoGroupManager) – The SourceHypoGroupManager instance defining the source hypothesis groups.

property shg_mgr: The SourceHypoGroupManager instance defining the source hypothesis groups.

create_src_params_recarray(src_detsigyield_weights_service)

Creates the src_params_recarray structured ndarray of length N_sources holding the local source parameter names and values needed for the calculation of the detector signal yields.

Parameters:: src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService) – The instance of SrcDetSigYieldWeightsService providing the product of the source weights with the detector signal yield.
Returns:: src_params_recarray (instance of numpy structured ndarray) – The structured numpy ndarray of length N_sources, holding the local parameter names and values of each source needed to calculate the detector signal yield.

change_shg_mgr(shg_mgr): Changes the source hypothesis group manager. Derived classes can reimplement this method but this method of the base class must still be called by the derived class.

abstract generate_signal_events(rss, mean, poisson=True, src_detsigyield_weights_service=None)

This abstract method must be implemented by the derived class to generate a given number of signal events.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (int | float) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean specifies the actual number of generated signal events.
src_detsigyield_weights_service (instance of SrcDetSigYieldWeightsService | None) – The instance of SrcDetSigYieldWeightsService providing the weighting of the sources within the detector. This can be None if this signal generator does not need this information.

Returns:

n_signal (int) – The number of generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.

class skyllh.p1.signal_generator.MultiDatasetSignalGenerator(shg_mgr, dataset_list, data_list, sig_generator_list=None, ds_sig_weight_factors_service=None, **kwargs)

Bases: SignalGenerator

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

Constructs a new signal generator handling multiple datasets.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The instance of SourceHypoGroupManager that defines the list of source hypothesis groups, i.e. the list of sources.
dataset_list (list of instance of Dataset) – The list of instance of Dataset for which signal events should get generated.
data_list (list of instance of DatasetData) – The list of instance of DatasetData holding the actual data of each dataset. The order must match the order of dataset_list.
sig_generator_list (list of instance of SignalGenerator | None) – The optional list of instance of SignalGenerator holding signal generator instances for each individual dataset. This can be None if this signal generator does not require individual signal generators for each dataset.
ds_sig_weight_factors_service (instance of DatasetSignalWeightFactorsService) – The instance of DatasetSignalWeightFactorsService providing the dataset signal weight factor service for calculating the dataset signal weights.

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

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

property sig_generator_list: The list of instance of SignalGenerator holding signal generator instances for each individual dataset.

property ds_sig_weight_factors_service: The instance of DatasetSignalWeightFactorsService providing the dataset signal weight factor service for calculating the dataset signal weights.

property n_datasets: (read-only) The number of datasets.

change_shg_mgr(shg_mgr): Changes the source hypothesis group manager. This will recreate the src_params_recarray needed for calculating the detector signal yields. Also it calls the change_shg_mgr methods of the signal generators of the individual datasets.

generate_signal_events(rss, mean, poisson=True, **kwargs)

Generates a given number of signal events distributed across the individual datasets.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (float | int) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean must be an integer and specifies the actual number of generated signal events.

Returns:

n_signal (int) – The number of actual generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.

class skyllh.p1.signal_generator.MCMultiDatasetSignalGenerator(shg_mgr, dataset_list, data_list, valid_event_field_ranges_dict_list=None, **kwargs)

Bases: MultiDatasetSignalGenerator

This is a signal generator class, which handles multiple datasets with monte-carlo (MC). It uses the MC events of all datasets to determine the possible signal events for a source. It does not depend on the detector or source hypothesis, because these dependencies are factored out into the signal generation method. In fact the construction within this class depends on the construction of the signal generation method.

Constructs a new signal generator instance.

Parameters:

shg_mgr (instance of SourceHypoGroupManager) – The SourceHypoGroupManager instance defining the source hypothesis groups.
dataset_list (list of Dataset instances) – The list of Dataset instances for which signal events should get generated for.
data_list (list of DatasetData instances) – The list of DatasetData instances holding the actual data of each dataset. The order must match the order of dataset_list.
valid_event_field_ranges_dict_list (list of dict | None) – If not None, it specifies for each dataset event fields (key) and their valid value range as a 2-element tuple (value). If a generated signal event does not fall into a given field range, the signal event will be discarded and a new signal event will be drawn.

property valid_event_field_ranges_dict_list: The list of dictionary holding the event data fields (key) and their valid value range as 2-element tuple (value).

change_shg_mgr(shg_mgr): Recreates the signal candidates with the changed source hypothesis group manager.

mu2flux(mu, per_source=False)

Translate the mean number of signal events mu into the corresponding flux. The unit of the returned flux is the internally used flux unit.

Parameters:

mu (float) – The mean number of expected signal events for which to get the flux.
per_source (bool) – Flag if the flux should be returned for each source individually (True), or as the sum of all these fluxes (False). The default is False.

Returns:

mu_flux (float | (n_sources,)-shaped numpy ndarray) – The total flux for all sources (if per_source = False) that would correspond to the given mean number of detected signal events mu. If per_source is set to True, a numpy ndarray is returned that contains the flux for each individual source.

generate_signal_events(rss, mean, poisson=True, **kwargs)

Generates a given number of signal events from the signal candidate monte-carlo events.

Parameters:

rss (instance of RandomStateService) – The instance of RandomStateService providing the random number generator state.
mean (float | int) – The mean number of signal events. If the poisson argument is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with this given mean value of signal events.
poisson (bool) – If set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean value of signal events. If set to False, the argument mean must be an integer and specifies the actual number of generated signal events.

Returns:

n_signal (int) – The number of actual generated signal events.
signal_events_dict (dict of DataFieldRecordArray) – The dictionary holding the DataFieldRecordArray instances with the generated signal events. Each key of this dictionary represents the dataset index for which the signal events have been generated.