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

  • 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, 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.

  • 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, on_empty: str = 'warn')[source]#

Bases: Settings

Parameters:

  • selection (str)

  • axis (str | None)

  • field (str | None)

  • 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.

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.

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, on_empty='warn')#
Parameters:

  • selection (str)

  • axis (str | None)

  • field (str | None)

  • 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]