Interval Operations¶

The Interval class provides several operations to manipulate and combine interval objects.

First, let’s create some simple intervals:

from temporaldata import Interval
import numpy as np

# Create two intervals: [1, 8] and [12, 18]
interval1 = Interval(start=np.array([1., 12.]),end=np.array([8., 18.]))

# Create three intervals: [2, 5], [7, 10], and [14, 17]
interval2 = Interval(start=np.array([2., 7., 14.]), end=np.array([5., 10., 17.]))

Typically for most operations that involve multiple Interval objects, each Interval object must be disjoint and sorted.

You can check these conditions using:

interval.is_disjoint()  # Returns True if intervals don't overlap
interval.is_sorted()    # Returns True if intervals are sorted by start time

Intersection¶

The intersection operation (&) returns a new Interval containing only the overlapping time periods between two Interval objects.

# Compute intersection
intersection = interval1 & interval2

# Result will contain [2, 5], [7, 8] and [14, 17] as these are the overlapping periods
print(intersection.start)  # [2., 7., 14.]
print(intersection.end)    # [5., 8., 17.]

Union¶

The union operation (|) returns a new Interval containing the union of all intervals in both objects.

# Compute union
union = interval1 | interval2

# Result will contain [1, 10] and [12, 18]
print(union.start)  # [ 1., 12.]
print(union.end)    # [10., 18.]

Difference¶

The difference operation (.difference()) returns a new Interval containing time periods that are in the first interval but not in the second interval.

# Compute difference
difference = interval1.difference(interval2)

# Results in intervals: [1, 2], [5, 7], [12, 14], and [17, 18]
print(difference.start)  # [1., 5., 12., 17.]
print(difference.end)    # [2., 7., 14., 18.]

Dilation¶

The dilation operation (.dilate()) expands each interval by a specified amount on both sides. This is useful for creating buffer periods around intervals or merging nearby intervals.

# Create three intervals: [1, 5], [10, 13.5], and [14, 18]
interval = Interval(start=np.array([1.0, 10.0, 14.0]), end=np.array([5.0, 13.5, 18.]))

# Dilate by 0.5 on each side
dilated = interval.dilate(0.5)

# Results in intervals: [0.5, 5.5], [9.5, 13.75], and [13.75, 18.5]
print(dilated.start)  # [0.5 , 9.5 , 13.75]
print(dilated.end)    # [5.5 ,13.75, 18.5 ]

The dilation operation is particularly useful when you need to:

Create buffer periods around events
Account for uncertainty in interval boundaries
Merge intervals that are close together

Coalescing¶

The coalesce operation (.coalesce()) merges overlapping or touching intervals into single continuous intervals. This is useful for simplifying interval sets and removing gaps below a certain threshold.

Visualization of interval coalesce operation

# Create four intervals [1, 6], [6.1, 11], [11.3, 14.5], and [14.5, 17.8]
interval = Interval(
    start=np.array([1., 6.1, 11.3, 14.5]), end=np.array([6., 11., 14.5, 17.8])
)


# Coalesce intervals that are within 0.2 of each other
coalesced = interval.coalesce(0.2)

# [6-6.1] and [14.5-14.5] merged, [11-11.3] unchanged
print(coalesced.start)  # [ 1., 11.3]
print(coalesced.end)    # [11., 17.8]

The coalesce operation is useful for:

Cleaning up noisy interval data
Merging intervals that are effectively continuous
Simplifying interval representations

You can combine coalesce with dilate to merge intervals within a certain distance:

# Create two intervals [1, 2.5], and [3, 4]
interval = Interval(start=np.array([1., 3.]), end=np.array([2.5, 4.]))

# Merge intervals within distance 0.5
merged = interval.dilate(0.5).coalesce()

print(merged.start)  # [0.5]
print(merged.end)    # [4.5]

There are multiple edge cases that can occur when performing interval operations. For more details, see Interval Operations - Edge Cases.