StateVectorDict¶

class gwpy.timeseries.StateVectorDict[source]¶

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

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

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[, frametype, ...])	Find and read data from frames for a number of channels.
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[, pad, scaled, ...])	Retrieve data for multiple channels from frames or NDS
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
read(source, *args, **kwargs)	Read data for multiple bit vector channels into a StateVectorDict
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()
write(target, *args, **kwargs)	Write this TimeSeriesDict to a file

Attributes Documentation

span¶

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

Type:¶

Segment

Methods Documentation

append(other, copy=True, **kwargs)[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

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

copy()[source]¶

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

crop(start=None, end=None, copy=False)[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, start, end, host=None, port=None, verify=False, verbose=False, connection=None, pad=None, scaled=None, allow_tape=None, type=None, dtype=None)[source]¶

Fetch data from NDS for a number of channels.

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

portint, optional

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

verifybool, optional, default: True

check channels exist in database before asking for data

verbosebool, optional

print verbose output about NDS download progress, if verbose is specified as a string, this defines the prefix for the progress meter

connectionnds2.connection, optional

open NDS connection to use.

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 in logical order allowing tape access if necessary to retrieve the data

typeint, str, optional

NDS2 channel type integer or string name to match.

dtypenumpy.dtype, str, type, or dict

NDS2 data type to match

Returns:¶

dataTimeSeriesBaseDict

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

classmethod find(channels, start, end, frametype=None, frametype_match=None, pad=None, scaled=None, nproc=1, verbose=False, allow_tape=True, observatory=None, **readargs)[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().

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, defaults to end of data found; any input parseable by to_gps is fine

frametypestr

Name of frametype in which this channel is stored; if not given all frametypes discoverable via GWDataFind will be searched for the required channels.

frametype_matchstr

Regular expression to use for frametype matching.

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

Number of parallel processes to use.

allow_tapebool

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

fromkeys(/, iterable, value=None)¶

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

classmethod get(channels, start, end, pad=None, scaled=None, dtype=None, verbose=False, allow_tape=None, **kwargs)[source]¶

Retrieve data for multiple channels from frames or NDS

This method dynamically accesses either frames on disk, or a remote NDS2 server to find and return data for the given interval

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, optional

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

frametypestr, optional

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

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.

nprocint, optional, default: 1

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

allow_tapebool, optional, default: None

allow the use of frames 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, optional

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 either TimeSeriesBaseDict.find (for direct GWF file access) or TimeSeriesBaseDict.fetch for remote NDS2 access

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)[source]¶

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)[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

classmethod read(source, *args, **kwargs)[source]¶

Read data for multiple bit vector channels into a StateVectorDict

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.

channelsChannelList, list

a list of channels to read from the source.

startLIGOTimeGPS, float, str optional

GPS start time of required data, anything parseable by to_gps() is fine

endLIGOTimeGPS, float, str, optional

GPS end time of required data, anything parseable by to_gps() is fine

bitslist of lists, dict, optional

the ordered list of interesting bit lists for each channel, or a dict of (channel, list) pairs

formatstr, optional

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

nprocint, optional, default: 1

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

gapstr, optional

how to handle gaps in the cache, 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

padfloat, optional

value with which to fill gaps in the source data, only used if gap is not given, or gap='pad' is given

Returns:¶

statevectordictStateVectorDict

a StateVectorDict of (channel, StateVector) pairs. The keys are guaranteed to be the ordered list channels as given.

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
gwf	Yes	Yes	Yes
gwf.framecpp	Yes	Yes	No
gwf.framel	Yes	Yes	No
gwf.lalframe	Yes	Yes	No
hdf5	Yes	No	No

resample(rate, **kwargs)[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.

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

**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¶

write(target, *args, **kwargs)[source]¶

Write this TimeSeriesDict to a file

Arguments and keywords depend on the output format, see the online documentation for full details for each format.

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.

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
gwf	Yes	Yes	Yes
gwf.framecpp	Yes	Yes	No
gwf.framel	Yes	Yes	No
gwf.lalframe	Yes	Yes	No
hdf5	Yes	Yes	No