API Reference

EventIntervals

Interval-aware data structures for point processes. Couples timestamped event collections (Points) with the temporal domains (Interval) they are defined on, so that slicing, intersecting, downsampling, and transforming operations keep points and their intervals in sync.

Core types come in "naked" (coordinates only) and "marked" (coordinates + metadata) variants: NakedPoint/MarkedPoint, NakedInterval/MarkedInterval, NakedPoints/VariablePoints. SubPoints provides lazy, zero-copy views into any points collection.

Interval{E,N}

Abstract supertype for interval types, parameterised by the element type E and dimensionality N. All concrete subtypes must implement bounds returning an NTuple{2,E}.

Supports in membership testing, measure, midpoint, bounds, and nakedinterval.

IntervalSet{E,T} <: Interval{E,1}

A composite interval formed from a tuple of contiguous, ordered sub-intervals. Behaves as a single interval whose bounds span from the start of the first component to the end of the last.

Constructors

IntervalSet(i1::Interval, i2::Interval, ...)
IntervalSet(intervals::AbstractVector{<:Interval})
IntervalSet(intervals::NTuple{N,Interval})

Throws ArgumentError if the intervals are not contiguous (each must start where the previous one ends) or if the collection is empty.

See also get_mark.

MarkedInterval{D<:Number,M} <: Interval{D,1}

An interval with attached metadata of type M. The mark can be any type.

Constructors

MarkedInterval(interval::NakedInterval, mark)
MarkedInterval((a, b), mark)
MarkedInterval(a, b, mark)

See also get_mark, nakedinterval.

MarkedPoint{E,M} <: Point{E}

A timestamp of type E paired with a mark of type M. Marks can be any type — numbers, symbols, tuples, or custom structs.

See also push_mark, pop_mark.

MarkedPoints{E,N,I,M}

Type alias for Points{E,N,I,MarkedPoint{E,M}} — any Points collection whose elements are MarkedPoint values.

NakedInterval{D<:Number} <: Interval{D,1}

A plain interval storing (start, stop) bounds with no metadata. The fundamental interval type in EventIntervals.

Constructors

NakedInterval((a, b))
NakedInterval(a, b)

Arguments are promoted to a common numeric type.

NakedPoint{E} <: Point{E}

A bare timestamp with no metadata. Wraps a single value of type E.

NakedPoints{E,I,A} <: Points{E,1,I,NakedPoint{E}}

A sorted vector of timestamps of type E defined on an interval of type I. Points need not be strictly increasing, but must be non-decreasingly sorted.

Constructors

NakedPoints(points::AbstractVector{E}, interval::Interval{E})
NakedPoints(points::AbstractVector{E}, (a, b))
NakedPoints(points::AbstractVector{E}, a, b)
NakedPoints(points::AbstractVector)

The first three forms accept an explicit interval; unsorted input is sorted in-place. The last form infers the interval from (minimum(points), maximum(points)) and requires a non-empty vector.

Throws ArgumentError if points fall outside the given interval.

Point{E}

Abstract supertype for timestamped event types, parameterised by the element type E of the timestamp. Concrete subtypes are NakedPoint and MarkedPoint.

Point values support isless comparison with Number values, delegating to nakedpointvalue.

Points{E,N,I<:Interval{E},T<:Point{E}} <: AbstractVector{T}

Abstract supertype for read-only collections of Point values defined on an Interval. Subtypes are NakedPoints, VariablePoints, and SubPoints.

Points implements AbstractVector, so indexing, iteration, and length work as expected. Assignment via setindex! throws ReadOnlyMemoryError.

RelativeInterval{D,I,J} <: Interval{D,1}

An interval expressed in coordinates relative to a reference interval. Useful for defining peri-event windows (e.g. "100 ms before to 300 ms after stimulus onset").

RelativeInterval(reference::Interval, anchored_left::Bool, offset::Interval)

If anchored_left is true, offsets are relative to the start of reference; if false, relative to the end.

bounds resolves to absolute coordinates by adding the anchor point.

SubPoints{E,M,I,P} <: Points{E,1,I,M}

A lazy, zero-copy view of a Points collection restricted to a sub-interval. Indexing uses a precomputed offset for O(1) element access.

Constructors

SubPoints(points::Points, interval::Interval)
SubPoints(points::Points, (a, b))
SubPoints(points::Points, a, b)

The sub-interval must be contained within interval(points) (throws ArgumentError otherwise). Nesting SubPoints inside another SubPoints flattens automatically, referencing the original underlying data.

See also maybe_subpoints.

VariablePoints{E,I,P,M,A} <: Points{E,1,I,MarkedPoint{E,M}}

A sorted collection of timestamps paired with per-point marks of type M. Wraps a NakedPoints for the timestamps and a separate marks vector.

Constructors

VariablePoints(nakedpoints::NakedPoints, marks::AbstractVector)
VariablePoints(points::AbstractVector, marks::AbstractVector, interval_args...)
VariablePoints(pts::AbstractVector{<:MarkedPoint}, interval_args...)

