API Reference

check_overlap(start1, stop1, start2, stop2) -> Bool
check_overlap(a::NTuple{2,<:Number}, b::NTuple{2,<:Number}) -> Bool
check_overlap(intervals::AbstractVector{<:NTuple{2}}) -> Bool

Test whether two intervals overlap, or whether any pair of intervals in a vector overlaps.

Intervals are treated as closed (endpoints are included).

clip_int(int_begin, int_end, bound_begin, bound_end) -> NTuple{2}
clip_int(input::NTuple{2,<:Number}, bounds::NTuple{2,<:Number}) -> NTuple{2}

Clamp an interval to lie within the given bounds. Each endpoint is clamped independently.

clip_interval_duration(reqb, reqe, boundmin, boundmax) -> NTuple{2}
clip_interval_duration(int::NTuple{2}, bounds::NTuple{2}) -> NTuple{2}

Clip an interval to lie within [boundmin, boundmax] while attempting to preserve its duration. The interval is shifted to fit within the bounds when possible. If the requested interval is longer than the bounds, it is clamped to exactly [boundmin, boundmax].

Examples

julia> clip_interval_duration(8, 12, 0, 10)
(6, 10)

julia> clip_interval_duration(-2, 5, 0, 10)
(0, 7)

clipsize!(a::AbstractVector, n::Integer) -> AbstractVector

Resize a to length n and release excess memory capacity.

expand_intervals!(ints_in::AbstractVector{<:NTuple{2,<:Number}}, expand::Number) -> AbstractVector

Expand each interval by expand / 2 on each side, then merge any resulting overlaps. Mutates and resizes ints_in in-place.

See expand_intervals for a non-mutating version.

Examples

julia> ints = [(2, 4), (8, 10)];

julia> expand_intervals!(ints, 2)
2-element Vector{Tuple{Int64, Int64}}:
 (1, 5)
 (7, 11)

expand_intervals(ints_in, expand::Number) -> Vector

Non-mutating version of expand_intervals!.

extrema_red(a::AbstractVector{<:Number}) -> NTuple{2}
extrema_red(a::AbstractArray{<:Number, 2}) -> NTuple{2}
extrema_red(a::AbstractVector{<:NTuple{2,Number}}) -> NTuple{2}

Return the overall (minimum, maximum) across a collection of intervals or numbers.

For a vector of numbers, equivalent to extrema. For a 2×N matrix, treats each column as an interval. For a vector of 2-tuples, finds the global minimum start and maximum stop.

find_all_overlapping(intsa, intsb) -> BitVector
find_all_overlapping(fa, fb, intsa, intsb) -> BitVector

Return a BitVector of length length(intsa) indicating which intervals in intsa overlap with any interval in intsb. Optional accessor functions fa and fb extract (start, stop) tuples from each element.

Both inputs must be sorted and non-overlapping (see intervals_are_ordered).

Examples

julia> find_all_overlapping([(1, 3), (5, 7), (10, 12)], [(2, 6)])
3-element BitVector:
 1
 1
 0

find_overlaps(intervals::AbstractVector{<:Tuple{<:Any,<:Any}}) -> Vector{Vector{Int}}

Find all pairwise overlaps in a vector of intervals. Returns a vector of index lists, where result[i] contains the indices of all intervals that overlap with interval i.

Assumes intervals is sorted by start time.

Examples

julia> find_overlaps([(1, 5), (3, 7), (8, 10)])
3-element Vector{Vector{Int64}}:
 [2]
 [1]
 []

interval_complements(start, stop, intervals, contraction=0) -> Vector{NTuple{2}}

Find the gaps between intervals within the bounding interval [start, stop]. Each complement boundary is contracted inward by contraction (useful for excluding edge artifacts).

Assumes intervals is sorted and non-overlapping.

Examples

julia> interval_complements(0, 10, [(2, 4), (6, 8)])
3-element Vector{Tuple{Int64, Int64}}:
 (0, 2)
 (4, 6)
 (8, 10)

interval_indices(basis, start::Number, stop::Number) -> (i_b, i_e)
interval_indices(basis, bounds::NTuple{2,<:Number}) -> (i_b, i_e)

Find the first and last indices in the sorted collection basis whose values fall within [start, stop]. Uses binary search (searchsortedfirst / searchsortedlast).

interval_intersect(start1, stop1, start2, stop2) -> NTuple{2} | Nothing
interval_intersect(a::NTuple{2}, b::NTuple{2}) -> NTuple{2} | Nothing

Return the intersection of two intervals, or nothing if they do not overlap.

interval_intersect_measure(start1, stop1, start2, stop2) -> Number
interval_intersect_measure(a::NTuple{2}, b::NTuple{2}) -> Number

Return the length of the intersection of two intervals, or zero if they do not overlap.

interval_intersections(intsa, intsb) -> Vector{NTuple{2}}

Compute all pairwise intersections between two collections of intervals. Both inputs must be sorted and non-overlapping (see intervals_are_ordered). Returns a sorted, non-overlapping vector of intersection intervals.

See also interval_intersections_overlapping for inputs that may contain overlaps.

Examples

julia> interval_intersections([(1, 5), (7, 10)], [(3, 8)])
2-element Vector{Tuple{Int64, Int64}}:
 (3, 5)
 (7, 8)

interval_intersections_overlapping(intsa, intsb) -> Vector{NTuple{2}}

Like interval_intersections, but allows the input interval lists to contain overlapping intervals. Both inputs must still be sorted by start time (see intervals_are_partially_ordered). Overlapping results are merged.

intervals_are_ordered(ints) -> Bool
intervals_are_ordered(f, ints) -> Bool

