gwcelery.tasks.orchestrator module

This module implements the alert orchestrator, which responsible for the vetting and annotation workflow to produce preliminary, initial, and update alerts for gravitational-wave event candidates.

The orchestrator consists of two LVAlert message handlers:

• handle_superevent() is called for each superevent. It waits for a short duration of orchestrator_timeout seconds for the selection of the superevent by the superevent manager to stabilize, then performs data quality checks. If the data quality checks pass, then it calls preliminary_alert() to copy annotations from the preferred event and send the preliminary GCN notice.

• handle_cbc_event() is called for each CBC event. It performs some CBC-specific annotations that depend closely on the CBC matched-filter parameters estimates and that might influence selection of the preferred event: rapid sky localization with BAYESTAR and rapid source classification.

  Note that there is no equivalent of this task for burst events because both burst searches (cWB, LIB) have integrated source localization and have no other annotations.

Preliminary Alerts

The flow chart below illustrates the operation of these two tasks.

Initial and Update Alerts

The initial_alert() and update_alert() tasks create Initial and Update alerts respectively. At the moment, there is no handler or user interface to trigger these tasks, and they must be invoked manually (see Command-Line Tools). A flow chart for the initial alerts is shown below; the flow chart for update alerts is the same.

Retraction Alerts

Likewise, the retraction_alert() task creates Retraction alerts, and at the moment must be invoked manually. A flow chart is shown below.

Tasks

Tasks that comprise the alert orchestrator, which responsible for the vetting and annotation workflow to produce preliminary, initial, and update alerts for gravitational-wave event candidates.

(task)gwcelery.tasks.orchestrator.handle_selected_as_preferred(alert)

(task)gwcelery.tasks.orchestrator.handle_superevent(alert)

Schedule annotations for new superevents.

After waiting for a time specified by the orchestrator_timeout configuration variable for the choice of preferred event to settle down, this task performs data quality checks with gwcelery.tasks.detchar.check_vectors() and calls preliminary_alert() to send a preliminary GCN notice.

(task)gwcelery.tasks.orchestrator.handle_cbc_event(alert)

Perform annotations for CBC events that depend on pipeline-specific matched-filter parameter estimates.

Notes

This LVAlert message handler is triggered by updates that include the file psd.xml.gz. The table below lists which files are created as a result, and which tasks generate them.

File	Task
em_bright.json	gwcelery.tasks.em_bright.classifier()
p_astro.json.json	gwcelery.tasks.p_astro.compute_p_astro()

(task)gwcelery.tasks.orchestrator.handle_posterior_samples(alert)

Generate multi-resolution and flat-resolution fits files and skymaps from an uploaded HDF5 file containing posterior samples.

(task)gwcelery.tasks.orchestrator._download(*args, **kwargs)

Download a file from GraceDB.

This works just like gwcelery.tasks.gracedb.download(), except that it is retried for both TimeoutError and URLError. In particular, it will be retried for 404 (not found) errors.

(task)gwcelery.tasks.orchestrator._update_if_dqok(superevent_id, event_id)

Update preferred_event of superevent_id to event_id if DQOK label has been applied

(task)gwcelery.tasks.orchestrator._get_preferred_event(superevent_id)

Determine preferred event for a superevent by querying GraceDB.

This works just like gwcelery.tasks.gracedb.get_superevent(), except that it returns only the preferred event, and not the entire GraceDB JSON response.

(task)gwcelery.tasks.orchestrator._create_voevent(classification, *args, **kwargs)

Create a VOEvent record from an EM bright JSON file.

Parameters:

• classification (tuple, None) – A collection of JSON strings, generated by gwcelery.tasks.em_bright.classifier() and gwcelery.tasks.p_astro.compute_p_astro() or content of p_astro.json uploaded by gstlal respectively; or None
• *args – Additional positional arguments passed to gwcelery.tasks.gracedb.create_voevent().
• **kwargs – Additional keyword arguments passed to gwcelery.tasks.gracedb.create_voevent().

Returns:

The filename of the newly created VOEvent.

Return type:

str

(task)gwcelery.tasks.orchestrator._create_label_and_return_filename(filename, label, graceid)

(task)gwcelery.tasks.orchestrator.preliminary_alert(event, superevent_id)

Produce a preliminary alert by copying any sky maps.

This consists of the following steps:

1. Copy any sky maps and source classification from the preferred event to the superevent.
2. Create standard annotations for sky maps including all-sky plots by calling gwcelery.tasks.skymaps.annotate_fits().
3. Create a preliminary VOEvent.
4. Send the VOEvent to GCN.
5. Apply the GCN_PRELIM_SENT label to the superevent.
6. Create and upload a GCN Circular draft.

(task)gwcelery.tasks.orchestrator._get_lowest_far(superevent_id)

Obtain the lowest FAR of the events contained in the target superevent

(task)gwcelery.tasks.orchestrator.parameter_estimation(far_event, superevent_id)

Tasks for Parameter Estimation Followup with LALInference

This consists of the following steps:

1. Prepare and upload an ini file which is suitable for the target event.
2. Start Parameter Estimation if FAR is smaller than the PE threshold.

(task)gwcelery.tasks.orchestrator.preliminary_initial_update_alert(filenames, superevent_id, alert_type)

Create and send a preliminary, initial, or update GCN notice.

Parameters:

• filenames (tuple) – A list of the sky map, em_bright, and p_astro filenames.
• superevent_id (str) – The superevent ID.
• alert_type ({'preliminary', 'initial', 'update'}) – The alert type.

Notes

This function is decorated with gwcelery.tasks.gracedb.task rather than gwcelery.app.task so that a synchronous call to gwcelery.tasks.gracedb.get_log() is retried in the event of GraceDB API failures.

(task)gwcelery.tasks.orchestrator.initial_alert(filenames, superevent_id)

Produce an initial alert.

This does nothing more than call preliminary_initial_update_alert() with alert_type='initial'.

Parameters:

• filenames (tuple) – A list of the sky map, em_bright, and p_astro filenames.
• superevent_id (str) – The superevent ID.

Notes

This function is decorated with gwcelery.tasks.gracedb.task rather than gwcelery.app.task so that a synchronous call to gwcelery.tasks.gracedb.get_log() is retried in the event of GraceDB API failures.

(task)gwcelery.tasks.orchestrator.update_alert(filenames, superevent_id)

Produce an update alert.

This does nothing more than call preliminary_initial_update_alert() with alert_type='update'.

Parameters:

• filenames (tuple) – A list of the sky map, em_bright, and p_astro filenames.
• superevent_id (str) – The superevent ID.

Notes

This function is decorated with gwcelery.tasks.gracedb.task rather than gwcelery.app.task so that a synchronous call to gwcelery.tasks.gracedb.get_log() is retried in the event of GraceDB API failures.

(task)gwcelery.tasks.orchestrator.retraction_alert(superevent_id)

Produce a retraction alert. This is currently just a stub and does nothing more than create and send a VOEvent.