Segments

Stability: Stable

Classes and utilities for managing time segments (data quality flags, active/inactive intervals).

`DataQualityFlag`([name, active, known, ...])	A representation of a named set of segments.
`DataQualityDict`	An dict of (key, DataQualityFlag) pairs.
`Segment`([iterable])	A tuple defining a semi-open interval `[start, end)`.
`SegmentList`([iterable])	A list of Segments <Segment>.

class gwexpy.segments.DataQualityDict[source]

Bases: dict

An dict of (key, DataQualityFlag) pairs.

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

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

classmethod query_dqsegdb(flags: list[str], *args: SupportsToGps | Segment | SegmentList, host: str | None = 'https://segments.ligo.org', on_error: str = 'raise', parallel: int = 10, **kwargs) → Self[source]

Query the advanced LIGO DQSegDB for a list of flags.

Parameters:

flags (iterable) – A list of flag names 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().
on_error (str, optional) –
how to handle an error querying for one flag, one of
- ’raise’ (default): raise the Exception
- ’warn’: print a warning
- ’ignore’: move onto the next flag as if nothing happened
parallel (int, optional) – Maximum number of threads to use for parallel connections to the DQSegDB host.
kwargs – All other keyword arguments are passed to dqsegdb2.query.query_segments().

Returns:

flagdict – An ordered DataQualityDict of (name, DataQualityFlag) pairs.

Return type:

DataQualityDict

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(flags: list[str], *args: SupportsToGps | Segment | SegmentList, host: str | None = 'https://segments.ligo.org', on_error: str = 'raise', parallel: int = 10, **kwargs) → Self

Query the advanced LIGO DQSegDB for a list of flags.

Parameters:

flags (iterable) – A list of flag names 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().
on_error (str, optional) –
how to handle an error querying for one flag, one of
- ’raise’ (default): raise the Exception
- ’warn’: print a warning
- ’ignore’: move onto the next flag as if nothing happened
parallel (int, optional) – Maximum number of threads to use for parallel connections to the DQSegDB host.
kwargs – All other keyword arguments are passed to dqsegdb2.query.query_segments().

Returns:

flagdict – An ordered DataQualityDict of (name, DataQualityFlag) pairs.

Return type:

DataQualityDict

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 from_veto_definer_file(source: str, start: SupportsToGps | None = None, end: SupportsToGps | None = None, ifo: str | None = None, **read_kw) → Self[source]

Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.

Parameters:

source (str, Path, file) – Path or URL of veto definer file to read, or open file.
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
ifo (str, optional) – Interferometer prefix whose flags you want to read. Default is None (read all flags).
read_kw – Other keyword arguments are passed to ~astropy.table.Table.read when reading the veto definer file.

Returns:

flags – A DataQualityDict of flags parsed from the veto_def_table of the input file.

Return type:

DataQualityDict

Notes

This method does not automatically ~DataQualityDict.populate the active segment list of any flags, a separate call should be made for that as follows

>>> flags = DataQualityDict.from_veto_definer_file('/path/to/file.xml')
>>> flags.populate()

classmethod from_ligolw_tables(segmentdeftable: igwn_ligolw.lsctables.SegmentDefTable, segmentsumtable: igwn_ligolw.lsctables.SegmentSumTable, segmenttable: igwn_ligolw.lsctables.SegmentTable, names: list[str] | None = None, gpstype: type[SupportsFloat] | Callable[[float], SupportsFloat] = <class 'lal.LIGOTimeGPS'>, on_missing: str = 'error') → Self[source]

Build a DataQualityDict from a set of LIGO_LW segment tables.

Parameters:

segmentdeftable (SegmentDefTable) – The segment_definer table to read.
segmentsumtable (SegmentSumTable) – The segment_summary table to read.
segmenttable (SegmentTable) – The segment table to read.
names (list of str, optional) – A list of flag names to read. Default is to read all names.
gpstype (type, callable, optional) – Class to use for GPS times in returned objects, can be a function to convert GPS time to something else. Default is ~gwpy.time.LIGOTimeGPS.
on_missing (str, optional) –
Action to take when a one or more names are not found in the segment_definer table, one of
- 'ignore' : do nothing
- 'warn' : print a warning
- error' : raise a ValueError

Returns:

dqdict – A dict of DataQualityFlag objects populated from the LIGO_LW tables.

Return type:

DataQualityDict

to_ligolw_tables(**attrs) → tuple[igwn_ligolw.lsctables.SegmentDefTable, igwn_ligolw.lsctables.SegmentSumTable, igwn_ligolw.lsctables.SegmentTable][source]

Convert this DataQualityDict into a trio of LIGO_LW segment tables.

Parameters:

attrs – Other attributes to add to all rows in all tables (e.g. 'process_id').

Returns:

segmentdeftable (SegmentDefTable) – The segment_definer table.
segmentsumtable (SegmentSumTable) – The segment_summary table.
segmenttable (SegmentTable) – The segment table.

coalesce() → Self[source]

Coalesce all segments lists in this DataQualityDict.

This method modifies this object in-place.

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

populate(source: str | None = 'https://segments.ligo.org', segments: SegmentList | None = None, *, pad: bool = True, on_error: str = 'raise', **kwargs) → Self[source]

Query the segment database for each 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.

Entries in this dict 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 known segments during which to query, if not given, existing known segments for flags will be used.
pad (bool, optional, default: True) – Apply the ~DataQualityFlag.padding associated with each flag, default: True.
on_error (str) –
How to handle an error querying for one flag, one of
- ’raise’ (default): raise the Exception
- ’warn’: print a warning
- ’ignore’: move onto the next flag as if nothing happened
kwargs – Any other keyword arguments to be passed to DataQualityFlag.query() or DataQualityFlag.read().

Returns:

self – A reference to the modified DataQualityDict

Return type:

DataQualityDict

copy(*, deep: bool = False) → Self[source]

Build a copy of this dictionary.

Parameters:: deep (bool, optional, default: False) – perform a deep copy of the original dictionary with a fresh memory address
Returns:: flag2 – a copy of the original dictionary
Return type:: DataQualityFlag

union() → DataQualityFlag[source]

Return the union of all flags in this dict.

Returns:: union – a new DataQualityFlag who’s active and known segments are the union of those of the values of this dict
Return type:: DataQualityFlag

intersection() → DataQualityFlag[source]

Return the intersection of all flags in this dict.

Returns:: intersection – a new DataQualityFlag who’s active and known segments are the intersection of those of the values of this dict
Return type:: DataQualityFlag

plot(label: str = 'key', **kwargs) → Plot[source]

Plot this dict on a segments projection.

Parameters:

label (str, optional) –
Labelling system to use, or fixed label for all flags, special values include
- 'key': use the key of the DataQualityDict,
- 'name': use the name of the flag
If anything else, that fixed label will be used for all lines.
kwargs – All keyword arguments are passed to the Plot constructor.

Returns:

figure – the newly created figure, with populated Axes.

Return type:

~matplotlib.figure.Figure

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.

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?

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