Working with LIGO detection data

ANTARES listens on the GCN VOEvent stream and processes all LIGO messages. LIGO messages are stored in the ANTARES database and made available to filter code.

ANTARES stores recent LIGO events

ANYTARES considers a GCN VOEvent to be a LIGO message if it has a Packet_Type as one of the following:

import gcn

LIGO_TYPES = [
    gcn.notice_types.LVC_PRELIMINARY,
    gcn.notice_types.LVC_INITIAL,
    gcn.notice_types.LVC_UPDATE,
    gcn.notice_types.LVC_COUNTERPART,
    gcn.notice_types.LVC_RETRACTION,
]

LIGO VOEvents of type LVC_COUNTERPART are ignored.

All other GCN VOEvents are ignored.

When a LIGO VOEvent is processed, ANTARES parses it and produces a dictionary. Some fields may be missing if they were not found in the VOEvent. This may happen if the VOEvent is an LVC_RETRACTION, for example. In the case of an LVC_INITIAL or LVC_UPDATE, the dictionary is structured like the following example:

{
    'raw_packet_xml': '...',  # Complete VOEvent XML
    'packet_type': 152,
    'alert_type': 'Update',
    'event_timestamp': '2019-04-25T08:18:05.017147',
    'notice_date': '2019-04-26T14:51:42',
    'sender': 'LIGO Scientific Collaboration and Virgo Collaboration',
    'event_far': 4.53764787126e-13,
    'event_url': 'https://gracedb.ligo.org/superevents/S190425z/view/',
    'event_name': 'S190425z',
    'event_instr': 'L1,V1',
    'event_skymap_url': 'https://gracedb.ligo.org/api/.../LALInference.fits.gz',
    'event_skymap_fits_data': b'...',  # FITS file binary data
    'event_classification': {
        'BNS': 0.999402567114,
        'NSBH': 0.0,
        'BBH': 0.0,
        'MassGap': 0.0,
        'Terrestrial': 0.00059743288626
    },
    'Event_properties': {
        'HasNS': 1.0,
        'HasRemnant': 1.0
    }
}

If the VOEvent is an LVC_PRELIMINARY, LVC_INITIAL, or LVC_UPDATE, then the dictionary is stored in an ANTARES storage system.

If the VOEvent is an LVC_RETRACTION then all existing data for this event is deleted from ANTARES.

In summary:

LVC_PRELIMINARY  --> Store LIGO detection in ANTARES.
LVC_INITIAL      --> Store LIGO detection in ANTARES.
LVC_UPDATE       --> Store LIGO detection in ANTARES.
LVC_COUNTERPART  --> Do nothing.
LVC_RETRACTION   --> Delete the detection from ANTARES.

Accessing LIGO data in an ANTARES filter

Filters may fetch LIGO data as follows:

from antares import devkit as dk
events = dk.get_ligo_events()

Here events will be a list of dictionaries. Each dictionary will be of the form described above. The list will contain only one dictionary per LIGO detection. If multiple VOEvent messages pertaining to the same LIGO detection have been received, then only the most recent one will be included in the list.