DataQualityFlag¶

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

Bases: object

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?

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(**kwargs)	Plot this flag.
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()	Round this flag to integer segments.
write(target, *args, **kwargs)	Write this DataQualityFlag to file

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:	x : float number of seconds by which to contract each Segment.

copy()[source]¶

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)[source]¶

Fetch Open Data timeline segments into a flag.

flag : str

the name of the flag to query

start : int, str

the GPS start time (or parseable date string) to query

end : int, str

the GPS end time (or parseable date string) to query

verbose : bool, optional

show verbose download progress, default: False

timeout : int, optional

timeout for download (seconds)

host : str, optional

URL of LOSC host, default: 'losc.ligo.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)[source]¶

Define a DataQualityFlag from a VetoDef

Parameters:	veto : VetoDef 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:	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(**kwargs)[source]¶

Plot this flag.

Parameters:	**kwargs all keyword arguments are passed to the SegmentPlot constructor.
Returns:	plot : SegmentPlot a new Plot with this flag displayed on a set of SegmentAxes.

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:

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 valid 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)[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:	x : float number of seconds by which to protact each Segment.

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

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)[source]¶

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)[source]¶

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)[source]¶

Read segments from file into a DataQualityFlag.

Parameters:

filename : str path of file to read flag : str, optional, default: read all segments name of flag to read from file. 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'. 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.

Notes

The available built-in formats are:

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

round()[source]¶

Round this flag to integer segments.

Returns:	roundedflag : DataQualityFlag A copy of the original flag with the active and known segments padded out to the enclosing 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
segwizard	Yes	Yes	Yes

active¶

The set of segments during which this flag was active.

category¶

Veto category for this flag.

Type:	int

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:	x : float number of seconds by which to contract each Segment.

copy()[source]

Build an exact copy of this flag.

Returns:	flag2 : DataQualityFlag a copy of the original flag, but with a fresh memory address.

description¶

Description of why/how this flag was generated.

Type:	str

extent¶

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

Type:	Segment

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

Fetch Open Data timeline segments into a flag.

flag : str

the name of the flag to query

start : int, str

the GPS start time (or parseable date string) to query

end : int, str

the GPS end time (or parseable date string) to query

verbose : bool, optional

show verbose download progress, default: False

timeout : int, optional

timeout for download (seconds)

host : str, optional

URL of LOSC host, default: 'losc.ligo.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)[source]

Define a DataQualityFlag from a VetoDef

Parameters:	veto : VetoDef veto definition to convert from

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

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:	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

padding¶

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

plot(**kwargs)[source]

Plot this flag.

Parameters:	**kwargs all keyword arguments are passed to the SegmentPlot constructor.
Returns:	plot : SegmentPlot a new Plot with this flag displayed on a set of SegmentAxes.

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:

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 valid 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)[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:	x : float number of seconds by which to protact each Segment.

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

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)[source]

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)[source]

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)[source]

Read segments from file into a DataQualityFlag.

Parameters:

filename : str path of file to read flag : str, optional, default: read all segments name of flag to read from file. 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'. 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.

Notes

The available built-in formats are:

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

regular¶

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

Type:	bool

round()[source]

Round this flag to integer segments.

Returns:	roundedflag : DataQualityFlag A copy of the original flag with the active and known segments padded out to the enclosing integer boundaries.

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.

valid¶

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

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

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
segwizard	Yes	Yes	Yes