ezmsg.sigproc.util.rereference#

Deterministic rereferencing schemes expressed as affine weight matrices.

These helpers build weight matrices for deterministic, cluster-aware rereferencing — identity passthrough and per-cluster common-average reference (CAR) — suitable for ezmsg.sigproc.affinetransform.AffineTransformTransformer (y = x @ A). All returned matrices are symmetric, so the right_multiply orientation does not matter.

Matrices are built with numpy: AffineTransformTransformer converts its weights to the message’s array namespace, dtype, and device on first use, so a host-side float64 matrix is the correct interchange format even for GPU-backed streams.

The matrix form of mean-CAR is equivalent to the streaming ezmsg.sigproc.affinetransform.CommonRereferenceTransformer with mode="mean". The streaming form is cheaper per sample (mean subtraction vs. matmul) and also supports median; the matrix form composes with other affine transforms and provides a deterministic cold-start for adaptive rereferencing (e.g. LRR in ezmsg-learn).

Functions

car_matrix(n_channels, *, clusters=None, include_current=True, min_reref_size=1, dtype=<class 'numpy.float64'>)[source]#

Build a per-cluster common-average-reference matrix.

Within each cluster of k channels the sub-block subtracts the cluster mean: y_i = x_i - mean_j x_j (include_current=True), or the leave-one-out mean y_i = x_i - mean_{j != i} x_j (include_current=False). Channels outside every cluster — and all cross-cluster terms — stay identity.

Parameters:

  • n_channels (int) – Total number of channels (matrix is n x n).

  • clusters (list[list[int]] | None) – Disjoint channel-index groups, e.g. from ezmsg.sigproc.util.channels.channel_clusters_from_field(). None treats all channels as a single cluster.

  • include_current (bool) – Set False for the leave-one-out reference (each channel excluded from its own reference).

  • min_reref_size (int) – Clusters with fewer channels than this stay identity. Note this is distinct from min_cluster_size, which is a block-diagonal matmul merge threshold.

  • dtype (DTypeLike) – Result dtype; must be floating-point.

Returns:

Symmetric (n_channels, n_channels) numpy weight matrix.

Return type:

ndarray

rereference_matrix(kind, n_channels, *, clusters=None, include_current=True, min_reref_size=1, dtype=<class 'numpy.float64'>)[source]#

Build the weight matrix for a RereferenceKind.

Dispatches to car_matrix() for CAR; the cluster/reference arguments are ignored for IDENTITY. Accepts the enum or its plain string value.

Parameters:
Return type:

ndarray

Classes

class RereferenceKind(*values)[source]#

Bases: str, Enum

Deterministic rereference schemes expressible as a weight matrix.

str enum so values round-trip through config as their plain strings.

IDENTITY = 'identity'#

Pass the signal through unchanged.

CAR = 'car'#

Per-cluster common-average reference.