DataQualityFlag

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

A representation of a named set of segments.

Parameters

name : str, 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.

active : SegmentList, optional

A list of active segments for this flag

known : SegmentList, optional

A list of known segments for this flag

label : str, optional

Human-readable name for this flag, e.g. 'Science-mode'

category : int, optional

Veto category for this flag.

description : str, optional

Human-readable description of why this flag was created.

isgood : bool, 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 for segments of a given flag
query_dqsegdb(flag, *args, **kwargs)	Query the advanced LIGO DQSegDB for the given flag
query_segdb(flag, *args, **kwargs)	Query the initial LIGO segment database 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()

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)

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

x : float

number of seconds by which to contract each Segment.

copy()

Build an exact copy of this flag.

Returns

flag2 : DataQualityFlag

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

classmethod fetch_open_data(flag, start, end, **kwargs)

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

flag : DataQualityFlag

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)

Define a DataQualityFlag from a VetoDef

Parameters

veto : VetoDef

veto definition to convert from

pad(*args, **kwargs)

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

start : float

padding to apply to the start of the each segment

end : float

padding to apply to the end of each segment

inplace : bool, optional, default: False

modify this object in-place, default is False, i.e. return a copy of the original object with padded segments

Returns

paddedflag : DataQualityFlag

a view of the modified flag

plot(figsize=(12, 4), xscale='auto-gps', **kwargs)

Plot this flag on a segments projection.

Parameters

**kwargs

all keyword arguments are passed to the Plot constructor.

Returns

figure : Figure

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)

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

source : str

source of segments for this flag. This must be either a URL for a segment database or a path to a file on disk.

segments : SegmentList, optional

a list of segments during which to query, if not given, existing known segments for this flag will be used.

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

self : DataQualityFlag

a reference to this flag

protract(x)

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

x : float

number of seconds by which to protact each Segment.

classmethod query(flag, *args, **kwargs)

Query for segments of a given flag

This method intelligently selects the query_segdb or the query_dqsegdb methods based on the url kwarg given.

Parameters

flag : str

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

url : str, optional

URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns

flag : DataQualityFlag

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

See also

DataQualityFlag.query_segdb

DataQualityFlag.query_dqsegdb

for details on the actual query engine, and documentation of other keyword arguments appropriate for each query

classmethod query_dqsegdb(flag, *args, **kwargs)

Query the advanced LIGO DQSegDB for the given flag

Parameters

flag : str

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

url : str, optional

URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns

flag : DataQualityFlag

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

classmethod query_segdb(flag, *args, **kwargs)

Query the initial LIGO segment database for the given flag

Parameters

flag : str

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

url : str, optional

URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns

flag : DataQualityFlag

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

classmethod read(source, *args, **kwargs)

Read segments from file into a DataQualityFlag.

Parameters

filename : str

path of file to read

name : str, optional

name of flag to read from file, otherwise read all segments.

format : str, optional

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

coltype : type, optional, default: float

datatype to force for segment times, only valid for format='segwizard'.

strict : bool, optional, default: True

require segment start and stop times match printed duration, only valid for format='segwizard'.

coalesce : bool, optional

if True coalesce the all segment lists before returning, otherwise return exactly as contained in file(s).

nproc : int, optional, default: 1

number of CPUs to use for parallel reading of multiple files

verbose : bool, optional, default: False

print a progress bar showing read status

Returns

dqflag : DataQualityFlag

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)

Round this flag to integer segments.

Parameters

contract : bool, optional

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

Returns

roundedflag : DataQualityFlag

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

write(target, *args, **kwargs)

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