ezmsg.sigproc.slicer#

Select a subset of data along a named axis using slice notation.

Functions

parse_slice(s, axinfo=None, field=None, allow_empty=False)[source]#

Parses a string representation of a slice and returns a tuple of slice objects.

“” -> slice(None, None, None) (take all)
“:” -> slice(None, None, None)
‘“none”` (case-insensitive) -> slice(None, None, None)
“{start}:{stop}” or {start}:{stop}:{step} -> slice(start, stop, step)
“5” (or any integer) -> (5,). Take only that item.
applying this to a ndarray or AxisArray will drop the dimension.
A comma-separated list of the above -> a tuple of slices | ints. Per-token results are concatenated in token order, duplicates included; note that SlicerTransformer normalizes the resolved indices per its order setting (deduplicated, and by default sorted into axis order).
A comma-separated list of values and axinfo is provided and is a CoordinateAxis -> a tuple of ints. Each value is first compared against the axis labels for an exact match; failing that, it is treated as a regular expression and full-matched against the labels (e.g. “C[34]” or “Ch.*”). Note: tokens containing “:” are parsed as slices, so regexes may not contain “:”. If the axis .data is a structured array, its “label” field supplies the labels; a structured array without a “label” field supports only integer/slice selections.
If field is provided, tokens are matched against that field of the structured axis data (stringified, so numeric fields like “bank” work). This disables the bare-integer positional fallback: “3” means field value “3”, not index 3. Positional selection remains available via slice syntax (e.g. “3:4”).

Parameters:

s (str) – The string representation of the slice.
axinfo (CoordinateAxis | None) – (Optional) If provided, and of type CoordinateAxis, and s is a comma-separated list of values, then the values in s will be matched (exactly, then as regex) against the values in axinfo.data.
field (str | None) – (Optional) Which field of a structured axinfo.data to match tokens against. None uses the “label” field when present. An explicit field raises ValueError if the axis data is missing, unstructured, or lacks that field.
allow_empty (bool) – (Optional) If True, a label/regex token that matches nothing returns no indices instead of raising. In a comma-separated selection, non-matching tokens are dropped and the matching ones kept; if every token matches nothing the result is an empty tuple.

Returns:

A tuple of slice objects and/or ints. May be empty when allow_empty is True and nothing matched.

Return type:

tuple[slice | int, …]

slicer(selection='', axis=None, field=None, order='axis', on_empty='warn')[source]#

Slice along a particular axis.

Parameters:

selection (str) – See ezmsg.sigproc.slicer.parse_slice for details.
axis (str | None) – The name of the axis to slice along. If None, the last axis is used.
field (str | None) – Which field of a structured coordinate axis to match selection values against. See SlicerSettings for details.
order (str) – “axis” (default) or “selection” — how to order the entries a comma-separated selection resolves to. See SlicerSettings for details.
on_empty (str) – “warn” (default) or “raise” — what to do when a label/regex selection matches nothing. See SlicerSettings for details.

Returns:

SlicerTransformer

Return type:

SlicerTransformer

Classes

class Slicer(*args, settings=None, **kwargs)[source]#

Bases: BaseTransformerUnit[SlicerSettings, AxisArray, AxisArray, SlicerTransformer]

Parameters:: settings (Settings | None)

SETTINGS#: alias of SlicerSettings

class SlicerSettings(selection: str = '', axis: str | None = None, field: str | None = None, order: str = 'axis', on_empty: str = 'warn')[source]#

Bases: Settings

Parameters:

selection (str)
axis (str | None)
field (str | None)
order (str)
on_empty (str)

selection: str = ''#

See ezmsg.sigproc.slicer.parse_slice for details. Label/regex selections always preserve the sliced axis — a single matching entry yields a length-1 axis. Only a bare-integer positional selection (e.g. “5”) drops the dimension. Comma-separated selections are normalized per order: duplicates from overlapping tokens are always removed, and by default the result follows axis order regardless of token order.

Type:: selection

axis: str | None = None#: The name of the axis to slice along. If None, the last axis is used.

field: str | None = None#: Which field of a structured coordinate axis to match selection values against (e.g. “bank”, “elec”). If None, the “label” field is used when present. Setting this explicitly makes selection tokens mean field values only — bare integers are no longer positional indices (use slice syntax like “3:4” for positions) — and raises an error if the axis has no such field.

order: str = 'axis'#

How to order the entries a comma-separated selection resolves to.

“axis” (default): the resolved indices are deduplicated and sorted into axis order — a selection is a filter, so selections naming the same entries in a different token order (e.g. ".*-aip-.*,.*-m1-.*" vs ".*-m1-.*,.*-aip-.*") produce identical output. An info message is logged when this reorders relative to token order.
“selection”: entries follow token order, so a positional selection like “3,1,2” is an intentional permutation.

In both modes duplicate indices from overlapping tokens (e.g. “0:3,1”) are removed — first occurrence wins — with a warning, so a coordinate axis of unique labels stays unique. A single non-comma slice token (e.g. “::-1”) is applied as-is and is not normalized.

on_empty: str = 'warn'#

What to do when a label/regex selection matches nothing on the target axis.

“warn” (default): non-matching tokens are dropped (logged at info level); if the whole selection matches nothing, the output is empty (0-length along axis) and a warning is logged once per stream configuration. This lets a selection be broadcast to streams that may legitimately contain none of the selected entries (e.g. a per-source region selection where a given source carries none of the requested regions).
“raise”: raise a ValueError when any token matches nothing, which catches typos and wrong-axis mistakes at first message.

__init__(selection='', axis=None, field=None, order='axis', on_empty='warn')#

Parameters:

selection (str)
axis (str | None)
field (str | None)
order (str)
on_empty (str)

Return type:

None

class SlicerState[source]#

Bases: object

slice_: slice | int | ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None#

new_axis: AxisBase | None = None#

b_change_dims: bool = False#

class SlicerTransformer(*args, **kwargs)[source]#

Bases: BaseStatefulTransformer[SlicerSettings, AxisArray, AxisArray, SlicerState]