DataQualityFlag¶

class gwpy.segments.DataQualityFlag(name=None, active=None, known=None, label=None, category=None, description=None, isgood=True, padding=None)[source]¶

A representation of a named set of segments.

Parameters¶

namestr, optional: The name of this flag. This should be of the form {ifo}:{tag}:{version}, e.g. ‘H1:DMT-SCIENCE:1’. Use label for human-readable names.
activeSegmentList, optional: A list of active segments for this flag
knownSegmentList, optional: A list of known segments for this flag
labelstr, optional: Human-readable name for this flag, e.g. 'Science-mode'
categoryint, optional: Veto category for this flag.
descriptionstr, optional: Human-readable description of why this flag was created.
isgoodbool, optional: Do active segments mean the IFO was in a good state?

Attributes Summary

`active`	The set of segments during which this flag was active.
`category`	Veto category for this flag.
`description`	Description of why/how this flag was generated.
`extent`	The single GPS `[start, stop)` enclosing segment of this `DataQualityFlag`.
`ifo`	The interferometer associated with this flag.
`isgood`	Whether `active` segments mean the instrument was in a good state.
`known`	The set of segments during which this flag was known, and its state was well defined.
`label`	A human-readable label for this flag.
`livetime`	Amount of time this flag was `active`.
`name`	The name associated with this flag.
`padding`	[start, end) padding for this flag's active segments.
`regular`	`True` if the `active` segments are a proper subset of the `known`.
`tag`	The tag (name) associated with this flag.
`texname`	Name of this flag in LaTeX printable format.
`version`	The version number of this flag.

Methods Summary

`coalesce`()	Coalesce the segments for this flag.
`contract`(x)	Contract each of the `active` `Segments` by `x` seconds.
`copy`()	Build an exact copy of this flag.
`fetch_open_data`(flag, start, end, **kwargs)	Fetch Open Data timeline segments into a flag.
`from_veto_def`(veto)	Define a `DataQualityFlag` from a `VetoDef`
`pad`(args, *kwargs)	Apply a padding to each segment in this `DataQualityFlag`
`plot`([figsize, xscale])	Plot this flag on a segments projection.
`populate`([source, segments, pad])	Query the segment database for this flag's active segments.
`protract`(x)	Protract each of the `active` `Segments` by `x` seconds.
`query`(flag, args, *kwargs)	Query the advanced LIGO DQSegDB for the given flag
`query_dqsegdb`(flag, args, *kwargs)	Query the advanced LIGO DQSegDB for the given flag
`read`(source, args, *kwargs)	Read segments from file into a `DataQualityFlag`.
`round`([contract])	Round this flag to integer segments.
`write`(target, args, *kwargs)	Write this `DataQualityFlag` to file

Attributes Documentation

active¶: The set of segments during which this flag was active.

category¶

Veto category for this flag.

Type¶: int

description¶

Description of why/how this flag was generated.

Type¶: str

extent¶

The single GPS [start, stop) enclosing segment of this DataQualityFlag.

Type¶: Segment

ifo¶

The interferometer associated with this flag.

This should be a single uppercase letter and a single number, e.g. 'H1'.

Type¶: str

isgood¶

Whether active segments mean the instrument was in a good state.

Type¶: bool

known¶: The set of segments during which this flag was known, and its state was well defined.

label¶

A human-readable label for this flag.

For example: 'Science-mode'.

Type¶: str

livetime¶

Amount of time this flag was active.

Type¶: float

name¶

The name associated with this flag.

This normally takes the form {ifo}:{tag}:{version}. If found, each component is stored separately the associated attributes.

Type¶: str

padding¶: [start, end) padding for this flag’s active segments.

regular¶

True if the active segments are a proper subset of the known.

Type¶: bool

tag¶

The tag (name) associated with this flag.

This should take the form 'AAA-BBB_CCC_DDD', i.e. where each component is an uppercase acronym of alphanumeric characters only, e.g. 'DCH-IMC_BAD_CALIBRATION' or 'DMT-SCIENCE'.

Type¶: str

texname¶: Name of this flag in LaTeX printable format.

version¶

The version number of this flag.

Each flag in the segment database is stored with a version integer, with each successive version representing a more accurate dataset for its known segments than any previous.

Type¶: int

Methods Documentation

coalesce()[source]¶

Coalesce the segments for this flag.

This method does two things:

coalesces the known and active segment lists
forces the active segments to be a proper subset of the known segments

Note

this operations is performed in-place.

Returns¶

self: a view of this flag, not a copy.

contract(x)[source]¶

Contract each of the active Segments by x seconds.

This method adds x to each segment’s lower bound, and subtracts x from the upper bound.

The active SegmentList is modified in place.

Parameters¶

xfloat: number of seconds by which to contract each Segment.

copy()[source]¶

Build an exact copy of this flag.

Returns¶

flag2DataQualityFlag: a copy of the original flag, but with a fresh memory address.

classmethod fetch_open_data(flag, start, end, **kwargs)[source]¶

Fetch Open Data timeline segments into a flag.

flagstr: the name of the flag to query
startint, str: the GPS start time (or parseable date string) to query
endint, str: the GPS end time (or parseable date string) to query
verbosebool, optional: show verbose download progress, default: False
timeoutint, optional: timeout for download (seconds)
hoststr, optional: URL of GWOSC host, default: 'https://gw-openscience.org'

