gwexpy.segments.DataQualityFlag

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?

__init__(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) → None[source]: Define a new DataQualityFlag.

Methods

`__init__`([name, active, known, label, ...])	Define a new DataQualityFlag.
`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

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

property name: str | None

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

property ifo: str | None

The interferometer associated with this flag.

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

property tag: str | None

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

property version: int | None

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.

property label: str | None

A human-readable label for this flag.

For example: 'Science-mode'.

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

property known: SegmentList: The segments during which this flag was known.

property category: int | None: Veto category for this flag.

property description: str | None: Description of why/how this flag was generated.

property isgood: bool: Whether active segments mean the instrument was in a good state.

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

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

property extent: Segment: The GPS [start, stop) enclosing segment of this DataQualityFlag.

property livetime: float: Amount of time this flag was active.

property regular: bool: True if the active segments are a proper subset of the known.

read = <gwpy.segments.connect.DataQualityFlagRead object>

write = <gwpy.segments.connect.DataQualityFlagWrite object>

classmethod query_dqsegdb(flag: str, *args: SupportsToGps | Segment | SegmentList, host: str | None = 'https://segments.ligo.org', **kwargs) → Self[source]

Query a DQSegDB server for a 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
host (str, 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:

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

Return type:

DataQualityFlag

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(flag: str, *args: SupportsToGps | Segment | SegmentList, host: str | None = 'https://segments.ligo.org', **kwargs) → Self

Query a DQSegDB server for a 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
host (str, 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:

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

Return type:

DataQualityFlag

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 fetch_open_data(flag: str, start: SupportsToGps, end: SupportsToGps, **kwargs) → Self[source]

Fetch Open Data timeline segments into a flag.

flagstr: The name of the flag to query
start~gwpy.time.LIGOTimeGPS, float, str: GPS start time of required data, any input parseable by ~gwpy.time.to_gps is fine
end~gwpy.time.LIGOTimeGPS, float, str: GPS end time of required data, any input parseable by ~gwpy.time.to_gps is fine
timeoutint, optional: Timeout for download (seconds).
hoststr, optional: URL of GWOSC host, default: 'https://gwosc.org'.

Returns:: flag – a new flag with active segments filled from Open Data
Return type:: DataQualityFlag

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

Define a DataQualityFlag from a VetoDef.

Parameters:: veto (~igwn_ligolw.lsctables.VetoDef, ~astropy.table.Row.) – Veto definition to convert from.

populate(source: str | None = 'https://segments.ligo.org', segments: SegmentList | None = None, *, pad: bool = True, **kwargs) → Self[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 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:

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 ~DataQualityFlag.padding associated with this flag, default: True.
**kwargs – any other keyword arguments to be passed to DataQualityFlag.query() or DataQualityFlag.read().

Returns:

self – a reference to this flag

Return type:

DataQualityFlag

contract(x: float) → SegmentList[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.

protract(x: float) → SegmentList[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.

pad(*args: float, inplace: bool = False) → Self[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 ~DataQualityFlag.known and ~DataQualityFlag.active lists, but will not coalesce() the result.

Parameters:

args (float, optional) – Two floats giving the start and end padding to apply. If not given, self.padding will be used.
inplace (bool, optional) – Modify this object in-place. Default is False, i.e. return a copy of the original object with padded segments.

Returns:

paddedflag – A view of the modified flag.

Return type:

DataQualityFlag

round(*, contract: bool = False) → Self[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 – A copy of the original flag with the active and known segments padded out to integer boundaries..
Return type:: DataQualityFlag

coalesce() → Self[source]

Coalesce the segments for this flag.

This method does two things:

coalesces <SegmentList.coalesce> the ~DataQualityFlag.known and ~DataQualityFlag.active segment lists
forces the active segments to be a proper subset of the known segments

Note

This operation is performed in-place.

Returns:: A view of this flag, not a copy.
Return type:: self

copy() → Self[source]

Build an exact copy of this flag.

Returns:: flag – A deepcopy of the original flag.
Return type:: DataQualityFlag

plot(figsize: tuple[float, float] = (12, 4), xscale: str = 'auto-gps', **kwargs) → Plot[source]

Plot this flag on a segments projection.

Parameters:

figsize (tuple 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:

figure – The newly created figure, with populated Axes.

Return type:

~matplotlib.figure.Figure