gwcelery.tasks.raven module

This module use functions from the ligo-raven package to launch coincidence searches and determine whether a joint search should be published.

Flow chart

digraph exttrig { compound = true nodesep = 0.1 ranksep = 0.1 node [ fillcolor = white shape = box style = filled target = "_top" ] graph [ labeljust = "left" style = filled target = "_top" ] NEW_EVENT [ style="rounded" label="New superevent\nor external event" ] RELAUNCH_PIPELINE [ style="rounded" label="Re-launch due to\nnew sky map(s)" ] subgraph cluster_raven_pipeline { href = "../gwcelery.tasks.raven.html#gwcelery.tasks.raven.coincidence_search" label = <<B><FONT face="monospace">coincidence_search</FONT></B>> Query_gracedb [ label="Query GraceDB\nto search for coincidence" ] Query_results [ shape=diamond label="Any joint\ncandidates found?" ] Add_to_superevent [ label="Add external event(s)\nto superevent" ] Calculate_coincidence_far [ label="Calculate\ncoincidence FAR" ] Apply_emcoinc [ label="Apply EM_COINC\nlabels to events" ] Check_publishing [ shape=diamond label="Does this\ncoincidence pass\npublishing conditions?" ] Launch_alert [ label="Launch preliminary alert\nor add coincidence info\nto next alert" ] Update_preferred_external [ label="Update preferred\nexternal event" ] } NEW_EVENT -> Query_gracedb [ lhead = cluster_raven_pipeline ] RELAUNCH_PIPELINE -> Calculate_coincidence_far Query_gracedb -> Query_results Query_results -> Add_to_superevent[label="yes"] Add_to_superevent -> Calculate_coincidence_far Calculate_coincidence_far -> Apply_emcoinc Calculate_coincidence_far -> Check_publishing Check_publishing -> Launch_alert[label="yes"] Check_publishing -> Update_preferred_external[label="no"] Launch_alert -> Update_preferred_external }

Tasks

Search for GRB-GW coincidences with ligo-raven.

(task)gwcelery.tasks.raven.calculate_coincidence_far(superevent, exttrig, tl, th, use_superevent_skymap=None)[source]

Compute coincidence FAR for external trigger and superevent coincidence by calling ligo.raven.search.calc_signif_gracedb, using sky map info if available.

Parameters:
  • superevent (dict) – Superevent dictionary

  • exttrig (dict) – External event dictionary

  • tl (int) – Lower bound of search window in seconds

  • th (int) – Upper bound of search window in seconds

  • use_superevent_skymap (bool) – If True/False, use/don’t use skymap info from superevent. Else if None, check SKYMAP_READY label in external event.

Returns:

joint_far – Dictionary containing joint false alarm rate, including sky map info if available

Return type:

dict

Perform ligo-raven search for coincidences. Determines time window to use. If events found, launches RAVEN pipeline.

Parameters:
  • gracedb_id (str) – GraceDB ID of the trigger that launched RAVEN

  • alert_object (dict) – Alert dictionary

  • group (str) – Burst or CBC

  • pipelines (list) – List of external trigger pipeline names

  • searches (list) – List of external trigger searches

  • se_searches (list) – List of superevent searches

(task)gwcelery.tasks.raven.search(gracedb_id, alert_object, tl=-5, th=5, group=None, pipelines=[], searches=[], se_searches=[])[source]

Perform ligo-raven search to look for coincidences. This function does a query of GraceDB and uploads a log message of the result(s).

Parameters:
  • gracedb_id (str) – GraceDB ID of the trigger that launched RAVEN

  • alert_object (dict) – Alert dictionary

  • tl (int) – Lower bound of search window in seconds

  • th (int) – Upper bound of search window in seconds

  • group (str) – Burst or CBC

  • pipelines (list) – List of external trigger pipelines for performing coincidence search against

  • searches (list) – List of external trigger searches

  • se_searches (list) – List of superevent searches

Returns:

results – List with the dictionaries of related GraceDB events

Return type:

list

(task)gwcelery.tasks.raven.raven_pipeline(raven_search_results, gracedb_id, alert_object, tl, th, gw_group, use_superevent_skymap=None)[source]

