StateVectorDict

class gwpy.timeseries.StateVectorDict

Ordered key-value mapping of named StateVector objects.

This object is designed to hold data for many different sources (channels) for a single time span.

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

Attributes Summary

read	Read data into a StateVectorDict.
span	The GPS [start, stop) extent of data in this dict.
write	Write this StateVectorDict to a file.

Methods Summary

append(other[, copy])	Append the dict other to this one.
clear()
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.
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.
fromkeys(/, iterable[, value])	Create a new ordered dictionary with keys from iterable and values set to value.
get(channels, start, end, *[, source, verbose])	Retrieve data for multiple channels from any data source.
items()
keys()
move_to_end(/, key[, last])	Move an existing element to the end (or beginning if last is false).
plot([label, method, figsize, xscale])	Plot the data for this TimeSeriesBaseDict.
pop(/, key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem(/[, last])	Remove and return a (key, value) pair from the dictionary.
prepend(other, **kwargs)	Prepend the dict other to this one.
resample(rate, **kwargs)	Resample items in this dict.
setdefault(/, key[, default])	Insert key with a value of default if key is not in the dictionary.
step([label, where, figsize, xscale])	Create a step plot of this dict.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

Attributes Documentation

read

Read data into a StateVectorDict.

Arguments and keywords depend on the output format, see the online documentation for full details for each format, the parameters below are common to most formats.

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.

namestr, Channel

the name of the channel to read, or a Channel object.

startLIGOTimeGPS, float, str, optional

GPS start time of required data, defaults to start of data found; 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

formatstr, optional

source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats.

parallelint, optional

number of parallel processes to use, serial process by default.

padfloat, optional

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

gapstr, optional

How to handle gaps in the data, one of

“ignore”

Do nothing, let the underlying reader method handle it.

“warn”

Do nothing except print a warning to the screen.

“raise”

Raise an exception upon finding a gap (default).

“pad”

Insert a value to fill the gaps.

Raises:

IndexError

if source is an empty list

span

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

Type:

Segment

write

Write this StateVectorDict to a file.

Arguments and keywords depend on the output format, see the online documentation for full details for each format, the parameters below are common to most formats.

Parameters:

targetstr

output filename

formatstr, optional

output format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats.

Methods Documentation

append(other, copy=True, **kwargs)

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

clear() → None.  Remove all items from od.

copy()

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

crop(start=None, end=None, copy=False)

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: GpsLike, end: GpsLike, *, 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)

Fetch data from NDS for a number of channels.

Parameters:

channelstr, Channel

The name (or representation) of the data channel to fetch.

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

Print verbose progress information about NDS download. If verbose is specified as a string, this defines the prefix for the progress meter.

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 find(channels: list[str | Channel], start: GpsLike, end: GpsLike, *, observatory: str | None = None, frametype: str | None = None, frametype_match: str | re.Pattern | None = None, pad: float | None = None, scaled: bool | None = None, allow_tape: bool | None = None, parallel: int = 1, verbose: bool | str = False, **readargs) → Self

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().

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.

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

Print verbose output about read progress, if verbose is specified as a string, this defines the prefix for the progress meter.

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=True, **metadata)

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, scaled=None, copy=True, **metadata)

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

classmethod fromkeys(/, iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

classmethod get(channels: list[str | Channel], start: GpsLike, end: GpsLike, *, source: str | list[str] | None = None, verbose: bool = False, **kwargs)

Retrieve data for multiple channels from any data source.

This method attemps to get data any way it can, potentially iterating over multiple available data sources.

Parameters:

channelslist

Required data channels.

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

sourcestr

The data source to use. Give one of

“files”

Use gwdatafind to find the paths of local files and then read them.

“nds2”

Use NDS2.

frametypestr

Name of frametype in which this channel is stored, by default will search for all required frame types.

padfloat

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

scaledbool

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

nprocint, default: 1

Number of parallel processes to use, serial process by default.

allow_tapebool, default: None

Allow the use of data files that are held on tape. Default is None to attempt to allow the TimeSeries.fetch method to intelligently select a server that doesn’t use tapes for data storage (doesn’t always work), but to eventually allow retrieving data from tape if required.

verbosebool

Print verbose output about data access progress. If verbose is specified as a string, this defines the prefix for the progress meter.

kwargs

Other keyword arguments to pass to the data access function for each data source.

See also

TimeSeries.find

For details of how data are accessed for source="files" and the supported keyword arguments.

TimeSeries.fetch

For details of how data are accessed for source="nds2" and the supported keyword arguments.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

move_to_end(/, key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

plot(label='key', method='plot', figsize=(12, 4), xscale='auto-gps', **kwargs)

Plot the data for this TimeSeriesBaseDict.

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.

**kwargs

all other keyword arguments are passed to the plotter as appropriate

pop(/, key, default=<unrepresentable>)

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(/, last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

prepend(other, **kwargs)

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, **kwargs)

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.

setdefault(/, key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

step(label='key', where='post', figsize=(12, 4), xscale='auto-gps', **kwargs)

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.

**kwargs

all other keyword arguments are passed to the plotter as appropriate

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values