TimeSeriesBaseDict#

class gwpy.timeseries.TimeSeriesBaseDict[source]#

Bases: dict[str | Channel, _V], Generic[_V]

Key-value mapping of named TimeSeriesBase objects.

This object is designed to hold data for many different sources (channels) for a single time span. Dictionary keys are ordered by insertion order.

The main entry points for this object are the read() and fetch() data access methods.

Attributes Summary

get

Retrieve data for multiple names from any data source.

read

Read data into a TimeSeriesBaseDict.

span

The GPS [start, stop) extent of data in this dict.

write

Write data from a TimeSeriesBaseDict.

Methods Summary

append(other, *[, copy])

Append the dict other to this one.

copy()

Return a copy of this dict with each value copied to new memory.

crop([start, end, copy])

Crop each entry of this dict.

fetch(channels, start, end, *[, host, port, ...])

Fetch data from NDS for a number of channels.

fetch_open_data(detectors, start, end, *[, ...])

Fetch open-access data from the LIGO Open Science Center.

find(channels, start, end, *[, observatory, ...])

Find and read data from frames for a number of channels.

from_arrakis(block, *[, copy])

Construct a new dict from an arrakis.SeriesBlock.

from_nds2_buffers(buffers, *[, scaled, copy])

Construct a new dict from a list of nds2.buffer objects.

plot([label, method, figsize, xscale])

Plot the data for this TimeSeriesBaseDict.

prepend(other, **kwargs)

Prepend the dict other to this one.

resample(rate, **kwargs)

Resample items in this dict.

step([label, where, figsize, xscale])

Create a step plot of this dict.

Attributes Documentation

get#

Retrieve data for multiple names from any data source.

read#

Read data into a TimeSeriesBaseDict.

span[source]#

The GPS [start, stop) extent of data in this dict.

write#

Write data from a TimeSeriesBaseDict.

Methods Documentation

append(
other: Mapping[str | Channel, NDArray],
*,
copy: bool = True,
**kwargs,
) → Self[source]#

Append the dict other to this one.

Parameters:
otherdict of TimeSeries

The container to append to this one.

copybool, optional

If True copy data from other before storing, only affects those keys in other that aren’t in self.

**kwargs

Other keyword arguments to send to TimeSeries.append.

See also

TimeSeries.append

For details of the underlying series append operation.

copy() → Self[source]#

Return a copy of this dict with each value copied to new memory.

crop(
start: SupportsToGps | None = None,
end: SupportsToGps | None = None,
*,
copy: bool = False,
) → Self[source]#

Crop each entry of this dict.

This method calls the crop() method of all entries and modifies this dict in place.

Parameters:
startLIGOTimeGPS, float, str

GPS start time of required data, any input parseable by to_gps is fine

endLIGOTimeGPS, float, str, optional

GPS end time of required data, defaults to end of data found; any input parseable by to_gps is fine

copybool, optional, default: False

If True copy the data for each entry to fresh memory, otherwise return a view.

See also

TimeSeries.crop

for more details

classmethod fetch(
channels: list[str | Channel],
start: SupportsToGps,
end: SupportsToGps,
*,
host: str | None = None,
port: int | None = None,
verbose: bool | str = False,
connection: nds2.connection | None = None,
verify: bool = False,
pad: float | None = None,
allow_tape: bool | None = None,
scaled: bool | None = None,
type: int | str | None = None,
dtype: int | str | None = None,
) → Self[source]#

Fetch data from NDS for a number of channels.

This is just a shim around TimeSeriesDict.get(..., source='nds2').

Parameters:
channelsstr, Channel

List of names of data channels to find.

startLIGOTimeGPS, float, str

GPS start time of required data, any input parseable by to_gps is fine

endLIGOTimeGPS, float, str, optional

GPS end time of required data, defaults to end of data found; any input parseable by to_gps is fine

hoststr, optional

URL of NDS server to use, if blank will try any server (in a relatively sensible order) to get the data

One of connection or host must be given.

portint, optional

Port number for NDS server query, must be given with host.

verifybool, optional

Check channels exist in database before asking for data. Default is True.

verbosebool, optional

This argument is deprecated and will be removed in a future release. Use DEBUG-level logging instead, see Logging with GWpy.

connectionnds2.connection, optional

Open NDS connection to use. Default is to open a new connection using host and port arguments.

One of connection or host must be given.

padfloat, optional

Float value to insert between gaps. Default behaviour is to raise an exception when any gaps are found.

scaledbool, optional

Apply slope and bias calibration to ADC data, for non-ADC data this option has no effect.

allow_tapebool, optional

Allow data access from slow tapes. If host or connection is given, the default is to do whatever the server default is, otherwise servers will be searched with allow_tape=False first, then allow_tape=True if that fails.

