SegmentList¶

class gwpy.segments.SegmentList[source]¶

Bases: glue.__segments.segmentlist

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	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(source[, format])	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(target, *args, **kwargs)	Write this SegmentList to a file

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

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.
Returns:	segmentlist : SegmentList SegmentList active and known segments read from file.

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
hdf5	Yes	No	No
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(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:	target : str output filename

Notes

The available built-in formats are:

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

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

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

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.
Returns:	segmentlist : SegmentList SegmentList active and known segments read from file.

Notes

The available built-in formats are:

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

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:	target : str output filename

Notes

The available built-in formats are:

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