Check that each interval is well-formed (start <= stop), intervals are sorted by start time, and no intervals overlap. An optional accessor function f extracts (start, stop) from each element.

See also intervals_are_partially_ordered.

Examples

julia> intervals_are_ordered([(1, 3), (4, 6), (7, 9)])
true

julia> intervals_are_ordered([(1, 5), (3, 7)])
false

intervals_are_partially_ordered(ints) -> Bool
intervals_are_partially_ordered(f, ints) -> Bool

Check that each interval is well-formed and intervals are sorted by start time. Unlike intervals_are_ordered, overlapping intervals are permitted.

Examples

julia> intervals_are_partially_ordered([(1, 5), (3, 7)])
true

julia> intervals_are_partially_ordered([(3, 7), (1, 5)])
false

intervals_diff(ints_a, ints_b) -> Vector{NTuple{2}}

Compute the set difference of two sorted interval collections: the portions of ints_a that are not covered by any interval in ints_b. Both inputs must be sorted and non-overlapping.

Examples

julia> intervals_diff([(1, 10)], [(3, 5), (7, 8)])
3-element Vector{Tuple{Int64, Int64}}:
 (1, 3)
 (5, 7)
 (8, 10)

is_subinterval(startchild, stopchild, startparent, stopparent) -> Bool
is_subinterval(child::NTuple{2,<:Number}, parent::NTuple{2,<:Number}) -> Bool

Test whether the child interval is entirely contained within the parent interval.

join_intervals!(ints::AbstractVector{<:NTuple{2,<:Number}}, min_gap=0) -> AbstractVector
join_intervals!(f, ints::AbstractVector{<:NTuple{2,<:Number}}, min_gap=0) -> AbstractVector

Merge successive intervals in the sorted vector ints when the gap between them is at most min_gap. Mutates and resizes ints in-place. An optional function f is applied to each merged interval before storing.

Assumes ints is sorted by start time. See join_intervals for a non-mutating version.

Examples

julia> ints = [(1, 3), (4, 6), (10, 12)];

julia> join_intervals!(ints, 1)
2-element Vector{Tuple{Int64, Int64}}:
 (1, 6)
 (10, 12)

join_intervals(ints::AbstractVector{<:NTuple{2,<:Number}}, min_gap=0) -> Vector
join_intervals(f, ints::AbstractVector{<:NTuple{2,<:Number}}, min_gap=0) -> Vector

Non-mutating version of join_intervals!. Returns a new vector with successive intervals merged when the gap between them is at most min_gap.

Examples

julia> join_intervals([(1, 3), (4, 6), (10, 12)], 1)
2-element Vector{Tuple{Int64, Int64}}:
 (1, 6)
 (10, 12)

mask_events(event_times::AbstractVector{<:Number}, start, stop) -> SubArray

Return a view of event_times containing only elements within [start, stop]. Uses binary search via interval_indices. Assumes event_times is sorted.

maximum_interval_overlap(xs::AbstractVector{NTuple{2,T}}, y::NTuple{2,T}) -> (index, overlap)

Find the interval in xs that has the greatest overlap with the target interval y. Returns the index of the best-matching interval and the overlap measure. Returns (0, typemin(T)) if xs is empty.

measure(a::NTuple{2,<:Number}) -> Number
measure(::Nothing) -> Int

Return the length (duration) of an interval a, i.e. a[2] - a[1]. Returns 0 for nothing, which is useful when chained with interval_intersect.

measure_to_bounds(start::Number, duration::Number) -> NTuple{2}
measure_to_bounds(t::NTuple{2}) -> NTuple{2}
measure_to_bounds(ts::AbstractArray{<:NTuple{2}}) -> AbstractArray
measure_to_bounds(starts::AbstractArray, durations::AbstractArray) -> AbstractArray

Convert a (start, duration) representation to a (start, stop) representation, where stop = start + duration.

midpoint(a::NTuple{2,<:Number}) -> Number

Return the midpoint of an interval a.

overlap_interval_union(a::NTuple{2}, b::NTuple{2}) -> NTuple{2}
overlap_interval_union(ab, ae, bb, be) -> NTuple{2}

Return the bounding interval that covers both a and b. The inputs are assumed to overlap; if they don't, the result spans the gap between them.

parse_ranges_str(s::AbstractString) -> Vector{Int}

Parse a comma-separated string of integers and integer ranges into a sorted vector of unique integers. Ranges are specified with hyphens.

Examples

julia> parse_ranges_str("1-3, 7, 10-12")
7-element Vector{Int64}:
  1
  2
  3
  7
 10
 11
 12

reduce_extrema(a::NTuple{2,T}, b::NTuple{2,T}) -> NTuple{2,T}
reduce_extrema(s1, s2, t1, t2) -> NTuple{2}

Return (min(a[1], b[1]), max(a[2], b[2])) — the bounding interval that contains both input intervals. Useful as a reduction operator over a collection of intervals.

relative_interval(interval, reference) -> NTuple{2}
relative_interval(int_begin, int_end, ref_begin, ref_end) -> NTuple{2}

Express interval in coordinates relative to reference, clamped to (0, measure(reference)). Equivalent to shifting interval so that ref_begin maps to zero, then clipping to the reference duration.

throttle(xs::AbstractVector{T}, min_gap::Number) -> Vector{NTuple{2,T}} where T<:Number

Group sorted points into intervals by merging consecutive points that are within min_gap of each other. Each output interval spans from the first to last point in its group.

Assumes xs is sorted.

Examples

julia> throttle([1, 2, 3, 10, 11, 20], 2)
3-element Vector{Tuple{Int64, Int64}}:
 (1, 3)
 (10, 11)
 (20, 20)