The second form sorts points and permutes marks to match. The third form destructures MarkedPoint elements. All forms require length(points) == length(marks).

See also get_mark, point_values.

bounds(m::Interval) -> NTuple{2,E}
bounds(p::Points) -> NTuple{2,E}

Return the (start, stop) bounds of an interval or points collection.

chunk(int::Interval{E,1}, chunk_len::E, exact::Bool=false) where E -> Vector{NakedInterval{E}}

Break int into consecutive sub-intervals of length chunk_len. If exact is true, any trailing remainder shorter than chunk_len is dropped; otherwise it is included as the final chunk.

chunk_len must be positive (throws ArgumentError otherwise).

chunk(intervals::AbstractVector{<:Interval{E,1}}, chunk_len::E, exact::Bool=true) where E

Apply chunking to each interval in the vector and concatenate the results.

complement(dom::Interval, int::Interval) -> Vector{NakedInterval}
complement(dom::Interval, ints::AbstractVector{<:Interval}) -> Vector{NakedInterval}

Return the portions of dom not covered by int (or by any interval in ints). The vector form requires ints to be sorted by start time.

get_mark(m::MarkedInterval)
get_mark(iset::IntervalSet)
get_mark(vp::VariablePoints)
get_mark(sp::SubPoints)

Retrieve the mark from a marked object. For an IntervalSet, returns the mark of the first MarkedInterval component. For VariablePoints or marked SubPoints, returns the marks vector.

Throws an error if no mark is found.

interval(p::Points) -> Interval

Return the domain interval on which the points collection is defined.

interval_intersections_subpoints(points::AbstractVector{<:Points}, intervals::AbstractVector{<:Interval}) -> Vector{SubPoints}

For each overlap between a points collection in points and an interval in intervals, produce a SubPoints view. Both inputs must be sorted by start time.

This is the lower-level function behind points_intersects.

interval_levels(intervals::AbstractVector{<:Interval{E,1}}) where E -> Vector{MarkedInterval{E,Int}}

Partition the time axis into segments labelled by the depth of interval overlap. Returns a vector of MarkedInterval where each mark is the number of input intervals overlapping that segment.

intervals must be sorted by start time and non-empty (throws ArgumentError otherwise).

join_points(pt::Points) -> NakedPoints or VariablePoints
join_points(pt1::Points, pt2::Points, pts::Points...) -> NakedPoints or VariablePoints

Materialise or merge point collections. The single-argument form copies a (possibly lazy) Points into a concrete NakedPoints or VariablePoints. The multi-argument form concatenates points and sorts the result; the output interval is the union of all input intervals. All arguments must have the same point type (all naked or all marked).

maybe_subpoints(points::Points, i::Interval) -> SubPoints or nothing

Return a SubPoints view if i overlaps with the domain of points, or nothing if there is no intersection.

nakedinterval(i::Interval) -> NakedInterval
nakedinterval(p::Points) -> NakedInterval

Strip any mark or wrapper to obtain a plain NakedInterval. Identity on NakedInterval inputs.

nakedpoints(p::Points) -> NakedPoints

Extract or return the underlying NakedPoints (timestamps only, no marks). Identity on NakedPoints inputs. For SubPoints, materialises a new NakedPoints covering the sub-interval.

nakedpointvalue(pt::Point) -> E

Return the raw timestamp value from a Point.

nakedvalues(p::Points) -> AbstractVector
nakedvalues(p::Points, b, e) -> AbstractVector

Return the raw timestamp values from a points collection, stripping any marks. Equivalent to point_values(nakedpoints(p), ...).

point_values(pts)

Extract the underlying value arrays from a collection of points.

For a vector of NakedPoint, returns a vector of timestamps. For a vector of MarkedPoint, returns (timestamps, marks). For Points subtypes, see NakedPoints, VariablePoints, and SubPoints for range-query forms point_values(pts, b, e).

points(p::Points, [b, e]) -> Vector{<:Point}

Materialise the Point objects from a points collection. The optional range [b, e] restricts to points within those bounds.

points_intersects(pts1::AbstractVector{<:Points}, pts2::AbstractVector{<:Points}) -> (Vector{SubPoints}, Vector{SubPoints})

Restrict two vectors of Points to only the time ranges where both have coverage. Returns a pair of SubPoints vectors aligned to the same intersection intervals. Both inputs must be sorted by start time.

See also interval_intersections_subpoints.

pop_mark(mp::MarkedPoint{<:Any,<:Tuple}) -> (MarkedPoint, mark)

Remove the outermost mark from a tuple-marked MarkedPoint, returning the modified point and the removed mark. If the mark tuple is empty, returns (mp, nothing).

See also push_mark, pop_marks.

pop_marks(p::VariablePoints) -> VariablePoints

Strip the outermost element from tuple marks on all points. Each mark (a, b) becomes b. This is the collection-level counterpart of pop_mark and is useful for removing the merge-count mark added by pp_downsamp.

pp_downsamp(p::Points, b, e, resolution, [merge_func=pt_merge], [RetType=M]) -> VariablePoints

