Data-quality segments¶

The DataQualityFlag¶

A DataQualityFlag is an annotated set of segments that indicate something about instrumental operation. Each flag is defined by applying some algorithm on data and generating a SegmentList that indicates some good or bad condition has been met during those times. For example, the times during which the LIGO interferometers are operating under ‘science-mode’ conditions are recorded as the ‘science’ flag, which are used by data analysis groups to define periods of data over which to run their pipelines. Conversely, in the last science run (S6, June 2009 - October 2010), high seismic noise around the observatory buildings was recorded in a data-quality flag used by analysis groups to veto periods of analysis due to sub-standard data.

Each DataQualityFlag has some key attributes:

The Segment Database¶

The LIGO and Virgo instruments utilise hundreds of data-quality flags to record instrumental state on a daily basis. These flags are stored in a joint segment database - a queryable database recording each flag, its valid and active segment lists, and all metadata associated with its generation. The segment database is the primary access point for users to study data-quality flags and apply them in their analyses.

The DataQualityFlag object comes with a direct link to the segment database, through the DataQualityFlag.query() classmethod:

classmethod DataQualityFlag.query(flag, *args, **kwargs)[source]

Query for segments of a given flag

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

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 url : str, optional, default: 'https://segments.ligo.org' URL of the segment database
Returns:	flag : DataQualityFlag A new DataQualityFlag, with the known and active lists filled appropriately.

See also

DataQualityFlag.query_segdb

DataQualityFlag.query_dqsegdb

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

DataQualityFlag applications¶

The major application of data-quality flags is to record times during which the instrument was operating outside of its nominal condition. These flags are typically generated by analysing auxiliary signals in the instrument that aren’t sensitive to gravitational-wave amplitude, but do have a recorded noise coupling into the main gravitational-wave channel.

The DataQualityDict¶

Groups of DataQualityFlags can be collected into a DataQualityDict, a simple extension of the OrderedDict with methods for operating on a group of flags in bulk.

The most immediate utility of this group class is a bulk query of the segment database, using the DataQualityDict.query() classmethod. This method is what is actually called by the DataQualityFlag.query() classmethod anyway.

Class reference¶

This reference includes the following class entries:

class gwpy.segments.DataQualityFlag(name=None, active=None, known=None, label=None, category=None, description=None, isgood=True, padding=None, valid=None)[source]¶

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?

Attributes Summary

active	The set of segments during which this flag was active.
category	Veto category for this flag.
description	Description of why/how this flag was generated.
extent	The single GPS [start, stop) enclosing segment of this DataQualityFlag.
ifo	The interferometer associated with this flag.
isgood	Whether active segments mean the instrument was in a good state.
known	The set of segments during which this flag was known, and its state was well defined.
label	A human-readable label for this flag.
livetime	Amount of time this flag was active.
name	The name associated with this flag.
padding	[start, end) padding for this flag’s active segments.
regular	True if the active segments are a proper subset of the known.
tag	The tag (name) associated with this flag.
texname	Name of this flag in LaTeX printable format.
valid	The set of segments during which this flag was known, and its state was well defined.
version	The version number of this flag.

Methods Summary

coalesce()	Coalesce the segments for this flag.
contract(x)	Contract each of the active Segments by x seconds.
copy()	Build an exact copy of this flag.
from_veto_def(veto)	Define a DataQualityFlag from a VetoDef
pad(*args, **kwargs)	Apply a padding to each segment in this DataQualityFlag
plot(**kwargs)	Plot this flag.
populate([source, segments, pad])	Query the segment database for this flag’s active segments.
protract(x)	Protract each of the active Segments by x seconds.
query(flag, *args, **kwargs)	Query for segments of a given flag
query_dqsegdb(*args, **kwargs)	Query the advanced LIGO DQSegDB for the given flag
query_segdb(flag, *args, **kwargs)	Query the initial LIGO segment database for the given flag
read(*args, **kwargs)	Read segments from file into a DataQualityFlag.
round()	Round this flag to integer segments.
write(data, *args, **kwargs)	Write out data

Attributes Documentation

active¶

The set of segments during which this flag was active.

category¶

Veto category for this flag.

Type:	int