typeint, str, optional

NDS2 channel type integer or string name to match. Default is to search for any channel type.

dtypenumpy.dtype, str, type, or dict, optional

NDS2 data type to match. Default is to search for any data type.

Returns:
dataTimeSeriesBaseDict

A new TimeSeriesBaseDict of (str, TimeSeries) pairs fetched from NDS.

classmethod fetch_open_data(
detectors: str,
start: SupportsToGps,
end: SupportsToGps,
*,
sample_rate: float = 4096,
version: int | None = None,
format: str = 'hdf5',
host: str = 'https://gwosc.org',
verbose: bool | None = None,
cache: bool | None = None,
parallel: int = 1,
**kwargs,
) → Self[source]#

Fetch open-access data from the LIGO Open Science Center.

This is just a shim around TimeSeriesDict.get(..., source='gwosc').

Parameters:
detectorslist of str

List of two-character prefices of the IFOs in which you are interested, e.g. ['H1', 'L1'].

startLIGOTimeGPS, float, str

GPS start time of required data, any input parseable by to_gps is fine.

endLIGOTimeGPS, float, str

GPS end time of required data, any input parseable by to_gps is fine.

sample_ratefloat, Quantity,

The sample rate (Hertz) of desired data; most data are stored by GWOSC at 4096 Hz, however there may be event-related data releases with a 16384 Hz rate.

versionint

Version of files to download, defaults to highest discovered version.

formatstr

The data format to download and parse. One of

“hdf5”

HDF5 data files, read using h5py.

“gwf”

Gravitational-Wave Frame files, requires LDAStools.frameCPP.

hoststr

Host name of GWOSC server to access.

verbosebool

This argument is deprecated and will be removed in a future release. Use DEBUG-level logging instead, see Logging with GWpy.

cachebool

Save/read a local copy of the remote URL, default: False; useful if the same remote data are to be accessed multiple times. Set GWPY_CACHE=1 in the environment to auto-cache.

parallelint

Number of parallel threads to use when downloading data for multiple detectors. Default is 1.

kwargs

Any other keyword arguments are passed to the TimeSeries.read method that parses the file that was downloaded.

See also

TimeSeries.fetch_open_data

For more examples.

TimeSeries.read

For details of how files are read.

Examples

>>> from gwpy.timeseries import TimeSeriesDict
>>> print(TimeSeriesDict.fetch_open_data(['H1', 'L1'], 1126259446, 1126259478))
TimeSeriesDict({'H1': <TimeSeries([2.17704028e-19, 2.08763900e-19, 2.39681183e-19, ...,
             3.55365541e-20, 6.33533516e-20, 7.58121195e-20]
            unit=Unit(dimensionless),
            t0=<Quantity 1.12625945e+09 s>,
            dt=<Quantity 0.00024414 s>,
            name='Strain',
            channel=None)>, 'L1': <TimeSeries([-1.04289994e-18, -1.03586274e-18, -9.89322445e-19,
             ..., -1.01767748e-18, -9.82876816e-19,
             -9.59276974e-19]
            unit=Unit(dimensionless),
            t0=<Quantity 1.12625945e+09 s>,
            dt=<Quantity 0.00024414 s>,
            name='Strain',
            channel=None)>})
classmethod find(
channels: list[str | Channel],
start: SupportsToGps,
end: SupportsToGps,
*,
observatory: str | None = None,
frametype: str | None = None,
frametype_match: str | re.Pattern | None = None,
host: str | None = None,
urltype: str | None = 'file',
ext: str = 'gwf',
pad: float | None = None,
scaled: bool | None = None,
allow_tape: bool | None = None,
parallel: int = 1,
verbose: bool | str = False,
**readargs,
) → Self[source]#

Find and read data from frames for a number of channels.