Downsample points within [b, e] by merging consecutive points closer than resolution. Adjacent points whose gap is less than resolution are merged using merge_func. Each merged point receives a count mark (via push_mark) recording how many original points were combined.

The default merge_func is pt_merge (mean of timestamps and marks). RetType specifies the element type returned by merge_func for type stability; it defaults to M, the point element type of the input collection.

See also pt_merge, pt_extent_merge, pop_marks.

pt_extent_merge(pts::AbstractVector{<:MarkedPoint}) -> MarkedPoint
pt_extent_merge(pts::AbstractVector{<:NakedPoint}) -> MarkedPoint

Merge a group of points by averaging timestamps and recording the extent (min, max). For MarkedPoint inputs, returns MarkedPoint(mean_time, ((min_time, max_time), mean_mark)). For NakedPoint inputs, returns MarkedPoint(mean_time, (min_time, max_time)).

Alternative merge function for pp_downsamp.

pt_merge(pts::AbstractVector{<:NakedPoint}) -> NakedPoint
pt_merge(pts::AbstractVector{<:MarkedPoint}) -> MarkedPoint

Merge a group of points by averaging their timestamps (and marks, for MarkedPoint). Used as the default merge function in pp_downsamp.

push_mark(p::NakedPoint, mark) -> MarkedPoint
push_mark(mp::MarkedPoint, newmark) -> MarkedPoint

Add a mark to a point. On a NakedPoint, creates a MarkedPoint. On a MarkedPoint, nests the new mark into a tuple (newmark, existing_mark), forming a mark stack.

See also pop_mark.

rate(p::Points) -> Number
rate(p::Points, b, e) -> Number
rate(ps::AbstractVector{<:Points}) -> Number or nothing

Compute the event rate (count / duration). The two-argument form restricts the calculation to the range [b, e]. The vector form computes the aggregate rate across all collections, returning nothing if the vector is empty.

shift_interval(a::Interval, offset::Number) -> Interval
shift_interval(offset::Number) -> Function

Translate an interval by adding offset to both bounds. Preserves the mark on a MarkedInterval. The single-argument form returns a curried function.

shrink(int::Interval, shrink_measure) -> Interval
shrink(ints::AbstractVector{<:Interval}, shrink_measure) -> Vector

Contract an interval inward by shrink_measure / 2 from each end. If shrink_measure exceeds the interval's measure, the result is a zero-width interval at the midpoint.

The vector form drops any intervals whose measure is less than shrink_measure before shrinking the survivors.

subinterval(int::Interval{E,1}, b::Real, e::Real) -> Interval
subinterval(int::Interval{E,1}, sub::NakedInterval{E}) -> Interval

Return the portion of int delimited by [b, e]. Preserves the type and mark of int (e.g. a MarkedInterval yields a MarkedInterval with the same mark).

Throws ArgumentError if [b, e] is not contained within int.

translate(p::NakedPoints, offset) -> NakedPoints
translate(p::VariablePoints, offset) -> VariablePoints

Shift all timestamps and the domain interval by offset. Marks are preserved.

duration(p::Points) -> Number

Return the duration (measure) of the domain interval. Equivalent to measure(interval(p)).

time_interval(p::Points) -> Interval

Return the domain interval. Synonym for interval.

check_overlap(m::Interval, n::Interval) -> Bool

Return true if intervals m and n overlap (share at least one point).

interval_indices(basis, i::Interval)
interval_indices(basis, a::AbstractVector{<:Interval})

Return the indices into basis that fall within interval i. The vector form maps over each interval independently.

interval_intersect(a::Interval, b::Interval) -> NakedInterval or nothing

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

interval_intersections(a::AbstractVector{<:Interval}, b::AbstractVector{<:Interval}) -> Vector{NakedInterval}

Compute all pairwise intersections between two sorted vectors of intervals. Both a and b must be sorted by start time.

intervals_diff(a::AbstractVector{<:Interval}, b) -> Vector{NakedInterval}
intervals_diff(a, b::AbstractVector{<:Interval}) -> Vector{NakedInterval}

Compute the set difference of two sorted interval vectors: the portions of a not covered by b. Accepts Interval objects or NTuple{2} bounds in either argument position.

is_subinterval(m::Interval, parent::Interval) -> Bool

Return true if m is entirely contained within parent (inclusive bounds).

mask_events(evts, i::Interval)

Filter a sorted event vector to only those falling within interval i. Delegates to SortedIntervals.mask_events(evts, b, e).

maximum_interval_overlap(xs::AbstractVector{<:Interval}, y::Interval) -> Number

Return the maximum overlap (in measure) between any single interval in xs and the interval y.

measure(m::Interval)
measure(m::IntervalSet)
measure(p::Points)

Return the length (duration) of an interval. For an IntervalSet, returns the sum of the component measures. For a Points collection, returns the measure of its underlying interval.

midpoint(m::Interval)

Return the midpoint of the interval (b + e) / 2.

relative_interval(interval, reference) -> NakedInterval

Express interval in coordinates relative to reference by subtracting the reference start from both bounds. Either argument may be an Interval or an NTuple{2,<:Number}.