Class LigolwSegmentList

source code

object --+
         |
        LigolwSegmentList

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, but it should be expected that consumers of the segment list will treat all times when the segment list's state is unknown the same way.

Example:

>>> from glue.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 glue.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 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 is inconvenient to type, slow, and not readable, a special in-place arithmetic operation named .update() is provided to implement this operation.

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