Segment

Shipping

segment

Crop a Signal to a time window [t0, t1] by timestamp (not index), configurable endpoint inclusivity

Signature

Inputs

aSignalrequired— The signal to crop by time. Samples whose timestamp falls inside the window are kept.

Outputs

resultSignal— The cropped signal — a sub-sampling of the input keeping only in-window samples. Unit and sample_rate preserved.

Parameters

Key	Type	Default	Notes
`t0`	float	0.0s	Window start time, in the input's time unit (seconds). Samples below t0 are dropped; the Inclusive setting makes this a ≥ (closed) or > (open) bound.
`t1`	float	1.0s	Window end time, same units as Start. Samples above t1 are dropped. If t1 < t0 the window is empty and an empty signal is emitted (no error).
`inclusive`	enum	both	one of: both, left, right, neither

Description

Segment is the time-domain cousin of an index slice. Where slice cuts on sample number, segment keeps every sample whose timestamp falls inside $[t_{0}, t_{1}]$ (endpoint inclusivity configurable). It is the canonical "crop to a time region of interest" / "gate the acquisition window" tool — e.g. keep only $t \in [1.0 s, 2.5 s]$ of a long capture.

It builds a boolean keep-mask over the timestamp array (numpy values[(t >= t0) & (t <= t1)]) and gathers the surviving samples. Because this is a pure reindexing, values, timestamps and the σ² array are all permuted by the same index map — exact uncertainty propagation (each kept sample carries its own σ²; None stays None). The unit is preserved (cropping never changes dimension), and sample_rate is carried through (a sub-sampling of a uniform axis keeps the rate).

Endpoint inclusivity selects one of four half-open/closed masks: both → $t_{0} \leq t \leq t_{1}$ ; left → $t_{0} \leq t < t_{1}$ ; right → $t_{0} < t \leq t_{1}$ ; neither → $t_{0} < t < t_{1}$ . Edge cases never panic: a reversed window ( $t_{1} < t_{0}$ ), an empty window, or an empty input all yield an empty (but unit/rate-preserving) Signal — robust for an animated or scrubbed window.

Mathematics

keep (t) = (t ≷ t_{0}) \land (t ≶ t_{1})

result = {(t_{i}, x_{i}, σ_{i}^{2}) : keep (t_{i})}

Examples

Closed interval

Timestamps 0..4, t0=1, t1=3, inclusive=both keeps indices 1,2,3 → timestamps [1,2,3], values [11,12,13].

Left-inclusive tiling

t0=1, t1=3, inclusive=left keeps $[1, 3)$ → indices 1,2. Using left lets you tile adjacent windows (…,[1,3),[3,5),…) without double-counting the shared edge.

Empty on reversed window

t0=3, t1=1 (t1 < t0) emits an empty signal with unit and sample_rate preserved — no error, safe for scrubbing.

Applications

Cropping a long acquisition to a time region of interest before analysis.
Gating an event window (e.g. a transient between two trigger times) out of a continuous record.
Tiling a signal into adjacent, non-overlapping time windows using `left`/`right` inclusivity to avoid double edges.
Driving an animated or scrubbed window selection where reversed/out-of-range bounds must degrade gracefully to empty.

Neat

Unlike `slice`, the cut is on the timestamp value, so it stays correct even when the input is non-uniformly sampled or has gaps.

All three arrays (values, timestamps, σ²) are gathered by the identical keep-mask index, so a segmented sample never loses its time coordinate or uncertainty.

Every degenerate case — reversed window, point window with an exclusive endpoint, window outside the data, empty input — returns an empty but well-formed Signal instead of erroring.

Known issues

Only accepts a Signal (it needs a timestamp axis); to crop a Vector by index use `slice` instead.

A σ² array whose length doesn't match values is treated as absent (no uncertainty), rather than indexed into.