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

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(k[,d])	value.
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)

Append the dict other to this one

Parameters

other : dict of TimeSeries

the container to append to this one

copy : bool, 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

start : LIGOTimeGPS, float, str

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

end : LIGOTimeGPS, float, str, optional

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

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)

Fetch data from NDS for a number of channels.

Parameters

channels : list

required data channels.

start : LIGOTimeGPS, float, str

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

end : LIGOTimeGPS, float, str, optional

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

host : str, optional

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

port : int, optional

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

verify : bool, optional, default: True

check channels exist in database before asking for data

verbose : bool, optional

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

connection : nds2.connection, optional

open NDS connection to use.

scaled : bool, optional

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

allow_tape : bool, 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

type : int, str, optional

NDS2 channel type integer or string name.

dtype : numpy.dtype, str, type, or dict

numeric data type for returned data, e.g. numpy.float, or dict of (channel, dtype) pairs

Returns

data : TimeSeriesBaseDict

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

classmethod find(channels, start, end, frametype=None, frametype_match=None, pad=None, scaled=None, dtype=None, nproc=1, verbose=False, allow_tape=True, observatory=None, **readargs)

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

Parameters

channels : list

required data channels.

start : LIGOTimeGPS, float, str

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

end : LIGOTimeGPS, float, str, optional

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

frametype : str, optional

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

frametype_match : str, optional

regular expression to use for frametype matching

pad : float, optional

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

scaled : bool, optional

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

dtype : numpy.dtype, str, type, or dict

numeric data type for returned data, e.g. numpy.float, or dict of (channel, dtype) pairs

nproc : int, optional, default: 1

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

allow_tape : bool, optional, default: True

allow reading from frame files on (slow) magnetic tape

verbose : bool, 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()

classmethod from_nds2_buffers(buffers, scaled=None, copy=True, **metadata)

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

Requires: nds2

Parameters

buffers : list of nds2.buffer

the input NDS2-client buffers to read

scaled : bool, optional

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

copy : bool, 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

dict : TimeSeriesDict

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)

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

channels : list

required data channels.

start : LIGOTimeGPS, float, str

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

end : LIGOTimeGPS, float, str, optional

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

frametype : str, optional

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

pad : float, optional

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

scaled : bool, optional

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

dtype : numpy.dtype, str, type, or dict

numeric data type for returned data, e.g. numpy.float, or dict of (channel, dtype) pairs

nproc : int, optional, default: 1

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

allow_tape : bool, 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

verbose : bool, 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)

Plot the data for this TimeSeriesBaseDict.

Parameters

label : str, 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(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

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

other : dict of TimeSeries

the container to prepend to this one

copy : bool, 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)

Read data for multiple bit vector channels into a StateVectorDict

Parameters

source : str, list

Source of data, any of the following:

• str path of single data file,

• str path of LAL-format cache file,

• list of paths.

channels : ChannelList, list

a list of channels to read from the source.

start : LIGOTimeGPS, float, str optional

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

end : LIGOTimeGPS, float, str, optional

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

bits : list of lists, dict, optional

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

format : str, optional

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

nproc : int, optional, default: 1

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

gap : str, 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

pad : float, optional

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

Returns

statevectordict : StateVectorDict

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)

Resample items in this dict.

This operation over-writes items inplace.

Parameters

rate : dict, 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

label : str, 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)

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

target : str

output filename

format : str, 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