Executes the full RAVEN pipeline, including adding the external trigger to the superevent, calculating the coincidence false alarm rate, applying ‘EM_COINC’ to the appropriate events, and checking whether the candidate(s) pass all publishing conditions.

Parameters:
  • raven_search_results (list) – List of dictionaries of each related gracedb trigger

  • gracedb_id (str) – GraceDB ID of the trigger that launched RAVEN

  • alert_object (dict) – Alert dictionary, either a superevent or an external event

  • tl (int) – Lower bound of search window in seconds

  • th (int) – Upper bound of search window in seconds

  • gw_group (str) – Burst or CBC

  • use_superevent_skymap (bool) – If True/False, use/don’t use skymap info from superevent. Else if None, checks SKYMAP_READY label in external event.

(task)gwcelery.tasks.raven.preferred_superevent(raven_search_results)[source]

Chooses the superevent with the lowest FAR for an external event to be added to. This is to prevent errors from trying to add one external event to multiple superevents.

Parameters:

raven_search_results (list) – List of dictionaries of each related gracedb trigger

Returns:

superevent – List containing single chosen superevent

Return type:

list

(task)gwcelery.tasks.raven.update_coinc_far(coinc_far_dict, superevent, ext_event)[source]

Update joint info in superevent based on the current preferred coincidence. In order of priority, the determing conditions are the following:

  • Likely astrophysical external candidates are preferred over likely non-astrophysical candidates.

  • Candidates that pass publishing thresholds are preferred over those that do not.

  • A SNEWS coincidence is preferred, then GRB/FRB/HEN, then subthreshold.

  • A lower spacetime joint FAR is preferred over a higher spacetime joint FAR.

  • A lower temporal joint FAR is preferred over a higher temporal joint FAR.

Parameters:
  • coinc_far_dict (dict) – Dictionary containing coincidence false alarm rate results from RAVEN

  • superevent (dict) – Superevent dictionary

  • ext_event (dict) – External event dictionary

Returns:

coinc_far_far – Dictionary containing joint false alarm rate passed to the function as an initial argument

Return type:

dict

gwcelery.tasks.raven.keyfunc(event_far)[source]

Key function for selection of the preferred event.

Return a value suitable for identifying the preferred event. Given events a and b, a is preferred over b if keyfunc(a) > keyfunc(b), else b is preferred.

Parameters:

event_far (tuple) – Tuple of event dictionary and coinc far dictionary from RAVEN.

Returns:

key – The comparison key.

Return type:

tuple

Notes

Tuples are compared lexicographically in Python: they are compared element-wise until an unequal pair of elements is found.

(task)gwcelery.tasks.raven.trigger_raven_alert(coinc_far_dict, superevent, gracedb_id, ext_event, gw_group)[source]

Determine whether an event should be published as a preliminary alert. If yes, then triggers an alert by applying RAVEN_ALERT to the preferred event.

All of the following conditions must be true to either trigger an alert or include coincidence info into the next alert include:

  • The external event must be a threshold GRB or SNEWS event.

  • If triggered on a SNEWS event, the GW false alarm rate must pass snews_gw_far_threshold.

  • The event’s RAVEN coincidence false alarm rate, weighted by the group-specific trials factor as specified by the preliminary_alert_trials_factor configuration setting, is less than or equal to preliminary_alert_far_threshold. This FAR also must not be negative.

  • If the coincidence involves a GRB, then both sky maps must be present.

Parameters:
  • coinc_far_dict (dict) – Dictionary containing coincidence false alarm rate results from RAVEN

  • superevent (dict) – Superevent dictionary

  • gracedb_id (str) – GraceDB ID of the trigger that launched RAVEN

  • ext_event (dict) – External event dictionary

  • gw_group (str) – Burst or CBC

(task)gwcelery.tasks.raven.sog_paper_pipeline(ext_event, superevent)[source]

Determine whether an a speed of gravity measurment manuscript should be created for a given coincidence. This is denoted by applying the SOG_READY label to a superevent.

All of the following conditions must be true for a SoG paper:

  • The coincidence is significant and FARs more significant than in sog_paper_far_threshold.

  • The external event is a high-significance GRB and from an MOU partner.

  • The GW event is a CBC candidate.

Parameters:
  • superevent (dict) – Superevent dictionary

  • ext_event (dict) – External event dictionary