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¶
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:
- (task)gwcelery.tasks.raven.coincidence_search(gracedb_id, alert_object, group=None, pipelines=[], searches=[], se_searches=[])[source]¶
Perform ligo-raven search for coincidences. Determines time window to use. If events found, launches RAVEN pipeline.
- Parameters:
- (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:
- (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.
- (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:
- Returns:
coinc_far_far – Dictionary containing joint false alarm rate passed to the function as an initial argument
- Return type:
- 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
andb
,a
is preferred overb
ifkeyfunc(a) > keyfunc(b)
, elseb
is preferred.- Parameters:
event_far (tuple) – Tuple of event dictionary and coinc far dictionary from RAVEN.
- Returns:
key – The comparison key.
- Return type:
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 topreliminary_alert_far_threshold
. This FAR also must not be negative.If the coincidence involves a GRB, then both sky maps must be present.
- (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.