skyllh.i3.utils package

Submodules

skyllh.i3.utils.analysis module

skyllh.i3.utils.analysis.generate_ps_sin_dec_h0_ts_values(ana, rss, sin_dec_min, sin_dec_max, sin_dec_step, n_bkg_trials=10000, n_iter=1, bkg_kwargs=None, ppbar=None)

Generates sets of null-hypothesis, i.e. background-only trial data events, test-statistic values for the given point-source analysis for a grid of sin(dec) values. These ts values can the be used for the estimate_ps_sin_dec_sensitivity_curve and estimate_ps_sin_dec_discovery_potential_curve functions.

Parameters:

  • ana (Analysis instance) – The instance of Analysis to use for generating trials.

  • rss (RandomStateService instance) – The instance of RandomStateService to use for generating random numbers from.

  • sin_dec_min (float) – The minimum sin(dec) value for creating the sin(dec) value grid.

  • sin_dec_max (float) – The maximum sin(dec) value for creating the sin(dec) value grid.

  • sin_dec_step (float) – The step size in sin(dec) for creating the sin(dec) value grid.

  • n_bkg_trials (int, optional) – The number of background trials to generate. Default is 10000.

  • n_iter (int, optional) – Each set of ts values can be calculated several times to be able to estimate the variance of the sensitivity / discovery potential. This parameter specifies the number of iterations to perform. For each iteration the RandomStateService is re-seeded with a seed that is incremented by 1. Default is 1.

  • bkg_kwargs (dict | None) – Additional keyword arguments for the generate_events method of the background generation method class. An usual keyword argument is poisson.

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

Returns:

  • sin_dec_arr ((n_sin_dec,)-shaped 1D ndarray of float) – The numpy ndarray holding the sin(dec) values for which the ts values have been calculated.

  • h0_ts_vals_arr ((n_sin_dec,n_iter,n_bkg_trials)-shaped 3D ndarray of float) – The numpy ndarray holding the null-hypothesis ts values for all sin(dec) values and iterations.

skyllh.i3.utils.analysis.estimate_ps_sin_dec_sensitivity_curve(ana, rss, fitparam_values, sin_dec_arr, h0_ts_vals_arr, eps_p=0.0075, mu_min=0, mu_max=20, n_iter=1, bkg_kwargs=None, sig_kwargs=None, ppbar=None, **kwargs)

Estimates the point-source sensitivity of the given analysis as a function of sin(dec). This function places a PointLikeSource source on the given declination values and estimates its sensitivity.

Parameters:

  • ana (Analysis instance) – The instance of Analysis to use for generating trials.

  • rss (RandomStateService instance) – The instance of RandomStateService to use for generating random numbers from.

  • fitparam_values (array_like) – The fit parameter values for which to convert the mean number of signal events into a flux.

  • sin_dec_arr ((n_sin_dec,)-shaped 1D ndarray) – The ndarray holding the sin(dec) values for which to estimate the point-source sensitivity.

  • h0_ts_vals_arr ((n_sin_dec,n_iter,n_bkg_trials)-shaped 3D ndarray of float) – The numpy ndarray holding the null-hypothesis ts values for all sin(dec) values and iterations.

  • eps_p (float, optional) – The precision in probability used for the estimate_sensitivity function. Default is 0.0075.

  • mu_min (float, optional) – The minimum value for the mean number of injected signal events as a seed for the mu range in which the sensitivity is located. Default is 0.

  • mu_max (float, optional) – The maximum value for the mean number of injected signal events as a seed for the mu range in which the sensitivity is located. Default is 20.

  • n_iter (int, optional) – Each sensitivity can be estimated several times to be able to estimate the variance of the sensitivity. This parameter specifies the number of iterations to perform for each sensitivity. For each iteration the RandomStateService is re-seeded with a seed that is incremented by 1. Default is 1.

  • 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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the given mean number of signal events.

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

  • Arguments (Additional Keyword) –

  • ---------------------------- –

  • estimate_sensitivity (Any additional keyword arguments are passed to the) –

  • function. –

