gwcelery.tasks.external_triggers module¶
This module listens to the GCN notices from SNEWS and the Fermi, Swift, INTEGRAL, and AGILE 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, INTEGRAL, and AGILE MCAL.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)[source]¶
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)[source]¶
Handles the payload from Fermi, Swift, INTEGRAL, and AGILE MCAL 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 AGILE-MCAL: https://gcn.gsfc.nasa.gov/agile_mcal.html
- Parameters:
payload (str) – XML GCN notice alert packet in string format
- (task)gwcelery.tasks.external_triggers.handle_grb_igwn_alert(alert)[source]¶
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
andEXT_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 usinggwcelery.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)[source]¶
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)[source]¶
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)[source]¶
Launch detchar tasks for an external event.
- (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)[source]¶
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