description¶

Description of why/how this flag was generated.

Type:	str

extent¶

The single GPS [start, stop) enclosing segment of this DataQualityFlag.

Type:	Segment

ifo¶

The interferometer associated with this flag.

This should be a single uppercase letter and a single number, e.g. 'H1'.

Type:	str

isgood¶

Whether active segments mean the instrument was in a good state.

Type:	bool

known¶

The set of segments during which this flag was known, and its state was well defined.

label¶

A human-readable label for this flag.

For example: 'Science-mode'.

Type:	str

livetime¶

Amount of time this flag was active.

Type:	float

name¶

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

padding¶

[start, end) padding for this flag’s active segments.

regular¶

True if the active segments are a proper subset of the known.

Type:	bool

tag¶

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

Type:	str

texname¶

Name of this flag in LaTeX printable format.

valid¶

The set of segments during which this flag was known, and its state was well defined.

version¶

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.

Type:	int

Methods Documentation

coalesce()[source]¶

Coalesce the segments for this flag.

This method does two things:

• coalesces the known and active segment lists
• forces the active segments to be a proper subset of the known segments

Note

this operations is performed in-place.

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

contract(x)[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.

copy()[source]¶

Build an exact copy of this flag.

Returns:	flag2 : DataQualityFlag a copy of the original flag, but with a fresh memory address.

classmethod from_veto_def(veto)[source]¶

Define a DataQualityFlag from a VetoDef

pad(*args, **kwargs)[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 known and active lists, but will not coalesce() the result.

Parameters:	start : float padding to apply to the start of the each segment end : float padding to apply to the end of each segment inplace : bool, optional, default: False modify this object in-place, default is False, i.e. return a copy of the original object with padded segments
Returns:	paddedflag : DataQualityFlag a view of the modified flag

plot(**kwargs)[source]¶

Plot this flag.

Parameters:	**kwargs : all keyword arguments are passed to the SegmentPlot constructor.
Returns:	plot : SegmentPlot a new Plot with this flag displayed on a set of SegmentAxes.

populate(source='https://segments.ligo.org', segments=None, pad=True, **kwargs)[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 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.

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 valid segments during which to query, if not given, existing known segments for this flag will be used. pad : bool, optional, default: True apply the padding associated with this flag, default: True. **kwargs : any other keyword arguments to be passed to DataQualityFlag.query() or DataQualityFlag.read().

Returns:

self : DataQualityFlag a reference to this flag

protract(x)[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.

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

Query for segments of a given flag

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

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 url : str, optional, default: 'https://segments.ligo.org' URL of the segment database
Returns:	flag : DataQualityFlag A new DataQualityFlag, with the known and active lists filled appropriately.

See also

DataQualityFlag.query_segdb

DataQualityFlag.query_dqsegdb

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

classmethod query_dqsegdb(*args, **kwargs)[source]¶

Query the advanced LIGO DQSegDB for the given 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 url : str, optional, default: 'https://segments.ligo.org' URL of the segment database
Returns:	flag : DataQualityFlag A new DataQualityFlag, with the known and active lists filled appropriately.

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

Query the initial LIGO segment database for the given 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 url : str, optional, default: 'https://segments.ligo.org' URL of the segment database
Returns:	flag : DataQualityFlag A new DataQualityFlag, with the known and active lists filled appropriately.

classmethod read(*args, **kwargs)¶

Read segments from file into a DataQualityFlag.

Parameters:

filename : 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. flag : str, optional, default: read all segments name of flag to read from file. coltype : type, optional, default: float datatype to force for segment times, only valid for format='segwizard'. strict : bool, optional, default: True require segment start and stop times match printed duration, only valid for format='segwizard'.

Returns:

dqflag : DataQualityFlag formatted DataQualityFlag containing the active and known segments read from file.

Notes

When reading with format='segwizard' the known SegmentList will simply represent the extent of the active SegmentList. The available built-in formats are:

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

round()[source]¶

Round this flag to integer segments.

Returns:	roundedflag : DataQualityFlag A copy of the original flag with the active and known segments padded out to the enclosing integer boundaries.

write(data, *args, **kwargs)¶

Write out data

The arguments passed to this method depend on the format

The available built-in formats are:

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

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(() -> a shallow copy of od)
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(flag, *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(*args, **kwargs)	Read segments from file into a DataQualityDict.
setdefault((k[,d]) -> od.get(k,d), ...)
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(data, *args, **kwargs)	Write out data

Methods Documentation

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

copy() → a shallow copy of od¶

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 (passed to VetoDefTable.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='https://segments.ligo.org', 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(flag, *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, default: 'https://segments.ligo.org' URL of the segment database
Returns:	flag : DataQualityFlag A new DataQualityFlag, with the known and active lists filled appropriately.

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, default: 'https://segments.ligo.org' URL of the segment database.

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, default: 'https://segments.ligo.org' URL of the segment database.
Returns:	flagdict : `DataQualityDict An ordered DataQualityDict of (name, DataQualityFlag) pairs.

classmethod read(*args, **kwargs)¶

Read segments from file into a DataQualityDict.

Parameters:	filename : 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.
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
ligolw	Yes	No	No

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

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(data, *args, **kwargs)¶

Write out data

The arguments passed to this method depend on the format

The available built-in formats are:

Format	Read	Write	Auto-identify
ligolw	Yes	Yes	No

class gwpy.segments.Segment[source]¶

Bases: glue.__segments.segment

The Segment class defines objects that represent a range of values. A Segment has a start and an end, and is taken to represent the range of values in the semi-open interval [start, end). Some limited arithmetic operations are possible with Segments, but because the set of (single) Segments is not closed under the sensible definitions of the standard arithmetic operations, the behaviour of the arithmetic operators on Segments may not be as you would expect. For general arithmetic on Segments, use SegmentList objects. The methods for this class exist mostly for purpose of simplifying the implementation of the SegmentList class.

The Segment class is a subclass of the tuple built-in class provided by Python. This means Segments are immutable — you cannot modify a Segment object after creating it, to change the boundaries of a Segment you must create a new Segment object with the desired boundaries. Like tuples, Segments can be used as dictionary keys, and like tuples the comparison used to find a Segment in the dictionary is done by value not by ID. And, like tuples, a Segment can be created from any sequence-like object by passing it to the constructor (the sequence must have exactly two elements in it).

Example:

>>> `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
>>> bool(`Segment`(0, 0))
False
>>> `Segment`("AAA Towing", "York University") & `Segment`("Pool", "Zoo")
`Segment`('Pool', 'York University')
>>> x = [0, 1]
>>> `Segment`(x)
`Segment`(0, 1)
>>> y = `Segment`(0, 1)
>>> y == x
True
>>> y is x
False
>>> z = {x: ["/path/to/file1", "/path/to/file2"]}
>>> y in z
True
>>> z[y]
['/path/to/file1', '/path/to/file2']

Attributes Summary

end	The GPS end time of this segment
start	The GPS start time of this segment

Methods Summary

contract	Return a new segment whose bounds are given by adding x to the segment’s lower bound and subtracting x from the segment’s upper bound.
count(...)
disjoint	Returns >0 if self covers an interval above other’s interval, <0 if self covers an interval below other’s, or 0 if the two intervals are not disjoint (intersect or touch).
index((value, [start, ...)	Raises ValueError if the value is not present.
intersects	Return True if the intersection of self and other is not a null segment.
protract	Return a new segment whose bounds are given by subtracting x from the segment’s lower bound and adding x to the segment’s upper bound.
shift	Return a new segment whose bounds are given by adding x to the segment’s upper and lower bounds.

Attributes Documentation

end¶

The GPS end time of this segment

start¶

The GPS start time of this segment

Methods Documentation

contract()¶

Return a new segment whose bounds are given by adding x to the segment’s lower bound and subtracting x from the segment’s upper bound.

count(value) → integer -- return number of occurrences of value¶

disjoint()¶

Returns >0 if self covers an interval above other’s interval, <0 if self covers an interval below other’s, or 0 if the two intervals are not disjoint (intersect or touch). A return value of 0 indicates the two segments would coalesce.

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

intersects()¶

Return True if the intersection of self and other is not a null segment.

protract()¶

Return a new segment whose bounds are given by subtracting x from the segment’s lower bound and adding x to the segment’s upper bound.

shift()¶

Return a new segment whose bounds are given by adding x to the segment’s upper and lower bounds.

class gwpy.segments.SegmentList[source]¶

Bases: glue.__segments.segmentlist

The SegmentList class defines a list of Segments, and is an extension of the built-in list class. This class provides addtional methods that assist in the manipulation of lists of Segments. In particular, arithmetic operations such as union and intersection are provided. Unlike the Segment class, the SegmentList class 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 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 `SegmentList`s exclusively via the arithmetic operators.

Example:

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

Methods Summary

append	L.append(object) – append object to end
coalesce()	Sort the elements of a list into ascending order, and merge continuous segments into single segments.
contract	Execute the .contract() method on each segment in the list and coalesce the result.
count(...)
extend	L.extend(iterable) – extend list by appending elements from the iterable
extent	Return the segment whose end-points denote the maximum and minimum extent of the segmentlist.
find	Return the smallest i such that i is the index of an element that wholly contains item.
index((value, [start, ...)	Raises ValueError if the value is not present.
insert	L.insert(index, object) – insert object before index
intersects	Returns True if the intersection of self and the segmentlist other is not the null set, otherwise returns False.
intersects_segment	Returns True if the intersection of self and the segment other is not the null set, otherwise returns False.
pop(...)	Raises IndexError if list is empty or index is out of range.
protract	Execute the .protract() method on each segment in the list and coalesce the result.
read(*args, **kwargs)	Read segments from file into a SegmentList.
remove	L.remove(value) – remove first occurrence of value.
reverse	L.reverse() – reverse IN PLACE
shift	Execute the .shift() method on each segment in the list.
sort	L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE;
write(data, *args, **kwargs)	Write out data

Methods Documentation

append()¶

L.append(object) – append object to end

coalesce()[source]¶

Sort the elements of a list into ascending order, and merge continuous segments into single segments. This operation is O(n log n).

contract()¶

Execute the .contract() method on each segment in the list and coalesce the result. Segmentlist is modified in place.

count(value) → integer -- return number of occurrences of value¶

extend()¶

L.extend(iterable) – extend list by appending elements from the iterable

extent()¶

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

find()¶

Return the smallest i such that i is the index of an element that wholly contains item. Raises ValueError if no such element exists. Does not require the segmentlist to be coalesced.

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

insert()¶

L.insert(index, object) – insert object before index

intersects()¶

Returns True if the intersection of self and the segmentlist other is not the null set, otherwise returns False. The algorithm is O(n), but faster than explicit calculation of the intersection, i.e. by testing bool(self & other). Requires both lists to be coalesced.

intersects_segment()¶

Returns True if the intersection of self and the segment other is not the null set, otherwise returns False. The algorithm is O(log n). Requires the list to be coalesced.

pop([index]) → item -- remove and return item at index (default last).¶

Raises IndexError if list is empty or index is out of range.

protract()¶

Execute the .protract() method on each segment in the list and coalesce the result. Segmentlist is modified in place.

classmethod read(*args, **kwargs)¶

Read segments from file into a SegmentList.

Parameters:

filename : 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. flag : str, optional, default: read all segments name of flag to read from file. gpstype : type, optional, default: float datatype to force for segment GPS times strict : bool, optional, default: True require segment start and stop times match printed duration, only valid for format='segwizard'.

Returns:

segmentlist : SegmentList SegmentList active and known segments read from file.

Notes

When reading with format='segwizard' the known SegmentList will simply represent the extent of the active SegmentList. The available built-in formats are:

Format	Read	Write	Auto-identify
hdf	Yes	No	No
hdf5	Yes	Yes	Yes
segwizard	Yes	Yes	Yes

remove()¶

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()¶

L.reverse() – reverse IN PLACE

shift()¶

Execute the .shift() method on each segment in the list. The algorithm is O(n) and does not require the list to be coalesced nor does it coalesce the list. Segmentlist is modified in place.

sort()¶

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

write(data, *args, **kwargs)¶

Write out data

The arguments passed to this method depend on the format

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf	Yes	Yes	No
hdf5	Yes	Yes	Yes
segwizard	Yes	Yes	Yes

class gwpy.segments.SegmentListDict(*args)[source]¶

Bases: glue.segments.segmentlistdict

A dictionary associating a unique label and numeric offset with each of a set of SegmentList objects.

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

Example:

>>> 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)]}

Methods Summary

all_intersects(other)	Returns True if each segmentlist in self intersects the corresponding segmentlist in other; returns False if this is not the case or if self is empty.
all_intersects_all(other)	Returns True if self and other have the same keys, and each segmentlist intersects the corresponding segmentlist in the other; returns False if this is not the case or if either dictionary is empty.
clear(() -> None.  Remove all items from D.)
coalesce()	Run .coalesce() on all segmentlists.
contract(x)	Run .contract(x) on all segmentlists.
copy([keys])	Return a copy of the segmentlistdict object.
extend(other)	Appends the segmentlists from other to the corresponding segmentlists in self, adding new segmentslists to self as needed.
extent()	Return a dictionary of the results of running .extent() on each of the segmentlists.
extent_all()	Return the result of running .extent() on the union of all lists in the dictionary.
extract_common(keys)	Return a new segmentlistdict containing only those segmentlists associated with the keys in keys, with each set to their mutual intersection.
find(item)	Return a dictionary of the results of running .find() on each of the segmentlists.
fromkeys(...)	v 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(keys)	Return the intersection of the segmentlists associated with the keys in keys.
intersects(other)	Returns True if there exists a segmentlist in self that intersects the corresponding segmentlist in other; returns False otherwise.
intersects_all(other)	Returns True if each segmentlist in other intersects the corresponding segmentlist in self; returns False if this is not the case, or if other is empty.
intersects_segment(seg)	Returns True if any segmentlist in self intersects the segment, otherwise returns False.
is_coincident(other[, keys])	Return True if any segment in any list in self intersects any segment in any list in other.
items(() -> list of D’s (key, value) pairs, ...)
iteritems(() -> an iterator over the (key, ...)
iterkeys(() -> an iterator over the keys of D)
itervalues(...)
keys(() -> list of D’s keys)
keys_at(x)	Return a list of the keys for the segment lists that contain x.
map(func)	Return a dictionary of the results of func applied to each of the segmentlist objects in self.
pop((k[,d]) -> v, ...)	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(() -> (k, v), ...)	2-tuple; but raise KeyError if D is empty.
protract(x)	Run .protract(x) on all segmentlists.
read(*args, **kwargs)	Read segments from file into a SegmentListDict.
setdefault((k[,d]) -> D.get(k,d), ...)
union(keys)	Return the union of the segmentlists associated with the keys in keys.
update(([E, ...)	If E present and has a .keys() method, does: for k in E: D[k] = E[k]
values(() -> list of D’s values)
viewitems(...)
viewkeys(...)
viewvalues(...)
write(data, *args, **kwargs)	Write out data

Methods Documentation

all_intersects(other)¶

Returns True if each segmentlist in self intersects the corresponding segmentlist in other; returns False if this is not the case or if self is empty.

See also:

.intersects, .intersects_all(), .all_intersects_all()

all_intersects_all(other)¶

Returns True if self and other have the same keys, and each segmentlist intersects the corresponding segmentlist in the other; returns False if this is not the case or if either dictionary is empty.

See also:

.intersects(), .all_intersects(), .intersects_all()

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

coalesce()¶

Run .coalesce() on all segmentlists.

contract(x)¶

Run .contract(x) on all segmentlists.

copy(keys=None)¶

Return a copy of the segmentlistdict object. The return value is a new object with a new offsets attribute, with references to the original keys, and shallow copies of the segment lists. Modifications made to the offset dictionary or segmentlists in the object returned by this method will not affect the original, but without using much memory until such modifications are made. If the optional keys argument is not None, then should be an iterable of keys and only those segmentlists will be copied (KeyError is raised if any of those keys are not in the segmentlistdict).

More details. There are two “built-in” ways to create a copy of a segmentlist object. The first is to initialize a new object from an existing one with

>>> old = segmentlistdict()
>>> new = segmentlistdict(old)

This creates a copy of the dictionary, but not of its contents. That is, this creates new with references to the segmentlists in old, therefore changes to the segmentlists in either new or old are reflected in both. The second method is

>>> new = old.copy()

This creates a copy of the dictionary and of the segmentlists, but with references to the segment objects in the original segmentlists. Since segments are immutable, this effectively creates a completely independent working copy but without the memory cost of a full duplication of the data.

extend(other)¶

Appends the segmentlists from other to the corresponding segmentlists in self, adding new segmentslists to self as needed.

extent()¶

Return a dictionary of the results of running .extent() on each of the segmentlists.

extent_all()¶

Return the result of running .extent() on the union of all lists in the dictionary.

extract_common(keys)¶

Return a new segmentlistdict containing only those segmentlists associated with the keys in keys, with each set to their mutual intersection. The offsets are preserved.

find(item)¶

Return a dictionary of the results of running .find() on each of the segmentlists.

Example:

>>> x = segmentlistdict()
>>> x["H1"] = segmentlist([segment(0, 10)])
>>> x["H2"] = segmentlist([segment(5, 15)])
>>> x.find(7)
{'H2': 0, 'H1': 0}

NOTE: all segmentlists must contain the item or KeyError is raised.

fromkeys(S[, v]) → New dict with keys from S and values equal to v.¶

v 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(keys)¶

Return the intersection of the segmentlists associated with the keys in keys.

intersects(other)¶

Returns True if there exists a segmentlist in self that intersects the corresponding segmentlist in other; returns False otherwise.

See also:

.intersects_all(), .all_intersects(), .all_intersects_all()

intersects_all(other)¶

Returns True if each segmentlist in other intersects the corresponding segmentlist in self; returns False if this is not the case, or if other is empty.

See also:

.intersects(), .all_intersects(), .all_intersects_all()

intersects_segment(seg)¶

Returns True if any segmentlist in self intersects the segment, otherwise returns False.

is_coincident(other, keys=None)¶

Return True if any segment in any list in self intersects any segment in any list in other. If the optional keys argument is not None, then it should be an iterable of keys and only segment lists for those keys will be considered in the test (instead of raising KeyError, keys not present in both segment list dictionaries will be ignored). If keys is None (the default) then all segment lists are considered.

This method is equivalent to the intersects() method, but without requiring the keys of the intersecting segment lists to match.

items() → list of D's (key, value) pairs, as 2-tuples¶

iteritems() → an iterator over the (key, value) items of D¶

iterkeys() → an iterator over the keys of D¶

itervalues() → an iterator over the values of D¶

keys() → list of D's keys¶

keys_at(x)¶

Return a list of the keys for the segment lists that contain x.

Example:

>>> x = segmentlistdict()
>>> x["H1"] = segmentlist([segment(0, 10)])
>>> x["H2"] = segmentlist([segment(5, 15)])
>>> x.keys_at(12)
['H2']

map(func)¶

Return a dictionary of the results of func applied to each of the segmentlist objects in self.

Example:

>>> x = segmentlistdict()
>>> x["H1"] = segmentlist([segment(0, 10)])
>>> x["H2"] = segmentlist([segment(5, 15)])
>>> x.map(lambda l: 12 in l)
{'H2': True, 'H1': False}

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), remove and return some (key, value) pair as a¶

2-tuple; but raise KeyError if D is empty.

protract(x)¶

Run .protract(x) on all segmentlists.

classmethod read(*args, **kwargs)¶

Read segments from file into a SegmentListDict.

Parameters:

filename : 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 name of flag to read from file. gpstype : type, optional, default: float datatype to force for segment GPS times strict : bool, optional, default: True require segment start and stop times match printed duration, only valid for format='segwizard'.

Returns:

dqflag : DataQualityFlag formatted DataQualityFlag containing the active and known segments read from file.

Notes

When reading with format='segwizard' the known SegmentList will simply represent the extent of the active SegmentList.

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

union(keys)¶

Return the union of the segmentlists associated with the keys in keys.

update([E, ]**F) → None. Update D from dict/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 in F: D[k] = F[k]

values() → list of D's values¶

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

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

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

write(data, *args, **kwargs)¶

Write out data

The arguments passed to this method depend on the format