Returns:

  • sin_dec_arr ((n_sin_dec,)-shaped 1D ndarray) – The ndarray holding the sin(dec) values for which the sensitivities have been estimated.

  • mean_ns_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the mean number of signal events corresponding to the sensitivity for each sin(dec) value and iteration.

  • mean_ns_err_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the estimated error in mean_ns for each sin(dec) value and iteration.

  • flux_scaling_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the scaling factor the reference flux needs to get scaled to obtain the flux for the estimated sensitivity.

skyllh.i3.utils.analysis.estimate_ps_sin_dec_discovery_potential_curve(ana, rss, fitparam_values, sin_dec_arr, h0_ts_vals_arr, h0_ts_quantile=0.0027, eps_p=0.0075, mu_min=0, mu_max=20, n_iter=1, bkg_kwargs=None, sig_kwargs=None, ppbar=None, **kwargs)

Estimates the point-source discovery potential of the given analysis as a function of sin(dec). This function places a PointLikeSource source on the given declination values and estimates its discovery potential.

Parameters:

  • ana (Analysis instance) – The instance of Analysis to use for generating trials.

  • rss (RandomStateService instance) – The instance of RandomStateService to use for generating random numbers from.

  • fitparam_values (array_like) – The fit parameter values for which to convert the mean number of signal events into a flux.

  • sin_dec_arr ((n_sin_dec,)-shaped 1D ndarray) – The ndarray holding the sin(dec) values for which to estimate the point-source sensitivity.

  • h0_ts_vals_arr ((n_sin_dec,n_iter,n_bkg_trials)-shaped 3D ndarray of float) – The numpy ndarray holding the null-hypothesis ts values for all sin(dec) values and iterations.

  • h0_ts_quantile (float, optional) – Null-hypothesis test statistic quantile that defines the critical value. For a 5sigma discovery potential that value is 5.733e-7. For a 3sigma discovery potential this value is 2.7e-3. Default is 2.7e-3.

  • eps_p (float, optional) – The precision in probability used for the estimate_discovery_potential function. Default is 0.0075.

  • mu_min (float, optional) – The minimum value for the mean number of injected signal events as a seed for the mu range in which the sensitivity is located. Default is 0.

  • mu_max (float, optional) – The maximum value for the mean number of injected signal events as a seed for the mu range in which the sensitivity is located. Default is 20.

  • n_iter (int, optional) – Each discovery potential can be estimated several times to be able to estimate its variance. This parameter specifies the number of iterations to perform for each discovery potential estimation. For each iteration the RandomStateService is re-seeded with a seed that is incremented by 1. Default is 1.

  • 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. If poisson is set to True, the actual number of generated signal events will be drawn from a Poisson distribution with the mean number of signal events, mu.

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

  • Arguments (Additional Keyword) –

  • ---------------------------- –

  • the (Any additional keyword arguments are passed to) –

  • function. (estimate_discovery_potential) –

Returns:

  • sin_dec_arr ((n_sin_dec,)-shaped 1D ndarray) – The ndarray holding the sin(dec) values for which the discovery potential have been estimated.

  • mean_ns_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the mean number of signal events corresponding to the discovery potential for each sin(dec) value and iteration.

  • mean_ns_err_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the estimated error in mean_ns for each sin(dec) value and iteration.

  • flux_scaling_arr ((n_sin_dec,n_iter)-shaped 2D ndarray) – The ndarray holding the scaling factor the reference flux needs to get scaled to obtain the flux for the estimated discovery potential.

skyllh.i3.utils.coords module

IceCube specific coordinate utility functions.

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

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

Parameters:

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

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

Returns:

ra (instance of numpy.ndarray) – The right-ascension values.

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

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

Parameters:

  • ra (instance of numpy.ndarray) – The array with the right-ascension angles.

  • mjd (instance of numpy.ndarray) – The array with the MJD times for each right-ascension angle.

Returns:

azi (instance of numpy.ndarray) – The azimuth angle for each right-ascension angle.

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

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

Parameters:
Returns:

  • ra (instance of numpy.ndarray) – The right-ascension angle.

  • dec (instance of numpy.ndarray) – The declination angle.