ezmsg.sigproc.util.channels#

Helpers for deriving channel clusters from structured coordinate-axis metadata.

Several sources attach a structured CoordinateAxis to the channel dimension carrying per-channel fields — e.g. ezmsg-blackrock’s ChannelMap emits a ch axis with x/y/size/label/bank/elec/headstage. channel_clusters_from_field turns one such field (bank by default) into the list[list[int]] cluster spec consumed by per-cluster operations like common-average rereferencing and linear-regression rereferencing, so those units can become “bank aware” by reading metadata that already rides on the stream.

Functions

channel_clusters_from_field(message, axis=None, field='bank')[source]#

Group channel indices by a field of a structured coordinate axis.

Parameters:

  • message (AxisArray) – Message whose axis coordinate is a structured CoordinateAxis (its .data is a structured numpy array).

  • axis (str | None) – Channel axis name. None defaults to the last dimension.

  • field (str) – Structured-array field to group by (e.g. "bank").

Returns:

Clusters as a list of index lists, one per distinct field value in first-appearance order. Returns None when the axis carries no usable structured field (no such axis, no .data, unstructured .data, the field is absent, or the per-channel length doesn’t match the data). Returning None rather than a single all-channel cluster lets callers distinguish “no metadata, fall back to my default” from “one bank”.

Return type:

list[list[int]] | None

validate_channel_clusters(clusters, n_channels)[source]#

Raise ValueError if any cluster index falls outside 0..n_channels-1.

An empty clusters list (or empty groups within it) validates trivially; whether an empty spec is permitted at all is caller policy.

Parameters:
Return type:

None