DataQualityDict#

class gwpy.segments.DataQualityDict[source]#

Bases: dict

An dict of (key, DataQualityFlag) pairs.

Attributes Summary

`read`	Read segments from file into a `DataQualityDict`.
`write`	Write this `DataQualityDict` to file.

Methods Summary

`coalesce`()	Coalesce all segments lists in this `DataQualityDict`.
`copy`(*[, deep])	Build a copy of this dictionary.
`from_ligolw_tables`(segmentdeftable, ...)	Build a `DataQualityDict` from a set of LIGO_LW segment tables.
`from_veto_definer_file`(source[, start, end, ifo])	Read a `DataQualityDict` from a LIGO_LW XML VetoDefinerTable.
`intersection`()	Return the intersection of all flags in this dict.
`plot`([label])	Plot this dict on a segments projection.
`populate`([source, segments, pad, on_error])	Query the segment database for each flag's active segments.
`query`(flags, *args[, host, on_error, parallel])	Query the advanced LIGO DQSegDB for a list of flags.
`query_dqsegdb`(flags, *args[, host, ...])	Query the advanced LIGO DQSegDB for a list of flags.
`to_ligolw_tables`(**attrs)	Convert this `DataQualityDict` into a trio of LIGO_LW segment tables.
`union`()	Return the union of all flags in this dict.

Attributes Documentation

read#

Read segments from file into a DataQualityDict.

Parameters:

sourcestr: Path of file to read
formatstr, optional: Source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats.
nameslist, optional, default: read all names found: List of names to read, by default all names are read separately.
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:

flagdictDataQualityDict: A new DataQualityDict of DataQualityFlag entries with active and known segments seeded from the XML tables in the given file.

write#: Write this DataQualityDict to file.

Methods Documentation

coalesce() → Self[source]#

Coalesce all segments lists in this DataQualityDict.

This method modifies this object in-place.

Returns:

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

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

Build a copy of this dictionary.

Parameters:

deepbool, optional, default: False: perform a deep copy of the original dictionary with a fresh memory address

Returns:

flag2DataQualityFlag: a copy of the original dictionary

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:

segmentdeftableSegmentDefTable

The segment_definer table to read.

segmentsumtableSegmentSumTable

The segment_summary table to read.

segmenttableSegmentTable

The segment table to read.

nameslist of str, optional

A list of flag names to read. Default is to read all names.

gpstypetype, callable, optional

Class to use for GPS times in returned objects, can be a function to convert GPS time to something else. Default is LIGOTimeGPS.

on_missingstr, 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:

dqdictDataQualityDict: A dict of DataQualityFlag objects populated from the LIGO_LW tables.

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:

sourcestr, Path, file: Path or URL of veto definer file to read, or open file.
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
ifostr, optional: Interferometer prefix whose flags you want to read. Default is None (read all flags).
read_kw: Other keyword arguments are passed to read when reading the veto definer file.

Returns:

flagsDataQualityDict: A DataQualityDict of flags parsed from the veto_def_table of the input file.

Notes

This method does not automatically 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[source]#

Return the intersection of all flags in this dict.

Returns:

intersectionDataQualityFlag: a new DataQualityFlag who’s active and known segments are the intersection of those of the values of this dict

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

Plot this dict on a segments projection.

Parameters:

labelstr, 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:

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 = '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:

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 known segments during which to query, if not given, existing known segments for flags will be used.

padbool, optional, default: True

Apply the padding associated with each flag, default: True.

on_errorstr

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:

selfDataQualityDict: A reference to the modified 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[source]#

Query the advanced LIGO DQSegDB for a list of flags.

Parameters:

flagsiterable

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.

hoststr, optional

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

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

parallelint, 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:

flagdictDataQualityDict: An ordered DataQualityDict of (name, DataQualityFlag) pairs.

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(

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:

flagsiterable

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.

hoststr, optional

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

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

parallelint, 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:

flagdictDataQualityDict: An ordered DataQualityDict of (name, DataQualityFlag) pairs.

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)

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:

segmentdeftableSegmentDefTable: The segment_definer table.
segmentsumtableSegmentSumTable: The segment_summary table.
segmenttableSegmentTable: The segment table.

union() → DataQualityFlag[source]#

Return the union of all flags in this dict.

Returns:

unionDataQualityFlag: a new DataQualityFlag who’s active and known segments are the union of those of the values of this dict