ezmsg.event.peak#

Detects peaks in a signal.

Note

This module supports the Array API standard, enabling use with NumPy, CuPy, PyTorch, and other compatible array libraries. Signal data operations are array-API compliant. Event detection itself uses NumPy regardless of input backend. The output container is configurable via OutputFormat: SPARSE produces a sparse.COO (default), while DENSE produces a dense array in the input’s namespace so downstream consumers can keep data on accelerators.

Classes

class OutputFormat(*values)[source]#

Bases: str, Enum

Output container for ThresholdCrossingTransformer.

SPARSE = 'sparse'#

Emit a sparse.COO array with one entry per accepted event (default).

DENSE = 'dense'#

Emit a dense array in the input’s namespace, with non-zero entries at event positions.

Use this when downstream nodes are namespace-aware (e.g., ezmsg.event.kernel_activation.BinnedKernelActivation) and you want the data to stay on its current device (e.g., MLX, CuPy).

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

Bases: BaseTransformerUnit[ThresholdSettings, AxisArray, AxisArray, ThresholdCrossingTransformer]

Parameters:

settings (Settings | None)

SETTINGS#

alias of ThresholdSettings

class ThresholdCrossingState[source]#

Bases: object

State for ThresholdCrossingTransformer.

max_width: int = 0#
min_width: int = 1#
refrac_width: int = 0#
scaler: AdaptiveStandardScalerTransformer | None = None#

Object performing adaptive z-scoring.

data: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None#

Trailing buffer in case peak spans sample chunks. Only used if align_on_peak or return_peak_val.

data_raw: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None#

Keep track of the raw data so we can return_peak_val. Only needed if using the scaler.

elapsed: object | None = None#

Int32 array, samples since last accepted crossing per feature.

Lives in the input’s namespace: numpy (flat (prod(features),)) for the cpu event-loop path, MLX (shape (*features,)) for the on-device Metal path.

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

Bases: BaseStatefulTransformer[ThresholdSettings, AxisArray, AxisArray, ThresholdCrossingState]

Transformer that detects threshold crossing events.

class ThresholdSettings(threshold: float = -3.5, max_peak_dur: float = 0.002, min_peak_dur: float = 0.0, refrac_dur: float = 0.001, align_on_peak: bool = False, return_peak_val: bool = False, auto_scale_tau: float = 0.0, output_format: OutputFormat = <OutputFormat.SPARSE: 'sparse'>)[source]#

Bases: Settings

Parameters:
threshold: float = -3.5#

the value the signal must cross before the peak is found.

max_peak_dur: float = 0.002#

The maximum duration of a peak in seconds.

min_peak_dur: float = 0.0#

The minimum duration of a peak in seconds. If 0 (default), no minimum duration is enforced.

refrac_dur: float = 0.001#

The minimum duration between peaks in seconds. If 0 (default), no refractory period is enforced.

align_on_peak: bool = False#

If False (default), the returned sample index indicates the first sample across threshold. If True, the sample index indicates the sample with the largest deviation after threshold crossing.

return_peak_val: bool = False#

If True then the peak value is included in the EventMessage or sparse matrix payload.

auto_scale_tau: float = 0.0#

If > 0, the data will be passed through a standard scaler prior to thresholding.

output_format: OutputFormat = 'sparse'#

Output container. SPARSE (default) emits sparse.COO. DENSE emits a dense array in the input’s namespace so accelerator-resident data stays on device.

When DENSE is combined with an MLX input and a basic configuration (no align_on_peak, return_peak_val, min_peak_dur, or auto_scale_tau), threshold detection + refractory enforcement run via an on-device Metal kernel automatically — there is no separate opt-in toggle.

__init__(threshold=-3.5, max_peak_dur=0.002, min_peak_dur=0.0, refrac_dur=0.001, align_on_peak=False, return_peak_val=False, auto_scale_tau=0.0, output_format=OutputFormat.SPARSE)#
Parameters:
Return type:

None