Slice

Shipping

slice

numpy basic slicing arr[start:stop:step] over Signal / Vector / Matrix, with n-D multi-axis spec

Signature

Inputs

aSignal|Vector|Matrix|Tensor|DataFramerequired— The value to slice. Single-axis params handle Signal/Vector/Matrix; the multi-axis `spec` drives every axis of an n-D Array (or DataFrame).

Outputs

resultSignal|Vector|Matrix|Tensor|DataFrame— The selected (and possibly re-ordered) subset, same variant as the input.

Parameters

Key	Type	Default	Notes
`spec`	text		Multi-axis numpy slice — one `start:stop:step` per axis, comma-separated (e.g. `1:5, 2:20:3, ::2, -5:`). A bare `i` selects one index; `...` fills remaining axes with a full `:`. When set, this drives EVERY axis of an n-D Array (or 1-D Signal) and supersedes the single-axis params. Empty = use them.
`start`	text		Start index (numpy `start`). Empty = from the beginning. Negative counts from the end (-1 = last). With a negative Step, empty means start at the last element.
`stop`	text		Stop index, EXCLUSIVE (numpy `stop`). Empty = to the end. Negative counts from the end. With a negative Step, empty means go down to and including index 0.
`step`	text		Stride between picked samples (numpy `step`). Empty = 1. Use 2/3/… to decimate, -1 to reverse, -k to reverse + decimate. Zero is rejected.
`axis`	enum	rows	one of: rows, cols, flat

Description

Slice is a pure reindexing node implementing EXACT numpy basic-slicing semantics: it never invents samples — it selects (and re-orders) the ones already there. Because every output sample IS a source sample, propagation is exact for all carried metadata.

Signal — timestamps, values and the σ² array are permuted by the same index list, so a sliced sample keeps its own time coordinate and uncertainty (None stays None). The unit is preserved. sample_rate is kept when the step is $\pm 1$ (uniform spacing intact) and otherwise cleared to $0.0$ — a decimated/reversed signal is no longer uniformly sampled, so downstream falls back to the exact timestamps.
Vector — data reindexed, unit preserved.
Matrix — an axis enum chooses rows (slice the row index, keep all columns), cols (slice columns, keep all rows), or flat (slice the flattened row-major buffer → a 1×k row matrix).

The index resolution mirrors CPython's PySlice_GetIndicesEx: step defaults to 1 and must not be 0 (numpy raises); negative bounds count from the end; defaults depend on the step's sign; resolved bounds are clamped; an empty result is valid (never a panic). This covers reverse (step=-1), head (stop=n), tail (start=-n), decimate (step=k), drop-first (start=1).

The `spec` field unlocks full n-D basic slicing — one start:stop:step per axis, ... for an ellipsis fill, a bare i for a single index — reusing the same proven index core across every rank, and also slicing DataFrames as rows, cols.

Mathematics

step > 0 : i \in {s, s + step, \dots} while i < e, s = 0, e = n by default

step < 0 : i \in {s, s + step, \dots} while i > e, s = n - 1, e = - 1 by default

Examples

Reverse a signal

step = -1 reverses [10,20,30,40] → [40,30,20,10]; the timestamps are permuted by the same map (sample_rate is kept, since $\pm 1$ stays uniform).

Decimate by 2

step = 2 on [0,1,2,3,4,5] → [0,2,4]. The uniform rate is cleared to 0 (no longer uniformly sampled at the original $F_{s}$ ) and the exact timestamps 0,1,2 (×dt) are kept.

Head / tail

stop = 3 keeps the first three samples; start = -2 keeps the last two.

Matrix by column

axis = cols, step = 2 on a 3×3 matrix keeps columns 0 and 2 of every row → a 3×2 matrix.

n-D spec

spec = "1:3, 0:2" on a 3×4 matrix selects rows {1,2} × cols {0,1} → [[4,5],[8,9]]. spec = "..., ::-1" reverses only the last axis of any-rank array.

Applications

Trimming a signal to a region of interest by sample index (head/tail/window).
Down-sampling / decimating a series by taking every k-th sample.
Reversing a waveform, or reverse-decimating with a negative step.
Selecting sub-blocks of a matrix or tensor (rows, columns, or arbitrary n-D windows) for focused processing.

Neat

The index core is a faithful port of CPython's `PySlice_GetIndicesEx`, so every corner case (negative bounds, out-of-range clamping, empty results) matches numpy bit-for-bit.

A single index list drives values, timestamps AND σ² for the Signal path, so a reversed or decimated slice keeps each sample married to its own time and uncertainty.

The multi-axis `spec` reuses the exact same single-axis resolver per axis, then does one n-D row-major cartesian gather — one proven core, every rank.

`sample_rate` is honestly cleared on any non-±1 step because the signal is no longer uniformly sampled; the retained exact timestamps become the single source of truth.

Known issues

A `step = 0` is a hard error (matching numpy's ValueError).

Multi-axis `spec` slicing of complex arrays is not yet supported (an explicit error).

A single-index axis in `spec` is kept as a length-1 axis (no axis-drop yet), unlike numpy which drops it.