TimeSeriesDict¶
- class gwpy.timeseries.TimeSeriesDict[source]¶
Ordered key-value mapping of named
TimeSeries
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()
andfetch()
data access methods.Attributes Summary
Read data into a
TimeSeriesDict
.The GPS
[start, stop)
extent of data in thisdict
.Write this
TimeSeriesDict
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[, frametype, ...])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
TimeSeriesDict
.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:¶
- source
str
,list
Source of data, any of the following:
- name
str
,Channel
the name of the channel to read, or a
Channel
object.- start
LIGOTimeGPS
,float
,str
, optional GPS start time of required data, defaults to start of data found; 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- format
str
, optional source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats.
- parallel
int
, optional number of parallel processes to use, serial process by default.
- pad
float
, optional value with which to fill gaps in the source data, by default gaps will result in a
ValueError
.
- source
- Raises:¶
- IndexError
if
source
is an empty list
- write¶
Write this
TimeSeriesDict
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.
Methods Documentation
-
append(other, copy=
True
, **kwargs)[source]¶ Append the dict
other
to this one.- Parameters:¶
- other
dict
ofTimeSeries
the container to append to this one
- copy
bool
, optional if
True
copy data fromother
before storing, only affects those keys inother
that aren’t inself
- **kwargs
other keyword arguments to send to
TimeSeries.append
- other
See also
TimeSeries.append
for details of the underlying series append operation
- clear() None. Remove all items from od. ¶
-
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:¶
- 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- copy
bool
, optional, default:False
If
True
copy the data for each entry to fresh memory, otherwise return a view.
- start
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
)[source]¶ Fetch data from NDS for a number of channels.
- Parameters:¶
- channel
str
,Channel
The name (or representation) of the data channel to fetch.
- 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
One of
connection
orhost
must be given.- port
int
, optional Port number for NDS server query, must be given with
host
.- verify
bool
, optional Check channels exist in database before asking for data. Default is
True
.- verbose
bool
, optional Print verbose progress information about NDS download. If
verbose
is specified as a string, this defines the prefix for the progress meter.- connection
nds2.connection
, optional Open NDS connection to use. Default is to open a new connection using
host
andport
arguments.One of
connection
orhost
must be given.- pad
float
, optional Float value to insert between gaps. Default behaviour is to raise an exception when any gaps are found.
- 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
orconnection
is given, the default is to do whatever the server default is, otherwise servers will be searched withallow_tape=False
first, then ``allow_tape=True` if that fails.- type
int
,str
, optional NDS2 channel type integer or string name to match. Default is to search for any channel type.
- dtype
numpy.dtype
,str
,type
, ordict
, optional NDS2 data type to match. Default is to search for any data type.
- channel
- Returns:¶
- data
TimeSeriesBaseDict
A new
TimeSeriesBaseDict
of (str
,TimeSeries
) pairs fetched from NDS.
- data
-
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 usingTimeSeriesDict.read()
.- 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
GPS end time of required data, defaults to end of data found; any input parseable by
to_gps
is fine- frametype
str
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_match
str
Regular expression to use for frametype matching.
- pad
float
Value with which to fill gaps in the source data, by default gaps will result in a
ValueError
.- scaled
bool
Apply slope and bias calibration to ADC data, for non-ADC data this option has no effect.
- nproc
int
Number of parallel processes to use.
- allow_tape
bool
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()
.
- channels
- 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)[source]¶ Construct a new dict from an
arrakis.SeriesBlock
.- Parameters:¶
- block
arrakis.SeriesBlock
The input Arrakis data to read.
- 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.
- block
- Returns:¶
- dict
TimeSeriesDict
A new
TimeSeriesDict
containing the data from the Arrakis block.
- dict
-
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:¶
- buffers
list
ofnds2.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
- buffers
- Returns:¶
- dict
TimeSeriesDict
a new
TimeSeriesDict
containing the data from the given buffers
- dict
- 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)[source]¶ 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:¶
- 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
GPS end time of required data, any input parseable by
to_gps
is fine- source
str
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
.
- frametype
str
Name of frametype in which this channel is stored, by default will search for all required frame types.
- pad
float
Value with which to fill gaps in the source data, by default gaps will result in a
ValueError
.- scaled
bool
apply slope and bias calibration to ADC data, for non-ADC data this option has no effect.
- nproc
int
, default:1
Number of parallel processes to use, serial process by default.
- allow_tape
bool
, default:None
Allow the use of data files that are held on tape. Default is
None
to attempt to allow theTimeSeries.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
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.
- channels
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)[source]¶ 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 theTimeSeriesBaseDict
,'name'
: use thename
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
- label
- 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:¶
- other
dict
ofTimeSeries
the container to prepend to this one
- copy
bool
, optional if
True
copy data fromother
before storing, only affects those keys inother
that aren’t inself
- **kwargs
other keyword arguments to send to
TimeSeries.prepend
- other
See also
TimeSeries.prepend
for details of the underlying series prepend operation
- resample(rate, **kwargs)[source]¶
Resample items in this dict.
This operation over-writes items inplace.
- 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:¶
- label
str
, optional labelling system to use, or fixed label for all elements Special values include
'key'
: use the key of theTimeSeriesBaseDict
,'name'
: use thename
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
- label
- 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 ¶