GWOSC

A python interface to the Gravitational-Wave Open Science Center archive.

Installation

gwosc can be installed via pip:

python -m pip install gwosc

or Conda:

conda install -c conda-forge gwosc

Documentation

Querying dataset information

gwosc.datasets includes functions to query for available datasets.

To search for all available datasets:

>>> from gwosc import datasets
>>> datasets.find_datasets()
['GW150914', 'GW151226', 'GW170104', 'GW170608', 'GW170814', 'GW170817', 'LVT151012', 'O1', 'S5', 'S6']
>>> datasets.find_datasets(detector='V1')
['GW170814', 'GW170817']
>>> datasets.find_datasets(type='run')
['O1', 'S5', 'S6']

To query for the GPS time of an event dataset (or vice-versa):

>>> datasets.event_gps('GW170817')
1187008882.43
>>> datasets.event_at_gps(1187008882)
'GW170817'

Similar queries are available for observing run datasets:

>>> datasets.run_segment('O1')
(1126051217, 1137254417)
>>> datasets.run_at_gps(1135136350)  # event_gps('GW151226')
'O1'

To run an event query filtered by merger parameters:

>>> from gwosc.datasets import query_events
>>> query_events(select=["mass-1-source <= 3.0"])
['GW170817-v3', 'GW190425-v1', 'GW190425-v2', 'GW190425_081805-v3']

Functions

dataset_type(dataset[, host])

Returns the type of the named dataset

event_at_gps(gps[, host, tol])

Returns the name of the open-data event matching the GPS time

event_detectors(event[, catalog, version, host])

Returns the set of detectors that observed an event

event_gps(event[, catalog, version, host])

Returns the GPS time of an open-data event

event_segment(event[, detector, catalog, ...])

Returns the GPS [start, stop) interval covered by an event dataset

find_datasets([detector, type, segment, ...])

Find datasets available on the given GW open science host

query_events(select[, host])

Return a list of events filtered by the parameters in select

run_at_gps(gps[, host])

Returns the name of the open-data run dataset matching the GPS time

run_segment(run[, host])

Returns the GPS [start, stop) interval covered by a run dataset

Querying for data file URLs

gwosc.locate provides functions to determine the file URLs containing data for a specific dataset.

You can search for remote data URLS based on the event name:

>>> from gwosc.locate import get_event_urls
>>> get_event_urls('GW150914')
['https://gwosc.org/eventapi/json/GWTC-1-confident/GW150914/v3/H-H1_GWOSC_4KHZ_R1-1126259447-32.hdf5',
 'https://gwosc.org/eventapi/json/GWTC-1-confident/GW150914/v3/H-H1_GWOSC_4KHZ_R1-1126257415-4096.hdf5',
 'https://gwosc.org/eventapi/json/GWTC-1-confident/GW150914/v3/L-L1_GWOSC_4KHZ_R1-1126259447-32.hdf5',
 'https://gwosc.org/eventapi/json/GWTC-1-confident/GW150914/v3/L-L1_GWOSC_4KHZ_R1-1126257415-4096.hdf5']

You can down-select the URLs using keyword arguments:

>>> get_event_urls('GW150914', detector='L1', duration=32)
['https://gwosc.org/eventapi/json/GWTC-1-confident/GW150914/v3/L-L1_GWOSC_4KHZ_R1-1126259447-32.hdf5']

You can search for remote data URLs based on the GPS time interval as follows:

>>> from gwosc.locate import get_urls
>>> get_urls('L1', 968650000, 968660000)
['https://gwosc.org/archive/data/S6/967835648/L-L1_LOSC_4_V1-968646656-4096.hdf5',
 'https://gwosc.org/archive/data/S6/967835648/L-L1_LOSC_4_V1-968650752-4096.hdf5',
 'https://gwosc.org/archive/data/S6/967835648/L-L1_LOSC_4_V1-968654848-4096.hdf5',
 'https://gwosc.org/archive/data/S6/967835648/L-L1_LOSC_4_V1-968658944-4096.hdf5']

By default, this method will return the paths to HDF5 files for the 4 kHz sample-rate data, these can be specified as keyword arguments. For full information, see get_urls().

Functions

get_urls(detector, start, end[, dataset, ...])

Fetch the URLs from GWOSC regarding a given GPS interval

get_run_urls(run, detector, start, end[, ...])

Fetch the URLs from GWOSC regarding a given event

get_event_urls(event[, catalog, version, ...])

Fetch the URLs from GWOSC regarding a given event

Querying for Timeline segments

gwosc.timeline provides functions to find segments for a given dataset.

You can search for Timeline segments, based on a flag name, and a GPS time interval as follows:

>>> from gwosc.timeline import get_segments
>>> get_segments('H1_DATA', 1126051217, 1126151217)
[(1126073529, 1126114861), (1126121462, 1126123267), (1126123553, 1126126832), (1126139205, 1126139266), (1126149058, 1126151217)]

The output is a list of [start, end) 2-tuples which each represent a semi-open time interval.

For documentation on what flags are available, for example for the O1 science run, see the O1 data release page (Data Quality).

Functions

get_segments(flag, start, end[, host])

Return the [start, end) GPS segments for this flag

timeline_url(flag, start, end[, host])

Returns the Timeline JSON URL for a flag name and GPS interval

Low-level API

gwosc.api provides the low-level interface functions that handle direct requests to the GWOSC host.

Module contents:

DEFAULT_URL

The default GWOSC host URL

JSON_CACHE

Cache of downloaded blobs

fetch_allevents_json([full, host])

"Returns the JSON metadata for the allevents API

fetch_allowed_params_json([host])

fetch_catalog_json(catalog[, host])

"Returns the JSON metadata for the given catalogue

fetch_cataloglist_json([host])

Returns the JSON metadata for the catalogue list.

fetch_dataset_json(gpsstart, gpsend[, host])

Returns the JSON metadata for all datasets matching the GPS interval

fetch_event_json(event[, catalog, version, host])

Returns the JSON metadata for the given event.

fetch_filtered_events_json(select[, host])

"Return the JSON metadata for the events constrained by select

fetch_json(url, **kwargs)

Fetch JSON data from a remote URL

fetch_run_json(run, detector[, gpsstart, ...])

Returns the JSON metadata for the given science run parameters

logger

Instances of the Logger class represent a single logging channel.

urlencode(query[, doseq, safe, encoding, ...])

Encode a dict or sequence of two-element tuples into a URL query string.

Index