LigolwSegmentList

class igwn_ligolw.utils.segments.LigolwSegmentList(active=(), valid=(), instruments=(), name=None, version=None, comment=None)

Bases: object

A description of a LIGO Light-Weight XML segment list. Instances of this class carry all the metadata associated with a LIGO Light- Weight XML segment list including its name, version number, a comment, and so on.

LIGO Light-Weight XML segment lists are three-state objects. A segment list can be on, off, or undefined. Two separate sequences of segments are used for this: the “valid” list defines the intervals when the state of the segment list is known, and the “active” list defines the intervals when the segment list is on. It is not an error for the active list to be on during times when the segment lists state is unknown, this code does not impose any policy in that regard.

Example:

>>> from igwn_segments import *
>>> segs = segmentlist([segment(0, 10), segment(20, 30)])
>>> validity = segmentlist([segment(0, 10), segment(25, 100)])
>>> x = LigolwSegmentList(active = segs, valid = validity, instruments = set(("H1",)), name = "test")
>>> # x made copies of arguments
>>> del segs[:]
>>> segs
[]
>>> x.active
[segment(0, 10), segment(20, 30)]
>>> # some typical operations
>>> x.active & x.valid  # known true
[segment(0, 10), segment(25, 30)]
>>> ~x.active & x.valid # known false
[segment(30, 100)]
>>> x.active & ~x.valid # not an error for this to be non-null
[segment(20, 25)]
>>> # make a copy
>>> y = LigolwSegmentList(x)
>>> del y.active[:]
>>> y.active
[]
>>> x.active
[segment(0, 10), segment(20, 30)]

The arithmetic operators on this class implement Kleene’s strong ternary logic, taking “true” to be (active & valid), “false” to be (~active & valid), and “unknown” to be ~valid.

Example:

>>> from igwn_segments import *
>>> segs = segmentlist([segment(0, 10), segment(20, 30)])
>>> validity = segmentlist([segment(0, 35)])
>>> x = LigolwSegmentList(active = segs, valid = validity, instruments = set(("H1",)), name = "test")
>>> segs = segmentlist([segment(40, 50), segment(60, 70)])
>>> validity = segmentlist([segment(35, 100)])
>>> y = LigolwSegmentList(active = segs, valid = validity, instruments = set(("H1",)), name = "test")
>>> (x | y).active
[segment(0, 10), segment(20, 30), segment(40, 50), segment(60, 70)]
>>> (x | y).valid
[segment(0, 10), segment(20, 30), segment(40, 50), segment(60, 70)]
>>> (x & y).active
[]
>>> (x & y).valid
[segment(10, 20), segment(30, 40), segment(50, 60), segment(70, 100)]
>>> (~x).active
[segment(10, 20), segment(30, 35)]
>>> (~x).valid
[segment(0, 35)]

With ternary logic the three basic Boolean operations AND, OR, and NOT, do not form a complete set of operations. That is, there exist algebraic functions that cannot be implemented using combinations of these three operators alone. One additional operator is required to construct a complete basis of logic operations, and we provide one: .isfalse(). This operation inverts intervals of known state, and maps intervals of unknown state to false.

>>> x.isfalse().active
[segment(10, 20), segment(30, 35)]
>>> x.isfalse().valid
[segment(-infinity, infinity)]

Unfortunately, one example of a function that cannot be constructed from the three basic Boolean operators is perhaps the most common operation we wish to perform with our tri-state segment lists. Often we wish to construct a tri-state list from two tri-state lists such that the final list’s interval of validity is the union of the intervals of validity of the two source lists, and the state of the final list in that interval is the union of the states of the source lists in that interval. For example if from one source we know the state of some process spanning some time, and from another source we know the state of the same process spanning some other time, taken together we know the state of that process over the union of those times. This function is given by

>>> z = ~(x.isfalse() | y.isfalse() | (x & ~x & y & ~y))
>>> z.active
[segment(0, 10), segment(20, 30), segment(40, 50), segment(60, 70)]
>>> z.valid
[segment(0, 100)]

Because this arithmetic expression is inconvenient to type, slow to evaluate, and incomprehensible, a special in-place arithmetic operation named .update() is provided to implement this.

>>> z = LigolwSegmentList(x).update(y)
>>> z.active
[segment(0, 10), segment(20, 30), segment(40, 50), segment(60, 70)]
>>> z.valid
[segment(0, 100)]

The .update() method is not exactly equivalent to the operation above. The .update() method demands that the two input lists’ states be identical where their intervals of validity intersect, whereas the arithmetic expression above yields their union where their intervals of validity intersect.

Attributes Summary

segment_columns
segment_def_columns
segment_sum_columns

Methods Summary

coalesce()	Coalesce the internal segment lists.
isfalse()	If unknown the result is false, otherwise the state is inverted.
sort(*args, **kwargs)	Sort the internal segment lists.
update(other)

Attributes Documentation

segment_columns = ('process:process_id', 'segment_id', 'start_time', 'start_time_ns', 'end_time', 'end_time_ns', 'segment_definer:segment_def_id')

segment_def_columns = ('process:process_id', 'segment_def_id', 'ifos', 'name', 'version', 'comment')

segment_sum_columns = ('process:process_id', 'segment_sum_id', 'start_time', 'start_time_ns', 'end_time', 'end_time_ns', 'segment_definer:segment_def_id', 'comment')

Methods Documentation

coalesce()

Coalesce the internal segment lists. Returns self.

isfalse()

If unknown the result is false, otherwise the state is inverted.

sort(*args, **kwargs)

Sort the internal segment lists. The optional args and kwargs are passed to the .sort() method of the segment lists. This can be used to control the sort order by providing an alternate comparison function. The default is to sort by start time with ties broken by end time.

update(other)