EventTable#

class gwpy.table.EventTable(

data=None,

masked=False,

names=None,

dtype=None,

meta=None,

copy=True,

rows=None,

copy_indices=True,

units=None,

descriptions=None,

**kwargs,

)[source]#

Bases: Table

A container for a table of events.

This object expands the default Table with extra read/write formats, and methods to perform filtering, rate calculations, and visualisation.

See also

astropy.table.Table: for details on parameters for creating an EventTable

Attributes Summary

`fetch`	Fetch a table of events from a database.
`read`	Read data into an `EventTable`.
`write`	Write this table to a file in the specified format.

Methods Summary

`binned_event_rates`(stride, column, bins[, ...])	Calculate an event rate `TimeSeriesDict`.
`cluster`(index, rank, window)	Cluster this `EventTable` over a given column.
`event_rate`(stride[, start, end, timecolumn])	Calculate the rate `TimeSeries` for this `Table`.
`fetch_open_data`(catalog[, columns, where, host])	Fetch events from an open-data catalogue hosted by GWOSC.
`filter`(*column_filters)	Apply one or more column slice filters to this `EventTable`.
`get_column`(name)	Return the `Column` with the given name.
`hist`(column, **kwargs)	Generate a `HistogramPlot` of this `Table`.
`scatter`(x, y, **kwargs)	Make a scatter plot of column `x` vs column `y`.
`tile`(x, y, w, h, **kwargs)	Make a tile plot of this table.

Attributes Documentation

fetch#

Fetch a table of events from a database.

Parameters:

*args: All positional arguments are specific to the data source, see below for basic usage.
sourcestr, Engine: The source of the remote data, see _Notes_ for a list of registered sources, OR an SQL database Engine object. Default is 'sql'.
columnslist of str, optional: the columns to fetch from the database table, defaults to all
wherestr, or list of str, optional: One or more column filters with which to downselect the returned table rows as they as read, e.g. 'snr > 5'; multiple conditions should be connected by ‘ && ‘, or given as a list, e.g. 'snr > 5 && frequency < 1000' or ['snr > 5', 'frequency < 1000']
enginesqlalchemy.engine.Engine, optional: The database engine to use when connecting.
drivernamestr: Database backend and driver name.
userstr, optional: The username for authentication to the database.
passwordstr, optional: The password for authentication to the database.
hoststr, optional: The name of the remote database host.
postint, optional: Port to connect to on host.
databasestr, optional: The name of the database to connect to.
querydict, optional: Query parameters.
kwargs: All other positional arguments are specific to the data format, see the online documentation for more details.

Returns:

tableEventTable: A table of events recovered from the remote database.

Examples

>>> from gwpy.table import EventTable

To download a table of all blip glitches from the Gravity Spy database:

>>> EventTable.fetch(
...     tablename="glitches",
...     source="gravityspy",
...     where=["ml_label=Blip", "ml_confidence>0.9"],
... )

To download a table from any SQL-type server

>>> EventTable.fetch(
...     drivername="postgresql",
...     host="localname",
...     tablename="data",
... )

read#

Read data into an EventTable.

Parameters:

sourcestr, list

Source of data, any of the following:

str path of single data file,
str path of LAL-format cache file,
list of paths.

args

Other positional arguments will be passed directly to the underlying reader method for the given format.

formatstr, optional

The format of the given source files; if not given, an attempt will be made to automatically identify the format.

columnslist of str, optional

The list of column names to read.

wherestr, or list of str, optional

One or more column filters with which to downselect the returned table rows as they as read, e.g. 'snr > 5', similar to a SQL WHERE statement. Multiple conditions should be connected by ‘ && ‘ or ‘ and ‘, or given as a list, e.g. 'snr > 5 && frequency < 1000' or ['snr > 5', 'frequency < 1000'].

parallelint

Number of threads to use for parallel reading of multiple files.

verbosebool

Print a progress bar showing read status, default: False.

.. note::

Keyword arguments other than those listed here may be required depending on the format

Returns:

tableEventTable

Raises:

astropy.io.registry.IORegistryError: If the format cannot be automatically identified.
IndexError: If source is an empty list.

write#

Write this table to a file in the specified format.

Get help on the available writers for EventTable using the help() method:

>>> EventTable.write.help()  # general help
>>> EventTable.write.help('root')  # detailed help for the ROOT writer
>>> EventTable.write.list_formats()  # print list of available formats

Parameters:

target: `str`: Filename for output data file.
*args: Other positional arguments will be passed directly to the underlying writer method for the given format.
formatstr: Format for output data; if not given, an attempt will be made to automatically identify the format based on the target filename.
**kwargs: Other keyword arguments will be passed directly to the underlying writer method for the given format.

Raises:

astropy.io.registry.IORegistryError: If the format cannot be automatically identified.

Methods Documentation

binned_event_rates( stride: float, column: str, bins: Sequence[tuple[float, float]] | Sequence[float], operator: str | Callable[[object, object], bool] = '>=', start: SupportsToGps | None = None, end: SupportsToGps | None = None, timecolumn: str | None = None, ) → TimeSeriesDict[source]#

Calculate an event rate TimeSeriesDict.

Calculate the event rate over a number of bins.

Parameters:

stridefloat

size (seconds) of each time bin

columnstr

name of column by which to bin.

binslist

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.

operatorstr, 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.

startfloat, LIGOTimeGPS, optional

