開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

Segments#

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

ベースクラス: dict

An dict of (key, DataQualityFlag) pairs.

coalesce() → Self

Coalesce all segments lists in this DataQualityDict.

This method modifies this object in-place.

戻り値:: A view of this flag, not a copy.
戻り値の型:: self

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

Build a copy of this dictionary.

パラメータ:: deep (bool, optional, default: False) -- perform a deep copy of the original dictionary with a fresh memory address
戻り値:: flag2 -- a copy of the original dictionary
戻り値の型:: DataQualityFlag

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

Build a DataQualityDict from a set of LIGO_LW segment tables.

パラメータ:

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

戻り値:

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

戻り値の型:

DataQualityDict

classmethod from_veto_definer_file(source: str, start: SupportsToGps | None = None, end: SupportsToGps | None = None, ifo: str | None = None, **read_kw) → Self

Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.

パラメータ:

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.

戻り値:

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

戻り値の型:

DataQualityDict

メモ

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

intersection() → DataQualityFlag

Return the intersection of all flags in this dict.

戻り値:: intersection -- a new DataQualityFlag who's active and known segments are the intersection of those of the values of this dict
戻り値の型:: DataQualityFlag

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

Plot this dict on a segments projection.

パラメータ:

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.

戻り値:

figure -- the newly created figure, with populated Axes.

戻り値の型:

~matplotlib.figure.Figure

参考

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

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.

パラメータ:

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

戻り値:

self -- A reference to the modified DataQualityDict

戻り値の型:

DataQualityDict

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.

パラメータ:

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

戻り値:

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

戻り値の型:

DataQualityDict

サンプル

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

パラメータ:

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

戻り値:

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

戻り値の型:

DataQualityDict

サンプル

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)

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

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

Convert this DataQualityDict into a trio of LIGO_LW segment tables.

パラメータ:

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

戻り値:

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

union() → DataQualityFlag

Return the union of all flags in this dict.

戻り値:: union -- a new DataQualityFlag who's active and known segments are the union of those of the values of this dict
戻り値の型:: DataQualityFlag

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

ベースクラス: object

A representation of a named set of segments.

パラメータ:

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 active: SegmentList: The set of segments during which this flag was active.

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

coalesce() → Self

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

注釈

This operation is performed in-place.

戻り値:: A view of this flag, not a copy.
戻り値の型:: self

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.

パラメータ:: x (float) -- Number of seconds by which to contract each Segment.

copy() → Self

Build an exact copy of this flag.

戻り値:: flag -- A deepcopy of the original flag.
戻り値の型:: DataQualityFlag

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

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

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

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

戻り値:: flag -- a new flag with active segments filled from Open Data
戻り値の型:: DataQualityFlag

サンプル

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

パラメータ:: veto (~igwn_ligolw.lsctables.VetoDef, ~astropy.table.Row.) -- Veto definition to convert from.

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 isgood: bool: Whether active segments mean the instrument was in a good state.

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

property label: str | None

A human-readable label for this flag.

For example: 'Science-mode'.

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

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

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 ~DataQualityFlag.known and ~DataQualityFlag.active lists, but will not coalesce() the result.

パラメータ:

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.

戻り値:

paddedflag -- A view of the modified flag.

戻り値の型:

DataQualityFlag

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

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

Plot this flag on a segments projection.

パラメータ:

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.

戻り値:

figure -- The newly created figure, with populated Axes.

戻り値の型:

~matplotlib.figure.Figure

参考

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 = 'https://segments.ligo.org', 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.

パラメータ:

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

戻り値:

self -- a reference to this flag

戻り値の型:

DataQualityFlag

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.

パラメータ:: x (float) -- Number of seconds by which to protact each Segment.

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

Query a DQSegDB server for a flag.

パラメータ:

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

戻り値:

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

戻り値の型:

DataQualityFlag

サンプル

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

Query a DQSegDB server for a flag.

パラメータ:

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

戻り値:

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

戻り値の型:

DataQualityFlag

サンプル

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)

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

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

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

Round this flag to integer segments.

パラメータ:: contract (bool, optional) -- If False (default) expand each segment to the containing integer boundaries, otherwise contract each segment to the contained boundaries.
戻り値:: roundedflag -- A copy of the original flag with the active and known segments padded out to integer boundaries..
戻り値の型:: DataQualityFlag

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 texname: str | None: Name of this flag in LaTeX printable format.

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.

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

class gwexpy.segments.Segment(iterable=(), /)

ベースクラス: segment, Generic[T]

