Calculating event trigger rate

Simple event rate

For discrete data in the form of event triggers, it is often very illuminating to analyse the rate at which these events occur in time - usually a high event rate is indicative of a higher noise level. One can calculate the event rate of any of the annotated tables using its event_rate() method. For example, as defined for the SnglBurstTable:

SnglBurstTable.event_rate(stride, start=None, end=None, timecolumn='time')[source]

Calculate the rate TimeSeries for this Table.

Parameters:

stride : float

size (seconds) of each time bin

start : float, LIGOTimeGPS, optional

GPS start epoch of rate TimeSeries

end : float, LIGOTimeGPS, optional

GPS end time of rate TimeSeries. This value will be rounded up to the nearest sample if needed.

timecolumn : str, optional, default: time

name of time-column to use when binning events
Returns:

rate : TimeSeries

a TimeSeries of events per second (Hz)

We can use the same data as for the example on plotting event triggers to demonstrate how to calculate and display the rate versus time of some event triggers:

>>> from gwpy.table.lsctables import SnglBurstTable
>>> events = SnglBurstTable.read('../../gwpy/tests/data/'
                                 'H1-LDAS_STRAIN-968654552-10.xml.gz')
>>> rate = events.event_rate(1, start=968654552, end=968654562)
>>> plot = rate.plot()
>>> plot.set_xlim(968654552, 968654562)
>>> plot.set_ylabel('Event rate [Hz]')
>>> plot.set_title('LIGO Hanford Observatory event rate for GW100916')
>>> plot.show()

(Source code, png)

../_images/rate1.png

This code is a snippet of the example on plotting event rate.

Binned event rate

Following from a simple rate versus time calculation, it is often useful to calculate the event rate for multiple conditions on the same table. The binned_event_rates() method is attached to each Table subclass for convenience.

SnglBurstTable.binned_event_rates(stride, column, bins, operator='>=', start=None, end=None, timecolumn='time')[source]

Calculate an event rate TimeSeriesDict over a number of bins.

Parameters:

stride : float

size (seconds) of each time bin

column : str

name of column by which to bin.

bins : list

a list of tuples marking containing bins, or a list of floats defining bin edges against which an math operation is performed for each event.

operator : str, callable

one of:

  • '<', '<=', '>', '>=', '==', '!=', for a standard mathematical operation,
  • 'in' to use the list of bins as containing bin edges, or
  • a callable function that takes compares an event value against the bin value and returns a boolean.

Note

If bins is given as a list of tuples, this argument is ignored.

start : float, LIGOTimeGPS, optional

GPS start epoch of rate TimeSeries.

end : float, LIGOTimeGPS, optional

GPS end time of rate TimeSeries. This value will be rounded up to the nearest sample if needed.

timecolumn : str, optional, default: time

name of time-column to use when binning events
Returns:

rates : TimeSeriesDict

a dict of (bin, TimeSeries) pairs describing a rate of events per second (Hz) for each of the bins.

For example, in the following example, we calculate the rate of events with signal-to-noise ratio (SNR) above some threshold, for the same table as above.

>>> rates = events.binned_event_rates(1, 'snr', [2, 3, 5, 8], operator='>=',
                                      start=968654552, end=968654562)
>>> # Finally, we can make a plot:
>>> plot = rates.plot(label='name')
>>> plot.set_xlim(968654552, 968654562)
>>> plot.set_ylabel('Event rate [Hz]')
>>> plot.set_title('LIGO Hanford Observatory event rate for GW100916')
>>> plot.add_legend()

(Source code, png)

../_images/rate_binned1.png

This code is a snippet of the example on plotting event rate.