DataQualityFlag

class gwpy.segments.DataQualityFlag(name: str | None = None, active: SegmentListLike | None = None, known: SegmentListLike | None = None, *, label: str | None = None, category: int | None = None, description: str | None = None, isgood: bool = True, padding: tuple[float | None, float | None] | None = None)

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 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 segments during which this flag was known.
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.
read	Read segments from file into a DataQualityFlag.
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.
write	Write this DataQualityFlag to file.

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[, inplace])	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[, host])	Query a DQSegDB server for a flag.
query_dqsegdb(flag, *args[, host])	Query a DQSegDB server for a flag.
round(*[, contract])	Round this flag to integer segments.

Attributes Documentation

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 GPS [start, stop) enclosing segment of this DataQualityFlag.

ifo

The interferometer associated with this flag.

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

isgood

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

known

The segments during which this flag was known.

label

A human-readable label for this flag.

For example: 'Science-mode'.

livetime

Amount of time this flag was active.

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.

read

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

parallelint, optional, default: 1

Number of threads 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.

regular

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

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

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.

write

Write this DataQualityFlag to file.

Methods Documentation

coalesce() → Self

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 operation is performed in-place.

Returns:

self

A view of this flag, not a copy.

contract(x: float) → SegmentList

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() → Self

Build an exact copy of this flag.

Returns:

flagDataQualityFlag

A deepcopy of the original flag.

classmethod fetch_open_data(flag: str, start: GpsLike, end: GpsLike, **kwargs) → Self

Fetch Open Data timeline segments into a flag.

flagstr

The name of the flag to query

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

timeoutint, optional

Timeout for download (seconds).

hoststr, optional

URL of GWOSC host, default: 'https://gwosc.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",
...     "Sep 14 2015",
...     "Sep 15 2015",
... ))
<DataQualityFlag('H1:DATA',
                 known=[[1126224017 ... 1126310417)]
                 active=[[1126251604 ... 1126252133)
                         [1126252291 ... 1126274322)
                         [1126276234 ... 1126281754)
                       ...
                         [1126308670 ... 1126309577)
                         [1126309637 ... 1126309817)
                         [1126309877 ... 1126310417)]
                 description=None)>

classmethod from_veto_def(veto: igwn_ligolw.lsctables.VetoDef | astropy.table.Row) → Self

Define a DataQualityFlag from a VetoDef.

Parameters:

vetoVetoDef, Row.

Veto definition to convert from.

pad(*args: float, inplace: bool = False) → Self

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:

argsfloat, optional

Two floats giving the start and end padding to apply. If not given, self.padding will be used.

inplacebool, optional

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: tuple[float, float] = (12, 4), xscale: str = 'auto-gps', **kwargs) → Plot

Plot this flag on a segments projection.

Parameters:

figsizetuple of float

The size (width, height) of the figure to create.

xscale: `str`

The scaling to use for the X-axis (time axis). Default is "auto-gps" to dynamically choose the right scaling based on how much time is covered by the visible span.

kwargs

Other 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: str | None = 'http://segments.ldas.cit', segments: SegmentList | None = None, *, pad: bool = True, **kwargs) → Self

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 segments during which this flag was known.

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: float) → SegmentList

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: str, *args: GpsLike | Segment | SegmentList, host: str | None = 'http://segments.ldas.cit', **kwargs) → Self

Query a DQSegDB server for a 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

hoststr, optional

Name or URL of the DQSegDB instance to talk to. Defaults to dqsegdb2.utils.get_default_host().

kwargs

All other keyword arguments are passed to dqsegdb2.query.query_segments().

Returns:

flagDataQualityFlag

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

Examples

The GPS interval(s) of interest can be passed as two arguments specifing the start and end of a single interval:

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], start, end)

Or, as a single Segment:

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], interval)

Or, as a SegmentList specifying multiple intervals.

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], intervals)

classmethod query_dqsegdb(flag: str, *args: GpsLike | Segment | SegmentList, host: str | None = 'http://segments.ldas.cit', **kwargs) → Self

Query a DQSegDB server for a 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

hoststr, optional

Name or URL of the DQSegDB instance to talk to. Defaults to dqsegdb2.utils.get_default_host().

kwargs

All other keyword arguments are passed to dqsegdb2.query.query_segments().

Returns:

flagDataQualityFlag

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

Examples

The GPS interval(s) of interest can be passed as two arguments specifing the start and end of a single interval:

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], start, end)

Or, as a single Segment:

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], interval)

Or, as a SegmentList specifying multiple intervals.

>>> DataQualityDict.query_dqsegdb(["X1:OBSERVING:1", "Y1:OBSERVING:1"], intervals)

round(*, contract: bool = False) → Self

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