GPS start epoch of rate TimeSeries.

endfloat, LIGOTimeGPS, optional

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

timecolumnstr, optional, default: time

name of time-column to use when binning events

Returns:

rates~gwpy.timeseries.TimeSeriesDict`: a dict of (bin, TimeSeries) pairs describing a rate of events per second (Hz) for each of the bins.

cluster(index: str, rank: str, window: float) → Self[source]#

Cluster this EventTable over a given column.

Cluster over the index column, maximizing over the rank column in the table.

The clustering algorithm uses a pooling method to identify groups of points that are all separated in index by less than window.

Each cluster of nearby points is replaced by the point in that cluster with the maximum value of rank.

Parameters:

indexstr: name of the column which is used to search for clusters
rankstr: name of the column to maximize over in each cluster
windowfloat: window to use when clustering data points, will raise ValueError if window > 0 is not satisfied

Returns:

tableEventTable: a new table that has had the clustering algorithm applied via slicing of the original

Examples

To cluster an EventTable (table) whose index is end_time, window is 0.1, and maximize over snr:

>>> table.cluster('end_time', 'snr', 0.1)

event_rate( stride: float, start: SupportsToGps | None = None, end: SupportsToGps | None = None, timecolumn: str | None = None, ) → TimeSeries[source]#

Calculate the rate TimeSeries for this Table.

Parameters:

stridefloat: size (seconds) of each time bin
startfloat, LIGOTimeGPS, optional: GPS start epoch of rate TimeSeries
endfloat, LIGOTimeGPS, optional: GPS end time of rate TimeSeries. This value will be rounded up to the nearest sample if needed.
timecolumnstr, optional: name of time-column to use when binning events, attempts are made to guess this

Returns:

rateTimeSeries: a TimeSeries of events per second (Hz)

Raises:

ValueError: if the timecolumn cannot be guessed from the table contents

classmethod fetch_open_data(

catalog: str,

columns: list[str] | None = None,

where: str | list[str] | None = None,

host: str = 'https://gwosc.org',

**kwargs,

) → Self[source]#

Fetch events from an open-data catalogue hosted by GWOSC.

This is an alias for EventTable.fetch(format='gwosc').

Parameters:

catalogstr: The name of the catalog to fetch, e.g. 'GWTC-1-confident'.
columnslist of str, optional: The list of column names to read.
wherestr, or list of str, optional: One or more column filters with which to downselect the returned table rows as they as read, e.g. 'snr > 5', similar to a SQL WHERE statement. Multiple conditions should be connected by ‘ && ‘ or ‘ and ‘, or given a list, e.g. 'mchirp < 3 && distance < 500' or ['mchirp < 3', 'distance < 500']
hoststr, optional: The open-data host to use.
**kwargs: Other keyword arguments are passed to the fetch method.

filter(*column_filters: FilterLike) → Self[source]#

Apply one or more column slice filters to this EventTable.

Multiple column filters can be given, and will be applied concurrently

Parameters:

*column_filtersstr, tuple: a column slice filter definition, e.g. 'snr > 10, or a filter tuple definition, e.g. ('snr', <my_func>, <arg>)

Returns:

tableEventTable: a new table with only those rows matching the filters

Notes

See Filtering tables for more details on using filter tuples

Examples

To filter an existing EventTable (table) to include only rows with snr greater than 10, and frequency less than 1000:

>>> table.filter('snr>10', 'frequency<1000')

Custom operations can be defined using filter tuple definitions:

>>> from gwpy.table.filters import in_segmentlist
>>> table.filter(('time', in_segmentlist, segs))

get_column(name: str) → Column[source]#

Return the Column with the given name.

This method is provided only for compatibility with the igwn_ligolw.ligolw.Table.

Parameters:

namestr: the name of the column to return

Returns:

columnastropy.table.Column

Raises:

KeyError: if no column is found with the given name

hist(column: str, **kwargs) → Plot[source]#

Generate a HistogramPlot of this Table.

Parameters:

columnstr: Name of the column over which to histogram data
methodstr, optional: Name of Axes method to use to plot the histogram, default: 'hist'.
**kwargs: Any other keyword arguments, see below.

Returns:

plotPlot: The newly created figure.

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure.
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes.
gwpy.plot.Axes.hist: for documentation of keyword arguments used to display the histogram, if the method keyword is given, this method might not actually be the one used.

scatter(x: str, y: str, **kwargs) → Plot[source]#

Make a scatter plot of column x vs column y.

Parameters:

xstr: name of column defining centre point on the X-axis
ystr: name of column defining centre point on the Y-axis
colorstr, optional, default:None: name of column by which to color markers
**kwargs: any other keyword arguments, see below

Returns:

plotPlot: the newly created figure

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes
gwpy.plot.Axes.scatter: for documentation of keyword arguments used to display the table

tile(x: str, y: str, w: str, h: str, **kwargs) → Plot[source]#

Make a tile plot of this table.

Parameters:

xstr: name of column defining anchor point on the X-axis
ystr: name of column defining anchor point on the Y-axis
wstr: name of column defining extent on the X-axis (width)
hstr: name of column defining extent on the Y-axis (height)
colorstr, optional, default:None: name of column by which to color markers
**kwargs: any other keyword arguments, see below

Returns:

plotPlot: the newly created figure

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes
gwpy.plot.Axes.tile: for documentation of keyword arguments used to display the table