DataQualityDict¶

class gwpy.segments.DataQualityDict[source]¶

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()
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(fp[, start, end, ...])	Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.
fromkeys(/, iterable[, value])	Create a new ordered dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
intersection()	Return the intersection of all flags in this dict
items()
keys()
move_to_end(/, key[, last])	Move an existing element to the end (or beginning if last is false).
plot([label])	Plot this flag on a segments projection.
pop(/, key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem(/[, last])	Remove and return a (key, value) pair from the dictionary.
populate([source, segments, pad, on_error])	Query the segment database for each flag's active segments.
query(flags, *args, **kwargs)	Query the advanced LIGO DQSegDB for a list of flags.
query_dqsegdb(flags, *args, **kwargs)	Query the advanced LIGO DQSegDB for a list of flags.
read(source[, names, format])	Read segments from file into a DataQualityDict
setdefault(/, key[, default])	Insert key with a value of default if key is not in the dictionary.
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, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()
write(target, *args, **kwargs)	Write this DataQualityDict to file

Methods Documentation

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

coalesce()[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=False)[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, segmentsumtable, segmenttable, names=None, gpstype=<class 'lal.LIGOTimeGPS'>, on_missing='error')[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, defaults to returning all

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(fp, start=None, end=None, ifo=None, format='ligolw')[source]¶

Read a DataQualityDict from a LIGO_LW XML VetoDefinerTable.

Parameters:¶

fpstr

path of veto definer file to read

startLIGOTimeGPS, int, optional

GPS start time at which to restrict returned flags

endLIGOTimeGPS, int, optional

GPS end time at which to restrict returned flags

ifostr, optional

interferometer prefix whose flags you want to read

formatstr, optional

format of file to read, currently only ‘ligolw’ is supported

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

fromkeys(/, iterable, value=None)¶

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶

Return the value for key if key is in the dictionary, else default.

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

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

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

move_to_end(/, key, last=True)¶

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

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

Plot this flag 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

pop(/, key, default=<unrepresentable>)¶

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(/, last=True)¶

Remove and return a (key, value) pair from the dictionary.

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:¶

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, *args, **kwargs)[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.

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

urlstr, optional

URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns:¶

flagdictDataQualityDict

An ordered DataQualityDict of (name, DataQualityFlag) pairs.

classmethod query_dqsegdb(flags, *args, **kwargs)[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.

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

urlstr, optional

URL of the segment database, defaults to $DEFAULT_SEGMENT_SERVER environment variable, or 'https://segments.ligo.org'

Returns:¶

flagdictDataQualityDict

An ordered DataQualityDict of (name, DataQualityFlag) pairs.

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

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

nprocint, optional, default: 1

number of CPUs 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.

Notes

The available built-in formats are:

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

setdefault(/, key, default=None)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

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:¶

segmentdeftableSegmentDefTable

the segment_definer table

segmentsumtableSegmentSumTable

the segment_summary table

segmenttableSegmentTable

the segment table

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

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

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

values() → an object providing a view on D'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