Returns¶

flagDataQualityFlag: a new flag with active segments filled from Open Data

Examples

>>> from gwpy.segments import DataQualityFlag
>>> print(DataQualityFlag.fetch_open_data('H1_DATA', 'Jan 1 2010',
...                                       'Jan 2 2010'))
<DataQualityFlag('H1:DATA',
                 known=[[946339215 ... 946425615)],
                 active=[[946340946 ... 946351800)
                         [946356479 ... 946360620)
                         [946362652 ... 946369150)
                         [946372854 ... 946382630)
                         [946395595 ... 946396751)
                         [946400173 ... 946404977)
                         [946412312 ... 946413577)
                         [946415770 ... 946422986)],
                 description=None)>

classmethod from_veto_def(veto)[source]¶

Define a DataQualityFlag from a VetoDef

Parameters¶

vetoVetoDef: veto definition to convert from

pad(*args, **kwargs)[source]¶

Apply a padding to each segment in this DataQualityFlag

This method either takes no arguments, in which case the value of the padding attribute will be used, or two values representing the padding for the start and end of each segment.

For both the start and end paddings, a positive value means pad forward in time, so that a positive start pad or negative end padding will contract a segment at one or both ends, and vice-versa.

This method will apply the same padding to both the known and active lists, but will not coalesce() the result.

Parameters¶

startfloat: padding to apply to the start of the each segment
endfloat: padding to apply to the end of each segment
inplacebool, optional, default: False: modify this object in-place, default is False, i.e. return a copy of the original object with padded segments

Returns¶

paddedflagDataQualityFlag: a view of the modified flag

plot(figsize=(12, 4), xscale='auto-gps', **kwargs)[source]¶

Plot this flag on a segments projection.

Parameters¶

**kwargs: all keyword arguments are passed to the Plot constructor.

Returns¶

figureFigure: the newly created figure, with populated Axes.

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_segmentlist: for documentation of keyword arguments used in rendering the data

populate(source='http://segments.ldas.cit', segments=None, pad=True, **kwargs)[source]¶

Query the segment database for this flag’s active segments.

This method assumes all of the metadata for each flag have been filled. Minimally, the following attributes must be filled

`name`	The name associated with this flag.
`known`	The set of segments during which this flag was known, and its state was well defined.

Segments will be fetched from the database, with any padding added on-the-fly.

This DataQualityFlag will be modified in-place.

Parameters¶

sourcestr: source of segments for this flag. This must be either a URL for a segment database or a path to a file on disk.
segmentsSegmentList, optional: a list of segments during which to query, if not given, existing known segments for this flag will be used.
padbool, optional, default: True: apply the padding associated with this flag, default: True.
**kwargs: any other keyword arguments to be passed to DataQualityFlag.query() or DataQualityFlag.read().

Returns¶

selfDataQualityFlag: a reference to this flag

protract(x)[source]¶

Protract each of the active Segments by x seconds.

This method subtracts x from each segment’s lower bound, and adds x to the upper bound, while maintaining that each Segment stays within the known bounds.

The active SegmentList is modified in place.

Parameters¶

xfloat: number of seconds by which to protact each Segment.

classmethod query(flag, *args, **kwargs)[source]¶

Query the advanced LIGO DQSegDB for the given flag

Parameters¶

flagstr: The name of the flag for which to query
*args: Either, two float-like numbers indicating the GPS [start, stop) interval, or a SegmentList defining a number of summary segments
urlstr, optional: URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns¶

flagDataQualityFlag: A new DataQualityFlag, with the known and active lists filled appropriately.

classmethod query_dqsegdb(flag, *args, **kwargs)[source]¶

Query the advanced LIGO DQSegDB for the given flag

Parameters¶

flagstr: The name of the flag for which to query
*args: Either, two float-like numbers indicating the GPS [start, stop) interval, or a SegmentList defining a number of summary segments
urlstr, optional: URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns¶

flagDataQualityFlag: A new DataQualityFlag, with the known and active lists filled appropriately.

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

Read segments from file into a DataQualityFlag.

Parameters¶

filenamestr: path of file to read
namestr, optional: name of flag to read from file, otherwise read all segments.
formatstr, optional: source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats.
coltypetype, optional, default: float: datatype to force for segment times, only valid for format='segwizard'.
strictbool, optional, default: True: require segment start and stop times match printed duration, only valid for format='segwizard'.
coalescebool, optional: if True coalesce the all segment lists before returning, otherwise return exactly as contained in file(s).
nprocint, optional, default: 1: number of CPUs to use for parallel reading of multiple files
verbosebool, optional, default: False: print a progress bar showing read status

Returns¶

dqflagDataQualityFlag: formatted DataQualityFlag containing the active and known segments read from file.

Raises¶

IndexError: if source is an empty list

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	Yes	Yes
json	Yes	No	No
ligolw	Yes	Yes	Yes

round(contract=False)[source]¶

Round this flag to integer segments.

Parameters¶

contractbool, optional: if False (default) expand each segment to the containing integer boundaries, otherwise contract each segment to the contained boundaries

Returns¶

roundedflagDataQualityFlag: A copy of the original flag with the active and known segments padded out to integer boundaries.

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

Write this DataQualityFlag to file

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	Yes	Yes
json	Yes	Yes	No
ligolw	Yes	Yes	Yes