gwcelery.tasks.superevents module

Superevents are an abstraction to unify gravitational-wave candidates from multiple search pipelines. Each superevent is intended to represent a single astrophysical event. A superevent consists of one or more event candidates, possibly from different pipelines, that are neighbors in time. At any given time, one event belonging to the superevent is identified as the preferred event.

This module provides the Superevent Manager, an LVAlert handler that creates and updates superevents whenever new events are uploaded to GraceDB.

Events are only considered for membership in a superevent if their false alarm rate is less than or equal to the value of the superevent_far_threshold configuration setting.

Each superevent has a time window described by a central time t_0, a start time t_start, and a end time t_end. The central time t_0 is just the time of the preferred event. The start and end time are extended to encompass all of the events that belong to the superevent (see get_ts()).

Selection of the preferred event

When a new event is added to a superevent, it may or may not become the new preferred event. The preferred event is selected by considering the following factors in order to resolve any ties:

1. Publishability: Would the event eligible, as determined by the function should_publish(), for sending an automated public alert?
2. Search group: Is it a CBC event or a burst event? CBC events takes precedence.
3. Number of detectors: How many detectors contributed data to the event? For CBC events, events with triggers from more detectors take precedence.
4. Significance: For CBC events, which has the highest SNR? For burst events, which has the lowest FAR?

The selection of the preferred event from a pair of events is illustrated by the decision tree below.

Tasks

Module containing the functionality for creation and management of superevents.

• There is serial processing of triggers from low latency pipelines.
• Dedicated superevent queue for this purpose.
• Primary logic to respond to low latency triggers contained in process() function.

(task)gwcelery.tasks.superevents.handle(payload)

Respond to lvalert nodes from low-latency search pipelines and delegate to process() for superevent management.

(task)gwcelery.tasks.superevents.process(*args, **kwargs)

Respond to payload and serially processes them to create new superevents, add events to existing ones and update superevent parameters.

Parameters:payload (dict) – LVAlert payload

gwcelery.tasks.superevents.get_ts(event)

Get time extent of an event, depending on pipeline-specific parameters.

• For CWB, use the event’s duration field.
• For oLIB, use the ratio of the event’s quality_mean and frequency_mean fields.
• For all other pipelines, use the superevent_d_t_start and superevent_d_t_start configuration values.

Parameters:event (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). Returns:

• t_0 (float) – Segment center time in GPS seconds.
• t_start (float) – Segment start time in GPS seconds.
• t_end (float) – Segment end time in GPS seconds.

gwcelery.tasks.superevents.get_snr(event)

Get the SNR from the LVAlert packet.

Different groups and pipelines store the SNR in different fields.

Parameters:event (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). Returns:snr – The SNR. Return type:float

gwcelery.tasks.superevents.get_instruments(event)

Get the instruments that contributed data to an event.

Parameters:event (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). Returns:The set of instruments that contributed to the event. Return type:set

gwcelery.tasks.superevents.get_instruments_in_ranking_statistic(event)

Get the instruments that contribute to the false alarm rate.

Parameters:event (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). Returns:The set of instruments that contributed to the ranking statistic for the event. Return type:set

Notes

The number of instruments that contributed data to an event is given by the instruments key of the GraceDB event JSON structure. However, some pipelines (e.g. gstlal) have a distinction between which instruments contributed data and which were considered in the ranking of the candidate. For such pipelines, we infer which pipelines contributed to the ranking by counting only the SingleInspiral records for which the chi squared field is non-empty.

gwcelery.tasks.superevents.should_publish(event)

Determine whether an event should be published as a public alert.

All of the following conditions must be true for a public alert:

• The event’s offline flag is not set.
• The event’s 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.

Parameters:event (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). Returns:should_publish – True if the event meets the criteria for a public alert or False if it does not. Return type:bool

gwcelery.tasks.superevents.keyfunc(event)

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 (dict) – Event dictionary (e.g., the return value from gwcelery.tasks.gracedb.get_event()). 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.