llama.files.coinc_significance.utils module

Utility functions for calculating significance of joint events.

NOTE: equations after 8 increment up by 1. equations after 22 increment up by 2.

@author: dvesk, stefco

llama.files.coinc_significance.utils.Aeff(e, theta)
llama.files.coinc_significance.utils.Aeff_skymap(skymap, enu)

Get the energy- and direction-dependent effective areas of the neutrino detector for every direction provided in skymap (Eq. 21, 22)

Parameters

  • skymap (llama.files.healpix.HEALPixSkyMap) – A HEALPixSkyMap instance with defined right-ascensions and declinations.

  • enu (float) – The reconstructed neutrino energy.

llama.files.coinc_significance.utils.Pempgw(ρgw, gw_bg_ρs)

The empirical neutrino background for a given GW SNR ρgw.

Parameters

  • ρgw (float) – The SNR of the current GW trigger.

  • gw_bg_ρs (RemoteFileCacher) – A file with a list of historical background SNR values.

llama.files.coinc_significance.utils.aeff_lookup_table()

Get a dictionary mapping from strings describing neutrino energy bounds to tuples of the form (factor, exponent) where factor is a lookup table of the constant factor multiplying the effective area (with indices representing 10-degree increments in the angle theta) and exponent is the exponent to which the neutrino energy e is raised (since we assume a rough power law for Aeff, again with indices representing 10-degree increments in the angle theta). The final value will be factor*e**exponent.

NOTE that we need to include an item for [180, 190) degrees because int(180./10) will give us 18, indexing into the 19th entry in the lookup table, and we want to include this edge case.

llama.files.coinc_significance.utils.angle_list()
llama.files.coinc_significance.utils.load_neutrino_background()

Load neutrino background data.

Returns

  • thetabg (array-like) – Array of background neutrino zenith angles [deg] as reconstructed by IceCube.

  • EGev (array-like) – Array of background neutrino energies [GeV] as reconstructed by IceCube.

llama.files.coinc_significance.utils.p_value(odds_ratio, search_type, population, sensitivity, instruments)

Calculate the p-value for a given odds ratio.

Parameters

  • odds_ratio (float) – The odds ratio for signal vs. background/null; is here being interpreted as a test statistic to make the analysis robust against constant factors in the priors.

  • search_type (str) – The type of search performed. This decides which background population will be used. Distinguishes between subthreshold, open public alert, and in the future, potentially other simulated backgrounds.

  • population (str) – The name of the source population against which this odds_ratio will be compared, e.g. ‘bns’ for binary neutron stars. NOTE: This just has to be set so that it references an existing group in the NEUTRINO_POPULATIONS HDF5 file; there are currently no explict standards for naming the population. See populations-hdf5-collater and the contents of the directory containing NEUTRINO_POPULATIONS for available options.

  • sensitivity (str) – The detector configuration and sensitivity used, e.g. ‘design’ for HLV at design sensitivity. See the NOTE on population for naming information.

  • instruments (list) – The instruments participating in this search as a list of detector names, e.g. [H1, L1, V1] for all three O3 GW detectors. If a background population is available for this set of instruments, it will be used; otherwise, at attempt will be made to use a population averaging over all sets of participating detectors (for populations where full separate cases could not be feasibly generated).

Returns

p_value – The p-value or false-alarm probability (FAP) of the given odds_ratio assuming the given source population and detector configuration. Returns None if a matching background does not yet exist for this search configuration.

Return type

float or NoneType

llama.files.coinc_significance.utils.r0(Egw, search_params)

Maximum GW detection distance for isotropic-equivalent emission energy Egw.

llama.files.coinc_significance.utils.search_parameters(population, instruments)

Return an IceCubeLvcSearchParameters instance with all default values and the given population and instruments.

populationstr

The name of the source population against which this odds_ratio will be compared, e.g. ‘bns’ for binary neutron stars. NOTE: This just has to be set so that it references an existing group in the NEUTRINO_POPULATIONS HDF5 file; there are currently no explict standards for naming the population. See populations-hdf5-collater and the contents of the directory containing NEUTRINO_POPULATIONS for available options.

instrumentslist

The GW detectors participating in this search as a list of detector names, e.g. [H1, L1, V1] for all three O3 GW detectors. If a background population is available for this set of instruments, it will be used; otherwise, at attempt will be made to use a population averaging over all sets of participating instruments (for populations where full separate cases could not be feasibly generated).

Returns

search_params – Default search parameter values along with the provided population and instruments.

Return type

IceCubeLvcSearchParameters

llama.files.coinc_significance.utils.t_overlap(tgw, tnu, search_params)

Integral of the source-time-dependent part of the likelihood integral (Eq. 5) finding the probability of getting tgw and tnu (the detection times of the gravitational wave trigger and neutrino trigger, respectively) given the specified search_params. Factors out from the rest of Eq. 5.