Index / Gather

Shipping

gather_index

numpy fancy indexing arr[i] / arr[[i,j,k]] over a Signal or Vector; single→Scalar, list→series

Signature

Inputs

aSignal|Vectorrequired— The signal or vector to gather from by explicit integer positions.

Outputs

resultScalar|Signal|Vector— A Scalar (single mode) or a shorter/reordered/duplicated Signal or Vector (list mode), shape-matched to the input variant.

Parameters

Key	Type	Default	Notes
`mode`	enum	list	one of: single, list
`indices`	text	0	Comma-separated integer positions, numpy fancy-indexing style (e.g. `0, 2, -1`). Negatives count from the end (-1 = last). Order is preserved and duplicates are allowed, so this both selects and reorders. An out-of-range index is a hard error — never silently clamped. Empty list in List mode yields an empty output.

Description

Index / Gather reindexes a Signal or Vector by an explicit, user-authored list of integer positions — the engine-side equivalent of numpy fancy indexing:

arr = [10, 20, 30, 40]
arr[2]          -> 30           (single  → Scalar)
arr[[0, 2, -1]] -> [10, 30, 40] (list    → shorter series)
arr[[-1, -2]]   -> [40, 30]     (reverse / negatives from end)

numpy semantics are EXACT: a negative index $- k$ resolves to $len + (- k)$ ; anything outside $[- len, len - 1]$ is an honest error, never a silent clamp (a bad index surfaces before any partial output is produced). single mode reads indices[0] (extra indices ignored) and yields a Scalar carrying that sample's value, unit and σ². list mode is a pure permutation/selection: it reads the source at each resolved position in order, so duplicates, reversal and arbitrary reordering all behave like numpy; the result may be empty, shorter, or longer than the input (duplicated indices).

Gathering is a pure permutation of samples, so uncertainty propagation is exact: each output sample carries the σ² of the same source sample it copied, and — for a Signal — the timestamp of that source sample too. None variances stay None. The unit is preserved verbatim. A list-mode Signal's sample_rate is dropped to 0 because arbitrary gathering destroys uniform sampling — the gathered timestamps become the time-axis source of truth.

Mathematics

single: out = x [resolve (i_{0})], resolve (i) = i < 0 ? i + n : i

list: out [k] = x [resolve (i_{k})] for each k

Examples

Single element to Scalar

mode=single, indices=2 on [10,20,30,40] (unit V) → Scalar 30 V, carrying the source sample's σ² if present.

List gather with negatives

mode=list, indices="0, 2, -1" on values [10,20,30,40] with ts [0,10,20,30] and σ² [.1,.2,.3,.4] → values [10,30,40], ts [0,20,30], σ² [.1,.3,.4]. sample_rate is cleared (non-uniform gather).

Reverse via negative indices

indices="-1, -2, -3, -4" reverses [10,20,30,40] → [40,30,20,10], with timestamps reversing in lock-step.

Duplicates grow the output

indices="0, 0, 1" on [10,20] → [10,10,20] — numpy permits repeated indices, so the output can be longer than the input.

Applications

Extracting a specific sample as a Scalar (e.g. the value at a detected peak index) for a numeric readout.
Reordering, reversing, or subsetting a series by an explicit index list computed elsewhere.
Building a repeated / bootstrap-style resampling by duplicating indices.
Selecting a handful of channels or samples by position with negative-from-end addressing.

Neat

The full resolved index map is built up front, so a single out-of-range index fails the whole gather — matching numpy, which raises before producing a partial array.

Because gather is a permutation, list mode can produce an output longer than the input (via duplicates), shorter (via subset), or the same length reordered — all three are legal numpy.

A list-mode Signal honestly clears its sample_rate: the gathered (possibly non-uniform) timestamps become the single source of truth, so no stale uniform rate is advertised.

Known issues

Single mode on a Vector yields an exact Scalar (variance None) because a Vector has no per-element σ² field.

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

Out-of-range indices are hard errors by design — clamp or wrap upstream if you need tolerant addressing.