StateVector

class gwpy.timeseries.StateVector(

data: ArrayLike1D,

bits: BitsInput | None = None,

t0: SupportsToGps | None = None,

dt: float | Quantity | None = None,

sample_rate: float | Quantity | None = None,

times: ArrayLike1D | None = None,

channel: Channel | str | None = None,

name: str | None = None,

**kwargs,

)

Bases: TimeSeriesBase

Binary array representing good/bad state determinations of some data.

Each binary bit represents a single boolean condition, with the definitions of all the bits stored in the StateVector.bits attribute.

Parameters:

valuearray_like

Input data array.

bitsBits, list, optional

List of bits defining this StateVector.

t0LIGOTimeGPS, float, str, optional

GPS epoch associated with these data, any input parsable by to_gps is fine.

dtfloat, Quantity, optional

Time between successive samples (seconds), can also be given inversely via sample_rate.

sample_ratefloat, Quantity, optional

The rate of samples per second (Hertz), can also be given inversely via dt.

timesarray-like

The complete array of GPS times accompanying the data for this series. This argument takes precedence over t0 and dt so should be given in place of these if relevant, not alongside.

namestr, optional

Descriptive title for this array.

channelChannel, str, optional

Source data stream for these data.

dtypedtype, optional

Input data type.

copybool, optional

Choose to copy the input data to new memory.

subokbool, optional

Allow passing of sub-classes by the array generator.

Notes

Key methods:

fetch(channel, start, end, *[, bits, host, ...])	Fetch data from NDS into a StateVector.
read	Read data into a StateVector.
write	Write this StateVector to a file.
to_dqflags(bits, minlen, dtype, *, round)	Convert this StateVector into a DataQualityDict.
plot([format, bits])	Plot the data for this StateVector.

Attributes Summary

bits	List of Bits for this StateVector.
boolean	A 2-D boolean array representation of this StateVector.
get	Retrieve StateVector data for a channel.
read	Read data into a StateVector.
write	Write this StateVector to a file.

Methods Summary

fetch(channel, start, end, *[, bits, host, ...])	Fetch data from NDS into a StateVector.
get_bit_series([bits])	Get the StateTimeSeries for each bit of this StateVector.
plot([format, bits])	Plot the data for this StateVector.
resample(rate)	Resample this StateVector to a new rate.
to_dqflags(bits, minlen, dtype, *, round)	Convert this StateVector into a DataQualityDict.

Attributes Documentation

bits

List of Bits for this StateVector.

Type:

Bits

boolean

A 2-D boolean array representation of this StateVector.

get

Retrieve StateVector data for a channel.

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

Parameters:

namestr, Channel

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

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.

bitsBits, list, optional

Definition of bits for this StateVector

sourcestr, list, list of dict.

The data source to use. One of the following formats:

• str - the name of a single source to use,

• list - a list of source names to try in order,

• list of dict - a list of source specifications to try in order; each dict must contain a "source" key giving the name of the source to use, and may contain other keys giving options to pass to the data access function for that source.

See ‘Notes’ section below for valid source names.

nprocint, optional

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

verbosebool, optional

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

kwargs

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

read

Read data into a StateVector.

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, os.PathLike, file, or list of these

Source of data, any of the following:

• Path of a single data file

• List of data file paths

• Path of LAL-format cache file

namestr, optional

The name of the data object to read, or a Channel object. This argument is required if source contains (or may contain) multiple datasets.

• When reading from GWF, this argument should specify the name of the channel to read.

• When reading from HDF5, this argument should specify the path or dataset name within the file.

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.

bitslist, optional

List of bits names for this StateVector, give None at any point in the list to mask that bit.

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.

Raises:

IndexError

If source is an empty list.

write

Write this StateVector 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

classmethod fetch(

channel: str | Channel,

start: SupportsToGps,

end: SupportsToGps,

*,

bits: Bits | BitsInput | None = None,

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

Fetch data from NDS into a StateVector.

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

bitsBits, list, optional

Definition of bits for this StateVector.

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.

padfloat, optional

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

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.

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.

get_bit_series(

bits: Iterable[int | str] | None = None,

) → StateTimeSeriesDict

Get the StateTimeSeries for each bit of this StateVector.

Parameters:

bitslist, optional

A list of bit indices or bit names, defaults to all bits.

Returns:

bitseriesStateTimeSeriesDict

A dict of StateTimeSeries, one for each given bit.

plot(

format: Literal['timeseries', 'segments'] = 'segments',

bits: Iterable[int | str] | None = None,

**kwargs,

) → Plot

Plot the data for this StateVector.

Parameters:

formatstr, optional

The type of plot to make, either ‘segments’ to plot the SegmentList for each bit, or ‘timeseries’ to plot the raw data for this StateVector.

bitslist, optional

A list of bit indices or bit names, defaults to bits. This argument is ignored if format is not 'segments'.

kwargs

Other keyword arguments to be passed to either plot or plot, depending on format.

Returns:

plotPlot

Output plot object.

See also

matplotlib.pyplot.figure

For documentation of keyword arguments used to create the figure.

matplotlib.figure.Figure.add_subplot

For documentation of keyword arguments used to create the axes.

gwpy.plot.SegmentAxes.plot_flag

For documentation of keyword arguments used in rendering each statevector flag.

resample(rate: float | Quantity) → StateVector

Resample this StateVector to a new rate.

Because of the nature of a state-vector, downsampling is done by taking the logical ‘and’ of all original samples in each new sampling interval, while upsampling is achieved by repeating samples.

Parameters:

ratefloat

Rate to which to resample this StateVector, must be a divisor of the original sample rate (when downsampling) or a multiple of the original (when upsampling).

Returns:

vectorStateVector

Resampled version of the input StateVector.

to_dqflags(

bits: Iterable[int | str] | None = None,

minlen: int = 1,

dtype: type = <class 'float'>,

*,

round: bool = False,

) → DataQualityDict

Convert this StateVector into a DataQualityDict.

The StateTimeSeries for each bit is converted into a DataQualityFlag with the bits combined into a dict.

Parameters:

bitslist, optional

A list of bit indices or bit names to select, defaults to bits.

minlenint, optional

Minimum number of consecutive True values to identify as a Segment. This is useful to ignore single bit flips, for example.

dtypetype, optional

Output segment entry type, can pass either a type for simple casting, or a callable function that accepts a float and returns another numeric type, defaults to float.

roundbool, optional

Choose to round each Segment to its inclusive integer boundaries.

Returns:

DataQualityFlag listlist

A list of DataQualityFlag representations for each bit in this StateVector.

See also

StateTimeSeries.to_dqflag

For details on the segment representation method for StateVector bits.