llama.files.i3 package¶

FileHandler classes and utilities associated with retrieving GFU neutrino data from IceCube (see: llama.detectors.IceCube).

class llama.files.i3.Neutrino(**kwargs)¶

Bases: object

A class for holding neutrino trigger data in easily accessible form.: Also provides convenience methods for coordinate conversions of underlying data. Good for plugging values into formulae.

All properties listed are REQUIRED and must be passed as kwargs.

mjd(independent): Modified Julian Date in UTC epoch at which the neutrino candidate was detected.
zenith(independent): Zenith angle of neutrino source direction, measured from IceCube’s location at South Pole.
azimuth(independent): Azimuthal angle of neutrino source direction, measured from IceCube’s location at South Pole.
energy(independent): Reconstructed energy of the neutrino candidate in GeV.
sigma(independent): Effective uncertainty radius in degrees.
gps(dependent): GPS time, i.e. number of GPS seconds since start of GPS epoch, when the neutrino candidate was detected.
ra(dependent): Right Ascension of neutrino candidate in degrees.
dec(dependent): Declination of neutrino candidate in degrees.
psf(dependent): A Psf object for this neutrino that can be used to take products of this neutrino’s localization PSF with other skymap objects.

property azimuth¶: (independent) Azimuthal angle of neutrino source direction, measured from

IceCube’s location at South Pole.

property dec¶: (dependent) Declination of neutrino candidate in degrees.

property energy¶: (independent) Reconstructed energy of the neutrino candidate in GeV.

property gps¶: (dependent) GPS time, i.e. number of GPS seconds since start of GPS epoch, when

the neutrino candidate was detected.

property mjd¶: (independent) Modified Julian Date in UTC epoch at which the neutrino candidate

was detected.

property psf¶: (dependent) A Psf object for this neutrino that can be used to take products of this

neutrino’s localization PSF with other skymap objects.

property ra¶: (dependent) Right Ascension of neutrino candidate in degrees.

property sigma¶: (independent) Effective uncertainty radius in degrees.

property zenith¶: (independent) Zenith angle of neutrino source direction, measured from

IceCube’s location at South Pole.

class llama.files.i3.IceCubeNeutrinoList¶

Bases: llama.filehandler.JSONFile, llama.files.healpix.skymap.HEALPixPSF

Required input files for llama.files.i3.json.IceCubeNeutrinoList (located on the far right of the graph). For a typical trigger, the leftmost files will be generated as triggers become available. They will be used as input for files to their right, eventually allowing llama.files.i3.json.IceCubeNeutrinoList to be generated.¶

Takes a list of dictionaries describing neutrinos and saves it to a text file. Validates the neutrino data to make sure each neutrino contains (minimally) the following properties:

mjd
zenith
azimuth
sigma
energy
type (one the values found in NEUTRINO_TYPES)

If this file is generated within the temporal search window for neutrinos, it is possible not all neutrinos needed for the final result will be available. In this case, the file will automatically become obsolete and will be regenerated after the window has elapsed.

Neutrinos from IceCube can be delayed due to communications issues; to combat this, when neutrinos are pulled from the online data stream after the temporal search window has elapsed, a check will be run to see if the next neutrino after the end of the search window is yet available. If it is not available, it is assumed that not all neutrinos needed for the search have arrived from south pole, and a GenerationError will be raised, allowing the pipeline to cooldown and retry the neutrino pull later.

Neutrinos pulled from before MJD_TOPIC_SWITCH_17_TO_BLANK will be automatically pulled from local GFU archives (stored online on LLAMA S3 and cached locally after use in llama.utils.CACHEDIR in *.npy format). Neutrinos from after this date will be pulled from the online GFU stream.

DEPENDENCIES = (<class 'llama.files.skymap_info.SkymapInfo'>,)¶

DETECTORS = (Detector(name='IceCube', abbrev='i3', fullname='IceCube', url='http://wiki.icecube.wisc.edu', summary='IceCube', description='', citations=ImmutableDict({})),)¶

FILENAME = 'icecube_neutrino_list.json'¶

MANIFEST_TYPES = (<class 'llama.files.i3.json.IceCubeNeutrinoList'>,)¶