This method uses gwdatafind to discover the (file://) URLs that provide the requested data, then reads those files using TimeSeriesDict.read().

This is just a shim around TimeSeriesDict.get(..., source="gwdatafind").

Parameters:
channelslist

List of names of data channels to find.

startLIGOTimeGPS, float, str

GPS start time of required data, any input parseable by to_gps is fine

endLIGOTimeGPS, float, str

GPS end time of required data, defaults to end of data found; any input parseable by to_gps is fine

observatorystr, optional

The observatory to use when searching for data. Default is to use the observatory from the channel name prefix, but this should be specified when searching for data in a multi-observatory dataset (e.g. observatory='HLV').

frametypestr, optional

Name of frametype (dataset) in which this channel is stored. Default is to search all available datasets for a match, which can be very slow.

frametype_matchstr, optional

Regular expression to use for frametype matching.

hoststr, optional

Name of the GWDataFind server to use. Default is set by gwdatafind.utils.get_default_host.

urltypestr, optional

The URL type to use. Default is “file” to use paths available on the file system.

extstr, optional

The file extension for which to search. “gwf” is the only file extension supported, but this may be extended in the future.

padfloat, optional

Value with which to fill gaps in the source data, by default gaps will result in a ValueError.

scaledbool, optional

Apply slope and bias calibration to ADC data, for non-ADC data this option has no effect.

parallelint, optional

Number of parallel threads to use when reading data.

allow_tapebool, optional

Allow reading from frame files on (slow) magnetic tape.

verbosebool, optional

This argument is deprecated and will be removed in a future release. Use DEBUG-level logging instead, see Logging with GWpy.

readargs

Any other keyword arguments to be passed to read().

Raises:
requests.exceptions.HTTPError

If the GWDataFind query fails for any reason.

RuntimeError

If no files are found to read, or if the read operation fails.

classmethod from_arrakis(
block: arrakis.SeriesBlock,
*,
copy: bool = True,
**metadata,
) → Self[source]#

Construct a new dict from an arrakis.SeriesBlock.

Parameters:
blockarrakis.SeriesBlock

The input Arrakis data to read.

copybool, optional

If True, copy the contained data array to new to a new array.

metadata

Any other metadata keyword arguments to pass to the TimeSeries constructor.

Returns:
dictTimeSeriesDict

A new TimeSeriesDict containing the data from the Arrakis block.

classmethod from_nds2_buffers(
buffers: Iterable[nds2.buffer],
*,
scaled: bool | None = None,
copy: bool = True,
**metadata,
) → Self[source]#

Construct a new dict from a list of nds2.buffer objects.

Requires: NDS2

Parameters:
bufferslist of nds2.buffer

The input NDS2-client buffers to read.

scaledbool, optional

Apply slope and bias calibration to ADC data, for non-ADC data this option has no effect.

copybool, optional

If True, copy the contained data array to new to a new array.

metadata

Any other metadata keyword arguments to pass to the TimeSeries constructor.

Returns:
dictTimeSeriesDict

A new TimeSeriesDict containing the data from the given buffers.

plot(
label: str = 'key',
method: str = 'plot',
figsize: tuple[float, float] = (12, 4),
xscale: str = 'auto-gps',
**kwargs,
) → Plot[source]#

Plot the data for this TimeSeriesBaseDict.

Parameters:
labelstr, optional

Labelling system to use, or fixed label for all elements Special values include

If anything else, that fixed label will be used for all lines.

methodstr, optional

The plotting method to use. This can be any method supported by the underlying plotting library (e.g., Matplotlib).

figsizetuple[float, float], optional

The size of the figure to create, in inches.

xscalestr, optional

The scale of the x-axis. This can be one of

  • 'linear': linear scale

  • 'log': logarithmic scale

  • 'auto-gps': automatically determine scale based on GPS time

kwargs

All other keyword arguments are passed to the plotter as appropriate.

prepend(other: Mapping[str | Channel, _V], **kwargs) → Self[source]#

Prepend the dict other to this one.

Parameters:
otherdict of TimeSeries

The container to prepend to this one.

copybool, optional

If True copy data from other before storing, only affects those keys in other that aren’t in self.

kwargs

Other keyword arguments to send to TimeSeries.prepend.

See also

TimeSeries.prepend

For details of the underlying series prepend operation.

resample(
rate: dict[str | Channel, float] | float,
**kwargs,
) → Self[source]#

Resample items in this dict.

This operation over-writes items inplace.

Parameters:
ratedict, float

either a dict of (channel, float) pairs for key-wise resampling, or a single float/int to resample all items.

**kwargs

other keyword arguments to pass to each item’s resampling method.

step(
label: str = 'key',
where: Literal['pre', 'post', 'mid'] = 'post',
figsize: tuple[float, float] = (12, 4),
xscale: str = 'auto-gps',
**kwargs,
) → Plot[source]#

Create a step plot of this dict.

Parameters:
labelstr, optional

Labelling system to use, or fixed label for all elements. Special values include

'key'

Use the key of the TimeSeriesBaseDict

'name'

Use the name of each element

If anything else, that fixed label will be used for all lines.

wherestr, optional

The location of the step change. This can be one of

  • 'pre': the step change occurs before the x value

  • 'post': the step change occurs after the x value

  • 'mid': the step change occurs at the midpoint of the x value

figsizetuple[float, float], optional

The size of the figure to create, in inches.

xscalestr, optional

The scale of the x-axis. This can be one of

  • 'linear': linear scale

  • 'log': logarithmic scale

  • 'auto-gps': automatically determine scale based on GPS time

kwargs

All other keyword arguments are passed to the plotter as appropriate.