SegmentList¶

class gwpy.segments.SegmentList(iterable=(), /)[source]¶

A list of Segments

The SegmentList provides additional methods that assist in the manipulation of lists of Segments. In particular, arithmetic operations such as union and intersection are provided. Unlike the Segment, the SegmentList 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 a SegmentList exclusively via the arithmetic operators.

Examples

>>> 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`(object, /)	Append object to the end of the list.
`clear`(/)	Remove all items from list.
`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.
`copy`(/)	Return a shallow copy of the list.
`count`(value, /)	Return number of occurrences of value.
`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, stop])	Return first index of value.
`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`([index])	Remove and return item at index (default last).
`protract`	Execute the .protract() method on each segment in the list and coalesce the result.
`read`(source[, format, coalesce])	Read segments from file into a `SegmentList`
`remove`(value, /)	Remove first occurrence of value.
`reverse`(/)	Reverse IN PLACE.
`shift`	Execute the .shift() method on each segment in the list.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`to_table`()	Convert this `SegmentList` to a `Table`
`value_slice_to_index`	Convert the slice s from a slice of values to a slice of indexes.
`write`(target, args, *kwargs)	Write this `SegmentList` to a file

Methods Documentation

append(object, /)¶: Append object to the end of the list.

clear(/)¶: Remove all items from list.

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.

copy(/)¶: Return a shallow copy of the list.

count(value, /)¶: Return number of occurrences of value.

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=0, stop=sys.maxsize, /)¶

Return first index of value.

Raises ValueError if the value is not present.

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=-1, /)¶

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(source, format=None, coalesce=False, **kwargs)[source]¶

Read segments from file into a SegmentList

Parameters:¶

filenamestr: 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.
coalescebool, optional: if True coalesce the segment list before returning, otherwise return exactly as contained in file(s).
**kwargs: other keyword arguments depend on the format, see the online documentation for details (Reading/writing segments and flags)

Returns:¶

segmentlistSegmentList: SegmentList active and known segments read from file.

Raises:¶

IndexError: if source is an empty list

Notes

The available built-in formats are:

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

remove(value, /)¶

Remove first occurrence of value.

Raises ValueError if the value is not present.

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(*, key=None, reverse=False)¶

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_table()[source]¶

Convert this SegmentList to a Table

The resulting Table has four columns: index, start, end, and duration, corresponding to the zero-counted list index, GPS start and end times, and total duration in seconds, respectively.

This method exists mainly to provide a way to write SegmentList objects in comma-separated value (CSV) format, via the write() method.

value_slice_to_index()¶

Convert the slice s from a slice of values to a slice of indexes. self must be coalesced, the operation is O(log n). This is used to extract from a segmentlist the segments that span a given range of values, and is useful in reducing operation counts when many repeated operations are required within a limited range of values.

NOTE: the definition of the transformation is important, and some care might be needed to use this tool properly. The start and stop values of the slice are transformed independently. The start value is mapped to the index of the first segment whose upper bound is greater than start, meaning the first segment spanning values greater than or equal to the value of start. The stop value is mapped to 1 + the index of the last segment whose lower bound is less than stop, meaning the last segment spanning values less than the value of stop. This can lead to unexpected behaviour if value slices whose upper and lower bounds are identical are transformed to index slices. For example:

>>> x = segmentlist([segment(-10, -5), segment(5, 10), segment(20, 30)])
>>> x.value_slice_to_index(slice(5, 5))
slice(1, 1, None)
>>> x.value_slice_to_index(slice(6, 6))
slice(1, 2, None)
Both value slices are zero-length, but one has yielded a zero-length (null) index slice, while the other has not.  The two value slices start at 5 and 6 respectively.  Both starting values lie within segment 1, and in both cases the start value has been mapped to index 1, as expected.  The first slice ends at 5, meaning it expresses the idea of a range of values upto but not including 5, which corresponds to segments upto *but not including* index 1, and so that stop value has been mapped to an index slice upper bound of 1.  The second slice ends at 6, and the range of values upto but not including 6 corresponds to segment indexes upto but not including 2, which is what we see that bound has been mapped to.

Examples:

>>> x = segmentlist([segment(-10, -5), segment(5, 10), segment(20, 30)])
>>> x
[segment(-10, -5), segment(5, 10), segment(20, 30)]
>>> x[x.value_slice_to_index(slice(7, 8))]
[segment(5, 10)]
>>> x[x.value_slice_to_index(slice(7, 10))]
[segment(5, 10)]
>>> x[x.value_slice_to_index(slice(7, 18))]
[segment(5, 10)]
>>> x[x.value_slice_to_index(slice(7, 20))]
[segment(5, 10)]
>>> x[x.value_slice_to_index(slice(7, 25))]
[segment(5, 10), segment(20, 30)]
>>> x[x.value_slice_to_index(slice(10, 10))]
[]
>>> x[x.value_slice_to_index(slice(10, 18))]
[]
>>> x[x.value_slice_to_index(slice(10, 20))]
[]
>>> x[x.value_slice_to_index(slice(10, 25))]
[segment(20, 30)]
>>> x[x.value_slice_to_index(slice(20, 20))]
[]
>>> x[x.value_slice_to_index(slice(21, 21))]
[segment(20, 30)]
>>> x[x.value_slice_to_index(slice(-20, 8))]
[segment(-10, -5), segment(5, 10)]
>>> x[x.value_slice_to_index(slice(-20, -15))]
[]
>>> x[x.value_slice_to_index(slice(11, 18))]
[]
>>> x[x.value_slice_to_index(slice(40, 50))]
[]
>>> x[x.value_slice_to_index(slice(None, 0))]
[segment(-10, -5)]
>>> x[x.value_slice_to_index(slice(0, None))]
[segment(5, 10), segment(20, 30)]

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

Write this SegmentList to a file

Arguments and keywords depend on the output format, see the online documentation for full details for each format.

Parameters:¶

targetstr: output filename

Notes

The available built-in formats are:

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