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:

  • A SNEWS coincidence is preferred over GRB.

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

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

  • A spacetime joint FAR over a time-only joint FAR.

  • Lower joint FARs are preferred over higher joint FARs.

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:

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

Return type:

dict

(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