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.
digraph preliminary_alert {
compound = true
nodesep = 0.1
ranksep = 0.1
node [
fillcolor = white
shape = box
style = filled
target = "_top"
]
graph [
labeljust = "left"
style = filled
target = "_top"
]
superevent [
label = "LVAlert message\nfor new\nsuperevent"
style = rounded
]
subgraph cluster_handle_superevent {
href = "../gwcelery.tasks.orchestrator.html#gwcelery.tasks.orchestrator.handle_superevent"
label = <<B><FONT face="monospace">handle_superevent</FONT></B>>
orchestrator_timeout [
href = "../gwcelery.conf.html#gwcelery.conf.orchestrator_timeout"
label = <Wait<BR/><B><FONT face="monospace">orchestrator_timeout</FONT></B><BR/>seconds>
]
get_preferred_event [
label = "Get preferred event"
]
check_vectors [
href = "../gwcelery.tasks.detchar.html#gwcelery.tasks.detchar.check_vectors"
label = "Check state vectors"
]
offline_event [
label = "Offline event\n?"
shape = diamond
]
far_threshold [
label = "N_trials * FAR \n < threshold?"
shape = diamond
]
dqv [
label = "Vetoed by\nstate vectors?"
shape = diamond
]
subgraph cluster_preliminary_alert {
href = "../gwcelery.tasks.orchestrator.html#gwcelery.tasks.orchestrator.preliminary_alert"
label = <<B><FONT face="monospace">preliminary_alert</FONT></B>>
copy_from_preferred_event [
label = "Copy classification\n(if CBC) and\nsky map from\npreferred event"
]
annotate_skymaps [
label = "Make sky\nmap plots"
]
send_gcn [
label = "Send preliminary\nGCN notice"
]
circular [
label = "Create GCN\ncircular draft"
shape = diamond
]
}
}
superevent -> orchestrator_timeout [lhead = cluster_handle_superevent]
orchestrator_timeout
-> get_preferred_event
-> check_vectors
-> offline_event
offline_event -> far_threshold [label = No, lhead = prelim_gcn_checks]
far_threshold -> dqv [label = Yes, lhead = prelim_gcn_checks]
dqv -> copy_from_preferred_event [label = No, lhead = cluster_preliminary_alert]
copy_from_preferred_event -> annotate_skymaps -> send_gcn -> circular
cbc_event [
label = "LVAlert for\nfile added\nto CBC event"
style = rounded
]
subgraph cluster_handle_cbc_event {
href = "../gwcelery.tasks.orchestrator.html#gwcelery.tasks.orchestrator.handle_cbc_event"
label = <<B><FONT face="monospace">handle_cbc_event</FONT></B>>
{
rank = same
which_file [
label = "What is the\nfilename?"
shape = diamond
]
download_psd [
label = <Download<BR/><FONT face="monospace">psd.xml.gz</FONT>>
]
}
download_ranking_data [
label = <Download<BR/><FONT face="monospace">ranking_data<BR/>.xml.gz</FONT>>
]
download_coinc_psd [
label = <Download<BR/><FONT face="monospace">coinc.xml</FONT>>
]
download_coinc_ranking_data [
label = <Download<BR/><FONT face="monospace">coinc.xml</FONT>>
]
bayestar [
href = "../gwcelery.tasks.bayestar.html#gwcelery.tasks.bayestar.localize"
label = <Create<BR/><FONT face="monospace">bayestar<BR/>.fits.gz</FONT>>
]
source_classification [
href = "../gwcelery.tasks.em_bright.html#gwcelery.tasks.em_bright.classifier"
label = <Create<BR/><FONT face="monospace">source_<BR/>classi<BR/>fication<BR/>.json</FONT>>
]
p_astro [
href = "../gwcelery.tasks.p_astro_gstlal.html#gwcelery.tasks.p_astro_gstlal.compute_p_astro"
label = <Create<BR/><FONT face="monospace">p_astro<BR/>_gstlal.json</FONT>>
]
}
cbc_event -> which_file [lhead = cluster_handle_cbc_event]
which_file -> download_psd [
fontname = monospace
label = "psd\n.xml\n.gz"
]
which_file -> download_ranking_data [
fontname = monospace
label = "ranking_data.xml.gz"
]
download_psd -> download_coinc_psd -> bayestar -> source_classification
download_ranking_data -> download_coinc_ranking_data -> p_astro
}
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.
digraph initial_alert {
compound = true
nodesep = 0.1
ranksep = 0.1
node [
fillcolor = white
shape = box
style = filled
target = "_top"
]
graph [
labeljust = "left"
style = filled
target = "_top"
]
subgraph cluster_initial_alert {
href = "../gwcelery.tasks.orchestrator.html#gwcelery.tasks.orchestrator.initial_alert"
label = <<B><FONT face="monospace">initial_alert</FONT></B>>
annotate_skymaps [
label = "If sky map provided,\nthen make sky map plots"
]
send_gcn [
label = "Send\nGCN notice"
]
}
annotate_skymaps -> send_gcn
}
Retraction Alerts
Likewise, the retraction_alert()
task creates Retraction
alerts, and at the moment must be invoked manually. A flow chart is shown below.
digraph retraction_alert {
compound = true
nodesep = 0.1
ranksep = 0.1
node [
fillcolor = white
shape = box
style = filled
target = "_top"
]
graph [
labeljust = "left"
style = filled
target = "_top"
]
subgraph cluster_initial_alert {
href = "../gwcelery.tasks.orchestrator.html#gwcelery.tasks.orchestrator.retraction_alert"
label = <<B><FONT face="monospace">retraction_alert</FONT></B>>
send_gcn [
label = "Send\nGCN notice"
]
}
}
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_superevent
( alert ) [source]
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 peforms 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 ) [source]
Peform 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 files
psd.xml.gz
and ranking_data.xml.gz
. The table below lists which
files are created as a result, and which tasks generate them.
(task) gwcelery.tasks.orchestrator.
preliminary_alert
( event , superevent_id ) [source]
Produce a preliminary alert by copying any sky maps.
This consists of the following steps:
Copy any sky maps and source classification from the preferred event
to the superevent.
Create standard annotations for sky maps including all-sky plots by
calling gwcelery.tasks.skymaps.annotate_fits()
.
Create a preliminary VOEvent.
Send the VOEvent to GCN.
Apply the GCN_PRELIM_SENT label to the superevent.
Create and upload a GCN Circular draft.
Start parameter estimation with LALInference.
(task) gwcelery.tasks.orchestrator.
initial_or_update_alert
( superevent_id , alert_type , skymap_filename=None ) [source]
Create and send initial or update GCN notice.
Parameters:
superevent_id (str ) – The superevent ID.
alert_type ({'initial' , 'update'} ) – The alert type.
skymap_filename (str , optional ) – The sky map to send. If None, then most recent public sky map is used.
(task) gwcelery.tasks.orchestrator.
initial_alert
( superevent_id , skymap_filename=None ) [source]
Produce an initial alert.
This does nothing more than call
initial_or_update_alert()
with
alert_type='initial'
.
Parameters:
superevent_id (str ) – The superevent ID.
skymap_filename (str , optional ) – The sky map to send. If None, then most recent public sky map is used.
(task) gwcelery.tasks.orchestrator.
update_alert
( superevent_id , skymap_filename=None ) [source]
Produce an update alert.
This does nothing more than call
initial_or_update_alert()
with
alert_type='update'
.
Parameters:
superevent_id (str ) – The superevent ID.
skymap_filename (str , optional ) – The sky map to send. If None, then most recent public sky map is used.
(task) gwcelery.tasks.orchestrator.
retraction_alert
( superevent_id ) [source]
Produce a retraction alert. This is currently just a stub and does
nothing more than create and send a VOEvent.