SegmentList

class gwpy.segments.SegmentList(iterable=(), /)

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

Attributes Summary

read	Read segments from file into a SegmentList.
write	Write this SegmentList to a file.

Methods Summary

coalesce()	Sort the elements of the list into ascending order, and merge continuous segments into single segments.
extent	Return the segment whose end-points denote the maximum and minimum extent of the segmentlist.
to_table()	Convert this SegmentList to a Table.

Attributes Documentation

read

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 SegmentList.read.help(format=<format>) for details, or see the online documentation (Reading/writing segments and flags).

Returns:

segmentlistSegmentList

SegmentList active and known segments read from file.

Raises:

IndexError

if source is an empty list

write

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.

Methods Documentation

coalesce() → Self

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

extent()

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

to_table() → Table

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.