llama.files.lvc_gcn_xml module

Class for saving, parsing, and conveniently retrieving data from VOEvent XML files distributed by the GCN network and created by LVC describing GW triggers. Includes functionality work with multiple schemas of LVC VOEvents from the Advanced LIGO era.

class llama.files.lvc_gcn_xml.LvcGcnXml

Bases: llama.filehandler.EventTriggeredFileHandler

digraph "llama.files.lvc_gcn_xml.LvcGcnXml" { charset="utf-8" splines=ortho bgcolor=none margin=0 rankdir=LR "llama.files.lvc_gcn_xml.LvcGcnXml" [label=<{{<B>LvcGcnXml</B>|<I>lvc_gcn.xml</I>|EventTriggeredFileHandler}}>, shape="record", style=filled, target=_top, URL="/llama.files.lvc_gcn_xml.html#llama.files.lvc_gcn_xml.LvcGcnXml", fillcolor="#cccccc"]; }

llama.files.lvc_gcn_xml.LvcGcnXml is created from external triggers. It therefore has no LLAMA-representable input dependencies, but instead acts as initial input for other FileHandler classes.

A VOEvent XML file received from GCN corresponding to an LVC event notice.

FILENAME = 'lvc_gcn.xml'
MANIFEST_TYPES = (<class 'llama.files.lvc_gcn_xml.LvcGcnXml'>,)
UR_DEPENDENCIES = ()
UR_DEPENDENCY_TREE = frozenset({})
property alert_type

Get the alert type for this VOEvent.

property etree

Return an lxml.etree for this VOEvent.

property event_time_gps

Get the time of the observed event up to nanosecond precision (less accurate than this in practice) in GPS time format.

property event_time_gps_nanoseconds

Get the number of nanoseconds past the last GPS second at the time of the observed event. Ostensibly provides nanosecond precision, but is less accurate than this in practice.

property event_time_gps_seconds

Get the time of the observed event in GPS seconds (truncated to the nearest second).

property event_time_mjd

Get the time of the observed event in UTC MJD format.

property event_time_str

Get a unicode string with the ISO date and time of the observed event straight from the VOEvent file. UTC time.

property far

Get the false alarm rate of this VOEvent as a float value.

get_alert_type()

Read the alert type of this GCN Notice.

get_param(param)

Get this VOEventParam for this event.

property graceid

Get the GraceID corresponding to this VOEvent.

property ivorn

Get the IVORN, a unique identifier for this GCN Notice.

property notice_time_str

Get a unicode string with the date and time of creation of the notification associated with this VOEvent, rather than the time of detection of the event itself. Should be in ISO format.

property pipeline

Return an ALL-CAPS name of the pipeline used to generate this event, e.g. GSTLAL or CWB.

property role

Get the role of this VOEvent as specified in the header.

property skymap_filename

Get the filename for this skymap as it appears on GraceDB.

class llama.files.lvc_gcn_xml.LvcRetractionXml

Bases: llama.files.lvc_gcn_xml.LvcGcnXml

digraph "llama.files.lvc_gcn_xml.LvcRetractionXml" { charset="utf-8" splines=ortho bgcolor=none margin=0 rankdir=LR "llama.files.lvc_gcn_xml.LvcRetractionXml" [label=<{{<B>LvcRetractionXml</B>|<I>lvc_gcn_retraction.xml</I>|LvcGcnXml}}>, shape="record", style=filled, target=_top, URL="/llama.files.lvc_gcn_xml.html#llama.files.lvc_gcn_xml.LvcRetractionXml", fillcolor="#cccccc"]; }

llama.files.lvc_gcn_xml.LvcRetractionXml is created from external triggers. It therefore has no LLAMA-representable input dependencies, but instead acts as initial input for other FileHandler classes.

A VOEvent XML file retracting a GCN notice.

FILENAME = 'lvc_gcn_retraction.xml'
llama.files.lvc_gcn_xml.get_filename_from_group(filename, paramname)

old VOEvent format had the skymap URL buried in a Param which itself is contained in a group:

VOEvent/What/Group/Param

This is mostly the same as get VOEventParam in utils and is rewritten here only to add support for an edge case.

llama.files.lvc_gcn_xml.get_filename_from_group_name(filename, grouptypename, paramname)

some stupid VOEvent format has things nested under filter(lambda a: a[‘type’] == ‘GW_SKYMAP’, event.voe_VOEvent.What.Group)[0] so go ahead and look under different group type names to find the right skymap URL.

llama.files.lvc_gcn_xml.get_filename_from_param(filename, paramname)

get the skymap URL for newer style VOEvents, which have the skymap param directly under the What element:

VOEvent/What/Param

llama.files.lvc_gcn_xml.get_skymap_filename(filename)

Get the skymap URL regardless of the current VOEvent format from the VOEvent file with the given filename.

llama.files.lvc_gcn_xml.parse_ivorn(payload)

Get identifying information about an LVC VOEvent, raising a ValueError if the IVORN cannot be parsed. Provides a safe way of handling errors for the GCN listener, which should to the greatest extent possible handle errors due to malformed data from partners.

Parameters

payload (str) – The LVC VOEvent in XML string format.

Returns

  • ivorn (str) – The event’s unique ID, called an “IVORN”.

  • eventid (str) – A combination of GraceID, serial GCN notice number for the event, and notice type for this event that will be used for OPA events in the pipeline.

  • graceid (str) – The GraceID of the gravitational wave event.

  • serial_no (int) – The serial number of this GCN Notice, e.g. 2 for the second notice related to this particular GraceID.

  • notice_type (str) – The LVC GCN Notice type for this notice; expected to be one of Preliminary, Initial, Update, or Retraction, though this is not checked.

Raises

ValueError – A descriptive error raised if root is not a lxml.etree._Element describing a valid LVC GCN Notice. The message will describe what part of parsing failed.

Examples

Get the IVORN, eventid, and GraceID from a test event file:

>>> from llama.utils import get_test_file
>>> with open(get_test_file('lvc_gcn.xml',
...                         'MS181101ab-2-Initial')) as xmlfile:
...     payload = xmlfile.read()
>>> parse_ivorn(payload)
('ivo://gwnet/LVC#MS181101ab-2-Initial', 'MS181101ab-2-Initial', 'MS181101ab', 2, 'Initial')