skyllh.core.utils package¶

Submodules¶

skyllh.core.utils.analysis module¶

skyllh.core.utils.coords module¶

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

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

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

skyllh.core.utils.coords.rotate_signal_events_on_sphere(src_ra, src_dec, evt_true_ra, evt_true_dec, evt_reco_ra, evt_reco_dec)¶

Rotate signal events on a sphere to a given source position preserving position angle and separation (great circle distance) between the event’s true and reco directions.

Parameters:

src_ra (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the true right-ascension of the source.
src_dec (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the true declination of the source.
evt_true_ra (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the true right-ascension of the MC event.
evt_true_dec (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the true declination of the MC event.
evt_reco_ra (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the reconstructed right-ascension of the MC event.
evt_reco_dec (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the reconstructed declination of the MC event.

Returns:

rot_evt_reco_ra (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the rotated reconstructed event right-ascension.
rot_evt_reco_dec (instance of numpy.ndarray) – The (N_events,)-shaped 1D numpy.ndarray holding the rotated reconstructed event declination.

skyllh.core.utils.coords.angular_separation(ra1, dec1, ra2, dec2, psi_floor=None)¶

Calculates the angular separation on the sphere between two vectors on the sphere.

Parameters:

ra1 (instance of numpy.ndarray) – The (N_events,)-shaped numpy.ndarray holding the right-ascension or longitude coordinate of the first vector in radians.
dec1 (instance of numpy.ndarray) – The (N_events,)-shaped numpy.ndarray holding declination or latitude coordinate of the first vector in radians.
ra2 (instance of numpy.ndarray) – The (N_events,)-shaped numpy.ndarray holding the right-ascension or longitude coordinate of the second vector in radians.
dec2 (instance of numpy.ndarray) – The (N_events,)-shaped numpy.ndarray holding declination coordinate of the second vector in radians.
psi_floor (float | None) – If not None, specifies the floor value of psi.

Returns:

psi (instance of numpy.ndarray) – The (N_events,)-shaped numpy.ndarray holding the calculated angular separation value of each event.

skyllh.core.utils.flux_model module¶

skyllh.core.utils.flux_model.create_scipy_stats_rv_continuous_from_TimeFluxProfile(profile)¶

This function builds a scipy.stats.rv_continuous instance for a given TimeFluxProfile instance.

It can be used to generate random numbers according to the given time flux profile function.

Parameters:: profile (instance of TimeFluxProfile) – The instance of TimeFluxProfile providing the function of the time flux profile.
Returns:: rv (instance of rv_continuous_frozen) – The instance of rv_continuous_frozen representing the time flux profile as a continuous random variate instance.

skyllh.core.utils.multidimgridpdf module¶

This module contains utility functions for creating and managing MultiDimGridPDF instances.

skyllh.core.utils.multidimgridpdf.get_kde_pdf_sig_spatial_norm_factor_func(log10_psi_name='log10_psi')¶

Returns the standard normalization factor function for the spatial signal MultiDimGridPDF, which is created from KDE PDF values. It can be used for the norm_factor_func argument of the create_MultiDimGridPDF_from_photosplinetable and create_MultiDimGridPDF_from_kde_pdf function.

Parameters:: log10_psi_name (str) – The name of the event data field for the log10(psi) values.

skyllh.core.utils.multidimgridpdf.get_kde_pdf_bkg_norm_factor_func()¶: Returns the standard normalization factor function for the background MultiDimGridPDF, which is created from KDE PDF values. It can be used for the norm_factor_func argument of the create_MultiDimGridPDF_from_photosplinetable and create_MultiDimGridPDF_from_kde_pdf function.

skyllh.core.utils.multidimgridpdf.create_MultiDimGridPDF_from_photosplinetable(multidimgridpdf_cls, pmm, ds, data, info_key, splinetable_key, kde_pdf_axis_name_map_key='KDE_PDF_axis_name_map', norm_factor_func=None, cache_pd_values=False, tl=None, **kwargs)¶

Creates a MultiDimGridPDF instance with pdf values taken from a photospline pdf, i.e. a spline interpolation of KDE PDF values stored in a splinetable on disk.

Parameters:

multidimgridpdf_cls (subclass of MultiDimGridPDF) – The MultiDimGridPDF class, which should be used.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, which defines the mapping of global parameters to local model parameters.
ds (instance of Dataset) – The instance of Dataset the PDF applies to.
data (instance of DatasetData) – The instance of DatasetData that holds the experimental and monte-carlo data of the dataset.
info_key (str) – The auxiliary data name for the file containing PDF information.
splinetable_key (str) – The auxiliary data name for the name of the file containing the photospline spline table.
kde_pdf_axis_name_map_key (str) – The auxiliary data name for the KDE PDF axis name map.
norm_factor_func (callable | None) – The function that calculates a possible required normalization factor for the PDF value based on the event properties. For more information about this argument see the documentation of the skyllh.core.pdf.MultiDimGridPDF.__init__() method.
cache_pd_values (bool) – Flag if the probability density values should get cached by the MultiDimGridPDF class.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pdf (instance of multidimgridpdf_cls) – The created PDF instance of MultiDimGridPDF.

skyllh.core.utils.multidimgridpdf.create_MultiDimGridPDF_from_kde_pdf(multidimgridpdf_cls, pmm, ds, data, numerator_key, denumerator_key=None, kde_pdf_axis_name_map_key='KDE_PDF_axis_name_map', norm_factor_func=None, cache_pd_values=False, tl=None, **kwargs)¶

Creates a MultiDimGridPDF instance with pdf values taken from KDE PDF values stored in the dataset’s auxiliary data.

Parameters:

multidimgridpdf_cls (subclass of MultiDimGridPDF) – The MultiDimGridPDF class, which should be used.
pmm (instance of ParameterModelMapper) – The instance of ParameterModelMapper, which defines the mapping of global parameters to local model parameters.
ds (instance of Dataset) – The instance of Dataset the PDF applies to.
data (instance of DatasetData) – The instance of DatasetData that holds the auxiliary data of the dataset.
numerator_key (str) – The auxiliary data name for the PDF numerator array.
denumerator_key (str | None) – The auxiliary data name for the PDF denumerator array. This can be None, if no denumerator array is required.
kde_pdf_axis_name_map_key (str) – The auxiliary data name for the KDE PDF axis name map.
norm_factor_func (callable | None) – The function that calculates a possible required normalization factor for the PDF value based on the event properties. For more information about this argument see the documentation of the skyllh.core.pdf.MultiDimGridPDF.__init__() method.
cache_pd_values (bool) – Flag if the probability density values should get cached by the MultiDimGridPDF class.
tl (instance of TimeLord | None) – The optional instance of TimeLord to use for measuring timing information.

Returns:

pdf (instance of multidimgridpdf_cls) – The created PDF instance of MultiDimGridPDF.

skyllh.core.utils.spline module¶

skyllh.core.utils.spline.make_spline_1d(x, y, kind='linear', **kwargs)¶

Creates a 1D spline for the function y(x) using scipy.interpolate.interp1d.

Parameters:

x (array_like) – The x values.
y (array_like) – The y values.
kind (str) – The kind of the spline. See the scipy.interpolate.interp1d documentation for possible values. Default is 'linear'.
**kwargs – Additional keyword arguments are passed to the interp1d function.

Returns:

spline – The created 1D spline instance.

class skyllh.core.utils.spline.CatmullRomRegular1DSpline(x, y, **kwargs)¶

Bases: object

This class provides a one-dimensional Catmull-Rom spline which is a C^1 continous spline, where the control points coincide with the data points. The x data points need to be equal distant.

Note

The first and last data point are not part of the splined curve!

Creates a new CatmullRom1DSpline instance.

Parameters:

x (instance of ndarray) – The x values of the data points.
y (instance of ndarray) – The y values of the data points.

__call__(x, oor_value=nan)¶

Evaluates the spline given x-values in data coordinates.

Parameters:: x (instance of ndarray) – The instance of ndarray holding the values for which the spline should get evaluated.
Returns:: y (instance of ndarray) – The instance of ndarray with the spline values at the given x values.

__annotations_cache__ = {}¶

__firstlineno__ = 56¶

__static_attributes__ = ('_delta_x', '_num_segments', '_segment_data', '_x_start', '_x_stop')¶

skyllh.core.utils.tdm module¶

skyllh.core.utils.tdm.get_tdm_field_func_psi(psi_floor=None)¶

Returns the TrialDataManager (TDM) field function for psi with an optional psi value floor.

Parameters:: psi_floor (float | None) – The optional floor value for psi. This should be None for a standard point-source analysis that uses an analytic function for the detector’s point-spread-function (PSF).
Returns:: tdm_field_func_psi (function) – TrialDataManager (TDM) field function for psi.

skyllh.core.utils.trials module¶

This module contains utility functions related analysis trials.

skyllh.core.utils.trials.create_pseudo_data_file(ana, rss, filename, mean_n_bkg_list=None, mean_n_sig=0, bkg_kwargs=None, sig_kwargs=None, tl=None)¶

Creates a pickle file that contains the pseudo data for a single trial by generating background and signal events.

Parameters:

ana (Analysis) – The Analysis instance that should be used to generate the pseudo data.
rss (RandomStateService) – The RandomStateService instance to use for generating random numbers.
filename (str) – The data file name into which the generated pseudo data should get written to.
mean_n_bkg_list (list of float | None) – The mean number of background events that should be generated for each dataset. If set to None (the default), the background generation method needs to obtain this number itself.
mean_n_sig (float) – The mean number of signal events that should be generated for the trial. The actual number of generated events will be drawn from a Poisson distribution with this given signal mean as mean.
bkg_kwargs (dict | None) – Additional keyword arguments for the generate_events method of the background generation method class. An usual keyword argument is poisson.
sig_kwargs (dict | None) – Additional keyword arguments for the generate_signal_events method of the SignalGenerator class. An usual keyword argument is poisson.
tl (TimeLord | None) – The instance of TimeLord that should be used to time individual tasks.

skyllh.core.utils.trials.load_pseudo_data(filename, tl=None)¶

Loads the pseudo data for a single trial from the given file name.

Parameters:

filename (str) – The name of the file that contains the pseudo data.
tl (TimeLord | None) – The instance of TimeLord that should be used to time individual tasks.

Returns:

mean_n_sig (float) – The mean number of signal events that was used to generate the pseudo data.
n_sig (int) – The actual total number of signal events in the pseudo data.
n_bkg_events_list (list of int) – The total number of background events for each data set of the pseudo data.
n_sig_events_list (list of int) – The total number of signal events for each data set of the pseudo data.
bkg_events_list (list of DataFieldRecordArray instances) – The list of DataFieldRecordArray instances containing the background pseudo data events for each data set.
sig_events_list (list of DataFieldRecordArray instances | None) – The list of DataFieldRecordArray instances containing the signal pseudo data events for each data set. If a particular dataset has no signal events, the entry for that dataset can be None.