UR_DEPENDENCIES = (<class 'llama.files.skymap_info.SkymapInfo'>,)¶

UR_DEPENDENCY_TREE = frozenset({<class 'llama.files.skymap_info.SkymapInfo'>})¶

downselect(ra=None, dec=None, ntype=None)¶

Downselect the neutrino list to match given criteria. Save the old neutrino list with the original filename prefixed by a timestamp and replace it with the downselected list.

Parameters

ra (list) – Right-ascension intervals (in degrees) that the neutrinos must fall into, e.g. [(21, 41),(92, 102)]
dec (list) – Decliination intervals (in degrees) that the neutrinos must fall into, e.g. [(-3, 20)]
ntype (str) – A type that the neutrino must match, e.g. 'observation' for real neutrinos.

end_of_neutrino_window()¶: The GPS time at which all neutrinos should be in under normal circumstances.

is_complete()¶: Whether the list of neutrinos is complete. Assumes incomplete if no complete key specified.

is_obsolete(checked=None, **kwargs)¶: IceCubeNeutrinoList files can be fetched immediately after a GW event becomes available. However, we want to eventually run our analysis on all neutrinos in a certain time window around an event. We therefore want to re-fetch the neutrinos in that time window after the time window has passed (allowing a safety factor for the IceCube GFU API to process new neutrino triggers). To do this, we mark the IceCubeNeutrinoList as obsolete if the current time is after the time window + safety margin has elapsed and the neutrino list was generated before that time had passed (meaning there might have been new neutrinos saved that are useful for the analysis after the file was originally generated). Standard FileHandler obsolescence criteria are also used to determine obsolescence through a call to super.

property neutrinos¶: Return a list containing a Neutrino object for each neutrino; more convenient to work with when writing formulae than dealing directly with the neutrino dictionaries.

property num_triggers¶: The number of triggers described by this file. Useful mostly for quickly determining if this trigger list is empty.

source_locations()¶: Returns a list of tuples of (RA, Dec, sigma) for all point-like sources, where (RA, Dec) is the central sky position and sigma is the standard deviation of the Gaussian PSF. Since this depends on the structure of data in the relevant file handler, it must be specified for each subclass.

property template_skymap_filehandler¶: The HEALPixSkyMapFileHandler whose HEALPix parameters should be used as a template for the HEALPixSkyMap output by this FileHandler. It is assumed that this HEALPixSkyMapFileHandler only returns one skymap in its list; consequently, only the first skymap loaded by this file handler will be used. Note that the template skymap file handler is likely not a dependency of this file handler; it is only used as a default for formatting generated skymaps from this file handler’s data.

class llama.files.i3.IceCubeNeutrinoListTex¶

Bases: llama.filehandler.FileHandler

Required input files for llama.files.i3.tex.IceCubeNeutrinoListTex (located on the far right of the graph). For a typical trigger, the leftmost files will be generated as triggers become available. They will be used as input for files to their right, eventually allowing llama.files.i3.tex.IceCubeNeutrinoListTex to be generated.¶

A list of neutrinos and their reconstructed properties as well as the significance of the joint event) in LaTeX format suitable for use in papers and coincident skymap summary plots.

DEPENDENCIES = (<class 'llama.files.i3.json.IceCubeNeutrinoList'>, <class 'llama.files.skymap_info.SkymapInfo'>, <class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>)¶

FILENAME = 'IceCubeNeutrinoList.tex'¶

MANIFEST_TYPES = (<class 'llama.files.i3.tex.IceCubeNeutrinoListTex'>,)¶

UR_DEPENDENCIES = (<class 'llama.files.skymap_info.SkymapInfo'>, <class 'llama.files.lvc_skymap.LvcSkymapFits'>, <class 'llama.files.i3.json.IceCubeNeutrinoList'>, <class 'llama.files.gracedb.LVCGraceDbEventData'>, <class 'llama.files.lvc_skymap.LvcDistancesJson'>, <class 'llama.files.lvc_skymap.LvcSkymapHdf5'>, <class 'llama.files.gracedb.PAstro'>, <class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>)¶

