ezmsg.learn.process.flatten

Flatten with time-lag-windowing struct semantics.

Thin wrapper around ezmsg.sigproc.flatten.FlattenTransformer that detects the windowed-feature case (any input with both the preserve dim — typically "win" — and a "time" lag dim alongside a labeled feature axis) and attaches a structured lag CoordinateAxis to the inner sample dim before delegating. The output merged-axis struct then carries a real integer lag field alongside the remaining feature dims, and sigproc’s canonical label field composes naturally (e.g. "t-2/c0" for 3-D (win, time, ch) or "t-2/c0/spk" for 4-D (win, time, ch, feature)).

Outside the lag case this module delegates unchanged — prefer ezmsg.sigproc.flatten.Flatten directly for the general (time, ch, feature) → (time, ch_x_feature) collapse.

Classes

class Flatten(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[FlattenSettings, AxisArray, AxisArray, FlattenTransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of FlattenSettings

class FlattenSettings(preserve_axis=None, sample_axis=None, feature_axis='ch')

Bases: Settings

Settings for the learn-side Flatten.

Mirrors ezmsg.sigproc.flatten.FlattenSettings but uses the historical feature_axis field name and defaults oriented toward time-lag windowing.

Parameters:

• preserve_axis (str | None)

• sample_axis (str | None)

• feature_axis (str)

preserve_axis: str | None = None

Axis kept as the leading dim of the output. Defaults to the input’s leading dim (typically "win" in the windowed pipeline).

sample_axis: str | None = None

Output name for the preserved axis. Defaults to preserve_axis (no rename).

feature_axis: str = 'ch'

Output name for the merged axis.

__init__(preserve_axis=None, sample_axis=None, feature_axis='ch')

Parameters:

• preserve_axis (str | None)

• sample_axis (str | None)

• feature_axis (str)

Return type:

None

class FlattenTransformer(*args, **kwargs)

Bases: BaseStatefulTransformer[FlattenSettings, AxisArray, AxisArray, _LagFlattenState]

Time-lag-aware Flatten that delegates to the canonical sigproc unit.

On each shape change we detect the lag case and, if present, precompute a structured lag CoordinateAxis. Per message that axis is injected into the inner sample dim before delegating to the inner sigproc transformer, which then produces an output merged-axis struct with lag (int), ch, and the sigproc-composed "label" ("t-2/c0" style).

STREAMING_DIMS: ClassVar[tuple[str, ...]] = ('win',)

Fallback stream dimension when the producer does not declare one.

The base class defaults to ("time",), which is exactly wrong here: the canonical input is (win, time, ch[, feature]), where win is what grows per message and time is the lag dimension inside each window. The lag count sizes the lag axis built below, so excluding time would stop this noticing a window-length change, while including win would rebuild the inner transformer every time the window count jittered.

Consulted only when AxisArray.stream_dim is absent; a producer that declares it – ezmsg-sigproc’s Window does – overrides this.