gwcelery.tasks.external_triggers module

This module listens to the GCN notices from SNEWS and the Fermi, Swift, and INTEGRAL missions, as well as Kafka alerts from Fermi and Swift. It is also responsible for carrying out tasks related to external trigger-gravitational wave coincidences, including looking for temporal coincidences, creating combined GRB-GW sky localization probability maps, and computing their joint temporal and spatio-temporal false alarm rates.

There are two GCN, one Kafka, and two IGWN Alert message handlers in the gwcelery.tasks.external_triggers module:

• handle_snews_gcn() is called for each SNEWS GCN.

• handle_grb_gcn() is called for each GRB GCN such as Fermi, Swift, and INTEGRAL.

• handle_targeted_kafka_alert() is called for GRB missions involved with the targeted search, currently Fermi and Swift.

• handle_snews_igwn_alert() is called for each SNEWS external trigger and superevent IGWN Alert.

• handle_grb_igwn_alert() is called for each Fermi and Swift external trigger and superevent IGWN Alert.

Flow charts

GCN VOEvent Ingestion

Kafka Alert Ingestion

IGWN Alert Handling

Tasks

gwcelery.tasks.external_triggers.REQUIRED_LABELS_BY_TASK = {'SoG': {'ADVOK', 'RAVEN_ALERT', 'SKYMAP_READY'}, 'compare': {'EM_COINC', 'EM_READY', 'EXT_SKYMAP_READY'}}

These labels should be present on an external event to consider it to be ready for sky map comparison or for post-alert analysis, such as a measurment of the speed of gravity (SoG).

gwcelery.tasks.external_triggers.FERMI_GRB_CLASS_VALUE = 4

This is the index that denote GRBs within Fermi’s Flight Position classification.

gwcelery.tasks.external_triggers.FERMI_GRB_CLASS_THRESH = 50

This values denotes the threshold of the most likely Fermi source classification, above which we will consider a Fermi Flight Position notice.

(task)gwcelery.tasks.external_triggers.handle_snews_gcn(payload)

Handles the GCN notice payload from SNEWS alerts.

Prepares the alert to be sent to graceDB as external events, updating the info if it already exists.

Parameters:

payload (str) – XML GCN notice alert packet in string format

(task)gwcelery.tasks.external_triggers.handle_grb_gcn(payload)

Handles the payload from Fermi, Swift, and INTEGRAL GCN notices.

Filters out candidates likely to be noise. Creates external events from the notice if new notice, otherwise updates existing event. Then creates and/or grabs external sky map to be uploaded to the external event.

More info for these notices can be found at: Fermi-GBM: https://gcn.gsfc.nasa.gov/fermi_grbs.html Fermi-GBM sub: https://gcn.gsfc.nasa.gov/fermi_gbm_subthresh_archive.html Swift: https://gcn.gsfc.nasa.gov/swift.html INTEGRAL: https://gcn.gsfc.nasa.gov/integral.html

Parameters:

payload (str) – XML GCN notice alert packet in string format

(task)gwcelery.tasks.external_triggers.handle_grb_igwn_alert(alert)

Parse an IGWN alert message related to superevents/GRB external triggers and dispatch it to other tasks.

Notes

This IGWN alert message handler is triggered by creating a new superevent or GRB external trigger event, a label associated with completeness of skymaps or change in state, or if a sky map file is uploaded:

• New event/superevent triggers a coincidence search with gwcelery.tasks.raven.coincidence_search().

• When both a GW and GRB sky map are available during a coincidence, indicated by the labels EM_READY and EXT_SKYMAP_READY respectively on the external event, this triggers the spacetime coinc FAR to be calculated and a combined GW-GRB sky map is created using gwcelery.tasks.external_skymaps.create_combined_skymap().

• Re-run sky map comparison if complete, and either the GW or GRB sky map has been updated or if the preferred event changed.

• Re-check RAVEN publishing conditions if the GRB was previously considered non-astrophycial but now should be considered.

Parameters:

alert (dict) – IGWN alert packet

(task)gwcelery.tasks.external_triggers.handle_snews_igwn_alert(alert)

Parse an IGWN alert message related to superevents/Supernovae external triggers and dispatch it to other tasks.

Notes

This igwn_alert message handler is triggered whenever a new superevent or Supernovae external event is created:

• New event triggers a coincidence search with gwcelery.tasks.raven.coincidence_search().

Parameters:

alert (dict) – IGWN alert packet

(task)gwcelery.tasks.external_triggers.handle_targeted_kafka_alert(alert)

Parse an alert sent via Kafka from a MOU partner in our joint subthreshold targeted search.

Parameters:

alert (dict) – Kafka alert packet

(task)gwcelery.tasks.external_triggers._launch_external_detchar(event)

Launch detchar tasks for an external event.

Parameters:

event (dict) – External event dictionary

Returns:

event – External event dictionary

Return type:

dict

(task)gwcelery.tasks.external_triggers._create_replace_external_event_and_skymap(events, payload, search, pipeline, label=None, ext_group='External', notice_date=None, notice_type=None, skymap=None, skymap_link=None, use_radec=False)

Either create a new external event or replace an old one if applicable Then either uploads a given sky map, try to download one given a link, or create one given coordinates.

Parameters:

• events (list) – List of external events sharing the same trigger ID

• payload (str) – VOEvent of event being considered

• search (str) – Search of external event

• pipeline (str) – Pipeline of external evevent

• label (list) – Label to be uploaded along with external event. If None, removes ‘NOT_GRB’ label from event

• ext_group (str) – Group of external event, ‘External’ or ‘Test’

• notice_date (str) – External event trigger time in ISO format

• notice_type (int) – GCN notice type integer

• skymap (str) – Base64 encoded sky map

• skymap_link (str) – Link to external sky map to be downloaded

• use_radec (bool) – If True, try to create sky map using given coordinates