Intervals.py - Utility functions for working with intervals

This module contains utility functions for working intervals or list of intervals.

An interval is a tuple of a start and end coordinate in python’s 0-based, half-open notation such as:

(12, 20)

An interval list is simply a list of such intervals.

The majority of the functions in this module take one or more lists of intervals and return one or more new lists of intervals.

Reference

Intervals.getLength(intervals)

return sum of intervals lengths.

>>> getLength([(10,20), (30,40)])
20
Intervals.combine(intervals)

combine overlapping and adjacent intervals.

>>> combine([(10,20), (30,40)])
[(10, 20), (30, 40)]
>>> combine([(10,20), (20,40)])
[(10, 40)]
>>> combine([(10,20), (15,40)])
[(10, 40)]
Intervals.prune(intervals, first=None, last=None)

truncates all intervals that are extending beyond first or last.

Empty intervals are deleted.

Intervals.complement(intervals, first=None, last=None)

complement a list of intervals with intervals not in list.

>>> complement([(10,20), (15,40)])
[]
>>> complement([(10,20), (30,40)])
[(20, 30)]
>>> complement([(10,20), (30,40)], first=5)
[(5, 10), (20, 30)]
Parameters

  • intervals (list) – List of intervals

  • first (int) – First position. If given, the interval from first to the first position in intervals is added.

  • last (int) – Last position. If given, the interval from the last position in intervals to last is added.

Returns

intervals – A new list of intervals

Return type

list

Intervals.addComplementIntervals(intervals, first=None, last=None)

complement a list of intervals with intervals not in list and return both.

The resulting interval list is sorted.

Intervals.joined_iterator(intervals1, intervals2)

iterate over the combination of two intervals.

returns the truncated intervals delineating the ranges of overlap between intervals1 and intervals2.

Intervals.intersect(intervals1, intervals2)

intersect two interval sets.

Return a set of intervals that is spanned by intervals in both sets. Returns the union of the two intervals.

Intervals.truncate(intervals1, intervals2)

truncate intervals in intervals1 by intervals2

Example: truncate( [(0,5)], [(0,3)] ) = [(3,5)]

Intervals.calculateOverlap(intervals1, intervals2)

calculate overlap between two list of intervals.

The intervals within each set should not be overlapping.

Intervals.fromArray(a)

get intervals from a binary array.

Intervals.combineAtDistance(intervals, min_distance)

combine a list intervals and merge those that are less than a certain distance apart.

Intervals.getIntersections(intervals)

return regions were two intervals are overlapping.

Intervals.RemoveIntervalsContained(intervals)

remove intervals that are fully contained in another

[(10, 100), (20, 50), (70, 120), (130, 200), (10, 50), (140, 210), (150, 200)]

results:

[(10, 100), (70, 120), (130, 200), (140, 210)]

Intervals.RemoveIntervalsSpanning(intervals)

remove intervals that are full covering another, i.e. always keep the smallest.

[(10, 100), (20, 50), (70, 120), (40,80), (130, 200), (10, 50), (140, 210), (150, 200)]

result:

[(20, 50), (40, 80), (70, 120), (150, 200)]

Intervals.ShortenIntervalsOverlap(intervals, to_remove)

shorten intervals, so that there is no overlap with another set of intervals.

assumption: intervals are not overlapping