UR_DEPENDENCY_TREE = ImmutableDict({<class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>: ImmutableDict({<class 'llama.files.gracedb.PAstro'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.lvc_skymap.LvcSkymapHdf5'>: ImmutableDict({<class 'llama.files.lvc_skymap.LvcSkymapFits'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.lvc_skymap.LvcDistancesJson'>: ImmutableDict({<class 'llama.files.lvc_skymap.LvcSkymapFits'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({}), <class 'llama.files.gracedb.LVCGraceDbEventData'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.i3.json.IceCubeNeutrinoList'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.i3.json.IceCubeNeutrinoList'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})¶

class llama.files.i3.IceCubeNeutrinoListTxt¶

Bases: llama.filehandler.FileHandler

Required input files for llama.files.i3.txt.IceCubeNeutrinoListTxt (located on the far right of the graph). For a typical trigger, the leftmost files will be generated as triggers become available. They will be used as input for files to their right, eventually allowing llama.files.i3.txt.IceCubeNeutrinoListTxt to be generated.¶

A space-delimited, table-formatted list of neutrinos formatted for human consumption in GCN Circulars.

DEPENDENCIES = (<class 'llama.files.i3.json.IceCubeNeutrinoList'>, <class 'llama.files.skymap_info.SkymapInfo'>)¶

FILENAME = 'icecube_neutrino_list.txt'¶

MANIFEST_TYPES = (<class 'llama.files.i3.txt.IceCubeNeutrinoListTxt'>,)¶

UR_DEPENDENCIES = (<class 'llama.files.skymap_info.SkymapInfo'>, <class 'llama.files.i3.json.IceCubeNeutrinoList'>)¶

UR_DEPENDENCY_TREE = ImmutableDict({<class 'llama.files.i3.json.IceCubeNeutrinoList'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})¶

class llama.files.i3.IceCubeNeutrinoListCoincTxt¶

Bases: llama.filehandler.FileHandler

Required input files for llama.files.i3.txt.IceCubeNeutrinoListCoincTxt (located on the far right of the graph). For a typical trigger, the leftmost files will be generated as triggers become available. They will be used as input for files to their right, eventually allowing llama.files.i3.txt.IceCubeNeutrinoListCoincTxt to be generated.¶

A space-delimited, table-formatted list of neutrinos meant for human consumption in GCN Circulars. Contains coincidence significance measures in addition to the base neutrino properties.

DEPENDENCIES = (<class 'llama.files.i3.json.IceCubeNeutrinoList'>, <class 'llama.files.skymap_info.SkymapInfo'>, <class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>)¶

FILENAME = 'icecube_neutrino_list_coinc.txt'¶

MANIFEST_TYPES = (<class 'llama.files.i3.txt.IceCubeNeutrinoListCoincTxt'>,)¶

UR_DEPENDENCIES = (<class 'llama.files.skymap_info.SkymapInfo'>, <class 'llama.files.lvc_skymap.LvcSkymapFits'>, <class 'llama.files.i3.json.IceCubeNeutrinoList'>, <class 'llama.files.gracedb.LVCGraceDbEventData'>, <class 'llama.files.lvc_skymap.LvcDistancesJson'>, <class 'llama.files.lvc_skymap.LvcSkymapHdf5'>, <class 'llama.files.gracedb.PAstro'>, <class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>)¶

UR_DEPENDENCY_TREE = ImmutableDict({<class 'llama.files.coinc_significance.opa.CoincSignificanceI3Lvc'>: ImmutableDict({<class 'llama.files.gracedb.PAstro'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.lvc_skymap.LvcSkymapHdf5'>: ImmutableDict({<class 'llama.files.lvc_skymap.LvcSkymapFits'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.lvc_skymap.LvcDistancesJson'>: ImmutableDict({<class 'llama.files.lvc_skymap.LvcSkymapFits'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({}), <class 'llama.files.gracedb.LVCGraceDbEventData'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.i3.json.IceCubeNeutrinoList'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})}), <class 'llama.files.i3.json.IceCubeNeutrinoList'>: ImmutableDict({<class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})}), <class 'llama.files.skymap_info.SkymapInfo'>: ImmutableDict({})})¶

Submodules