DataQualityDict¶

class gwpy.segments.DataQualityDict(*args, **kwds)[source]¶

Bases: collections.OrderedDict

An OrderedDict of (key, DataQualityFlag) pairs.

Since the DataQualityDict is an OrderedDict, all iterations over its elements retain the order in which they were inserted.

Methods Summary

clear(() -> None.  Remove all items from od.)
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(fp[, start, end, …])	Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.
fromkeys((S[, …)	If not specified, the value defaults to None.
get((k[,d]) -> D[k] if k in D, …)
has_key((k) -> True if D has a key k, else False)
intersection()	Return the intersection of all flags in this dict
items(() -> list of (key, value) pairs in od)
iteritems()	od.iteritems -> an iterator over the (key, value) pairs in od
iterkeys(() -> an iterator over the keys in od)
itervalues()	od.itervalues -> an iterator over the values in od
keys(() -> list of keys in od)
plot([label])	Plot the data for this dict.
pop((k[,d]) -> v, …)	value. If key is not found, d is returned if given, otherwise KeyError
popitem(() -> (k, v), …)	Pairs are returned in LIFO order if last is true or FIFO order if false.
populate([source, segments, pad, on_error])	Query the segment database for each flag’s active segments.
query(flags, *args, **kwargs)	Query for segments of a set of flags.
query_dqsegdb(flags, *args, **kwargs)	Query the advanced LIGO DQSegDB for a list of flags.
query_segdb(flags, *args, **kwargs)	Query the inital LIGO segment database for a list of flags.
read(source[, flags, format])	Read segments from file into a DataQualityDict
setdefault((k[,d]) -> od.get(k,d), …)
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
update(([E, …)	If E present and has a .keys() method, does: for k in E: D[k] = E[k]
values(() -> list of values in od)
viewitems(…)
viewkeys(…)
viewvalues(…)
write(target, *args, **kwargs)	Write this DataQualityDict to file

Methods Documentation

clear() → None. Remove all items from od.¶

copy(deep=False)[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 : DataQualityFlag a copy of the original dictionary

classmethod from_ligolw_tables(segmentdeftable, segmentsumtable, segmenttable, names=None, gpstype=<type 'lal.LIGOTimeGPS'>)[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, defaults to returning all 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 LIGOTimeGPS

Returns:

dqdict : DataQualityDict a dict of DataQualityFlag objects populated from the LIGO_LW tables

classmethod from_veto_definer_file(fp, start=None, end=None, ifo=None, format='ligolw')[source]¶

Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.

Parameters:	fp : str path of veto definer file to read start : LIGOTimeGPS, int, optional GPS start time at which to restrict returned flags end : LIGOTimeGPS, int, optional GPS end time at which to restrict returned flags ifo : str, optional interferometer prefix whose flags you want to read format : str, optional format of file to read, currently only ‘ligolw’ is supported
Returns:	flags : DataQualityDict 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()

fromkeys(S[, v]) → New ordered dictionary with keys from S.¶

If not specified, the value defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

has_key(k) → True if D has a key k, else False¶

intersection()[source]¶

Return the intersection of all flags in this dict

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

items() → list of (key, value) pairs in od¶

iteritems()¶

od.iteritems -> an iterator over the (key, value) pairs in od

iterkeys() → an iterator over the keys in od¶

itervalues()¶

od.itervalues -> an iterator over the values in od

keys() → list of keys in od¶

plot(label='key', **kwargs)[source]¶

Plot the data for this dict.

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 other keyword arguments are passed to the plotter as appropriate

See also

gwpy.plotter.SegmentPlot, gwpy.plotter.SegmentAxes, gwpy.plotter.SegmentAxes.plot_dqdict

pop(k[, d]) → v, remove specified key and return the corresponding¶

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), return and remove a (key, value) pair.¶

Pairs are returned in LIFO order if last is true or FIFO order if false.

populate(source='http://segments.ldas.cit', segments=None, pad=True, on_error='raise', **kwargs)[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 set of segments during which this flag was known, and its state was well defined.

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 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 : DataQualityDict a reference to the modified DataQualityDict

classmethod query(flags, *args, **kwargs)[source]¶

Query for segments of a set of flags.

This method intelligently selects the query_segdb or the query_dqsegdb methods based on the url kwarg given.

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 url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'
Returns:	flagdict : DataQualityDict A dict of (name, DataQualityFlag) pairs

See also

DataQualityDict.query_segdb

DataQualityDict.query_dqsegdb

for details on the actual query engine, and documentation of other keyword arguments appropriate for each query

classmethod query_dqsegdb(flags, *args, **kwargs)[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. 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 url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns:

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

classmethod query_segdb(flags, *args, **kwargs)[source]¶

Query the inital LIGO segment database 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. url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'
Returns:	flagdict : DataQualityDict An ordered DataQualityDict of (name, DataQualityFlag) pairs.

classmethod read(source, flags=None, format=None, **kwargs)[source]¶

Read segments from file into a DataQualityDict

Parameters:

source : str path of file to read format : str, optional source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats. flags : list, optional, default: read all flags found list of flags to read, by default all flags are read separately. coalesce : bool, optional, default: True coalesce all SegmentLists before returning. nproc : int, optional, default: 1 number of CPUs to use for parallel reading of multiple files verbose : bool, optional, default: False print a progress bar showing read status

Returns:

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

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	No	No
ligolw	Yes	Yes	Yes

setdefault(k[, d]) → od.get(k,d), also set od[k]=d if k not in od¶

to_ligolw_tables(**attrs)[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

union()[source]¶

Return the union of all flags in this dict

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

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of values in od¶

viewitems() → a set-like object providing a view on od's items¶

viewkeys() → a set-like object providing a view on od's keys¶

viewvalues() → an object providing a view on od's values¶

write(target, *args, **kwargs)[source]¶

Write this DataQualityDict to file

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	Yes	No
ligolw	Yes	Yes	Yes

copy(deep=False)[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 : DataQualityFlag a copy of the original dictionary

classmethod from_ligolw_tables(segmentdeftable, segmentsumtable, segmenttable, names=None, gpstype=<type 'lal.LIGOTimeGPS'>)[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, defaults to returning all 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 LIGOTimeGPS

Returns:

dqdict : DataQualityDict a dict of DataQualityFlag objects populated from the LIGO_LW tables

classmethod from_veto_definer_file(fp, start=None, end=None, ifo=None, format='ligolw')[source]

Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.

Parameters:	fp : str path of veto definer file to read start : LIGOTimeGPS, int, optional GPS start time at which to restrict returned flags end : LIGOTimeGPS, int, optional GPS end time at which to restrict returned flags ifo : str, optional interferometer prefix whose flags you want to read format : str, optional format of file to read, currently only ‘ligolw’ is supported
Returns:	flags : DataQualityDict 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()[source]

Return the intersection of all flags in this dict

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

plot(label='key', **kwargs)[source]

Plot the data for this dict.

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 other keyword arguments are passed to the plotter as appropriate

See also

gwpy.plotter.SegmentPlot, gwpy.plotter.SegmentAxes, gwpy.plotter.SegmentAxes.plot_dqdict

populate(source='http://segments.ldas.cit', segments=None, pad=True, on_error='raise', **kwargs)[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 set of segments during which this flag was known, and its state was well defined.

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 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 : DataQualityDict a reference to the modified DataQualityDict

classmethod query(flags, *args, **kwargs)[source]

Query for segments of a set of flags.

This method intelligently selects the query_segdb or the query_dqsegdb methods based on the url kwarg given.

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 url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'
Returns:	flagdict : DataQualityDict A dict of (name, DataQualityFlag) pairs

See also

DataQualityDict.query_segdb

DataQualityDict.query_dqsegdb

for details on the actual query engine, and documentation of other keyword arguments appropriate for each query

classmethod query_dqsegdb(flags, *args, **kwargs)[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. 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 url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns:

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

classmethod query_segdb(flags, *args, **kwargs)[source]

Query the inital LIGO segment database 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. url : str, optional URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'
Returns:	flagdict : DataQualityDict An ordered DataQualityDict of (name, DataQualityFlag) pairs.

classmethod read(source, flags=None, format=None, **kwargs)[source]

Read segments from file into a DataQualityDict

Parameters:

source : str path of file to read format : str, optional source format identifier. If not given, the format will be detected if possible. See below for list of acceptable formats. flags : list, optional, default: read all flags found list of flags to read, by default all flags are read separately. coalesce : bool, optional, default: True coalesce all SegmentLists before returning. nproc : int, optional, default: 1 number of CPUs to use for parallel reading of multiple files verbose : bool, optional, default: False print a progress bar showing read status

Returns:

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

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	No	No
ligolw	Yes	Yes	Yes

to_ligolw_tables(**attrs)[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

union()[source]

Return the union of all flags in this dict

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

write(target, *args, **kwargs)[source]

Write this DataQualityDict to file

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	Yes	No
ligolw	Yes	Yes	Yes