DataQualityFlag¶

class gwpy.segments.DataQualityFlag(name=None, active=None, known=None, label=None, category=None, description=None, isgood=True, padding=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?

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`(self)	Coalesce the segments for this flag.
`contract`(self, x)	Contract each of the `active` `Segments` by `x` seconds.
`copy`(self)	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`(self, \args, \\*kwargs)	Apply a padding to each segment in this `DataQualityFlag`
`plot`(self[, figsize, xscale])	Plot this flag on a segments projection.
`populate`(self[, source, segments, pad])	Query the segment database for this flag’s active segments.
`protract`(self, 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`(self[, contract])	Round this flag to integer segments.
`write`(self, 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(self)[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(self, 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(self)[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.

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 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(self, *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(self, 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: 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(self, 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 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(self, 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

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(self, contract=False)[source]¶

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(self, 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

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

property category

Veto category for this flag.

Type: int

coalesce(self)[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(self, 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(self)[source]

Build an exact copy of this flag.

Returns: flag2 : DataQualityFlag

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

property description

Description of why/how this flag was generated.

Type: str

property 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.

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

property ifo

The interferometer associated with this flag.

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

Type: str

property isgood

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

Type: bool

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

property label

A human-readable label for this flag.

For example: 'Science-mode'.

Type: str

property livetime

Amount of time this flag was active.

Type: float

property 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(self, *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.

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

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

plot(self, 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: 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(self, 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 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(self, 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

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

property regular

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

Type: bool

round(self, contract=False)[source]

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.

property 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

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

property 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(self, 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