A tuple defining a semi-open interval [start, end).

Each Segment represents the range of values in a given interval, with general arithmetic supported for combining/comparing overlapping segments.

パラメータ:

start (float) -- The start value of this Segment.
end (float) -- The end value of this Segment.

サンプル

>>> Segment(0, 10) & Segment(5, 15)
Segment(5, 10)
>>> Segment(0, 10) | Segment(5, 15)
Segment(0, 15)
>>> Segment(0, 10) - Segment(5, 15)
Segment(0, 5)
>>> Segment(0, 10) < Segment(5, 15)
True
>>> Segment(1, 2) in Segment(0, 10)
True
>>> Segment(1, 11) in Segment(0, 10)
False
>>> Segment(0, 1)
Segment(0, 1)
>>> Segment(1, 0)
Segment(0, 1)
>>> bool(Segment(0, 1))
True

property end: T: The end of this segment.

property start: T: The beginning of this segment.

class gwexpy.segments.SegmentList(iterable=(), /)

ベースクラス: segmentlist

A list of Segments <Segment>.

The SegmentList provides additional methods that assist in the manipulation of lists of Segments <Segment>. In particular, arithmetic operations such as union and intersection are provided. Unlike the Segment, the SegmentList is closed under all supported arithmetic operations.

All standard Python sequence-like operations are supported, like slicing, iteration and so on, but the arithmetic and other methods in this class generally expect the SegmentList to be in what is refered to as a "coalesced" state - consisting solely of disjoint Segments <Segment> listed in ascending order. Using the standard Python sequence-like operations, a SegmentList can be easily constructed that is not in this state; for example by simply appending a Segment to the end of the list that overlaps some other Segment already in the list. The class provides a coalesce() method that can be called to put it in the coalesced state. Following application of the coalesce method, all arithmetic operations will function reliably. All arithmetic methods themselves return coalesced results, so there is never a need to call the coalesce method when manipulating a SegmentList exclusively via the arithmetic operators.

サンプル

>>> x = SegmentList([Segment(-10, 10)])
>>> x |= SegmentList([Segment(20, 30)])
>>> x -= SegmentList([Segment(-5, 5)])
>>> print(x)
[Segment(-10, -5), Segment(5, 10), Segment(20, 30)]
>>> print(~x)
[Segment(-infinity, -10), Segment(-5, 5), Segment(10, 20),
 Segment(30, infinity)]

coalesce() → Self: Sort the elements of the list into ascending order, and merge continuous segments into single segments. Segmentlist is modified in place. This operation is O(n log n).

extent(): Return the segment whose end-points denote the maximum and minimum extent of the segmentlist. Does not require the segmentlist to be coalesced.

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

to_table() → Table

Convert this SegmentList to a ~astropy.table.Table.

The resulting Table has four columns: index, start, end, and duration, corresponding to the zero-counted list index, GPS start and end times, and total duration in seconds, respectively.

This method exists mainly to provide a way to write SegmentList objects in comma-separated value (CSV) format, via the write() method.

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

class gwexpy.segments.SegmentListDict(*args)

ベースクラス: segmentlistdict

A dict of SegmentLists <SegmentList>.

This class implements a standard mapping interface, with additional features added to assist with the manipulation of a collection of SegmentList objects. In particular, methods for taking unions and intersections of the lists in the dictionary are available, as well as the ability to record and apply numeric offsets to the boundaries of the Segments <Segment> in each list.

The numeric offsets are stored in the "offsets" attribute, which itself is a dictionary, associating a number with each key in the main dictionary. Assigning to one of the entries of the offsets attribute has the effect of shifting the corresponding SegmentList from its original position (not its current position) by the given amount.

サンプル

>>> x = SegmentListDict()
>>> x["H1"] = SegmentList([Segment(0, 10)])
>>> print(x)
{'H1': [Segment(0, 10)]}
>>> x.offsets["H1"] = 6
>>> print(x)
{'H1': [Segment(6.0, 16.0)]}
>>> x.offsets.clear()
>>> print(x)
{'H1': [Segment(0.0, 10.0)]}
>>> x["H2"] = SegmentList([Segment(5, 15)])
>>> x.intersection(["H1", "H2"])
[Segment(5, 10.0)]
>>> x.offsets["H1"] = 6
>>> x.intersection(["H1", "H2"])
[Segment(6.0, 15)]
>>> c = x.extract_common(["H1", "H2"])
>>> c.offsets.clear()
>>> c
{'H2': [Segment(6.0, 15)], 'H1': [Segment(0.0, 9.0)]}