ezmsg.sigproc.butterworthzerophase#

Streaming zero-phase Butterworth filter implemented as a two-stage composite processor.

Stage 1: Forward causal Butterworth filter (from ezmsg.sigproc.butterworthfilter) Stage 2: Backward acausal filter with buffering (ButterworthBackwardFilterTransformer)

The output is delayed by pad_length samples to ensure the backward pass has sufficient future context. The pad_length is computed analytically using scipy’s heuristic.

Classes

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

Bases: FilterByDesignTransformer[ButterworthFilterSettings, tuple[NDArray, NDArray] | NDArray]

Backward (acausal) Butterworth filter with buffering.

This transformer buffers its input and applies the filter in reverse, outputting only the “settled” portion where transients have decayed. This introduces a lag of pad_length samples.

Intended to be used as stage 2 in a zero-phase filter pipeline, receiving forward-filtered data from a ButterworthFilterTransformer.

Retention is a fixed pad_length-sample carry-over rather than a ring buffer: each chunk is filtered together with the tail of the previous one, the settled portion is emitted, and the trailing pad_length raw samples are kept to be re-filtered with the next chunk. The data are never permuted, so the filter runs along whichever axis the caller laid the time dimension on – which for time-last input is the contiguous one, and is also the layout the MLX Metal kernel wants.

get_design_function()[source]#

Return a function that takes sampling frequency and returns filter coefficients.

Return type:

Callable[[float], tuple[NDArray, NDArray] | NDArray | None]

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

Bases: BaseTransformerUnit[ButterworthZeroPhaseSettings, AxisArray, AxisArray, ButterworthZeroPhaseTransformer]

Parameters:

settings (Settings | None)

SETTINGS#

alias of ButterworthZeroPhaseSettings

class ButterworthZeroPhaseSettings(axis=None, coef_type='ba', use_fast_sosfilt=True, use_mlx_metal=True, mlx_metal_chunk_sizes=(512,), thread_min_bytes=1048576, fir_fft_min_taps=64, order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)[source]#

Bases: ButterworthFilterSettings

Settings for ButterworthZeroPhase.

This implements a streaming zero-phase Butterworth filter using forward-backward filtering. The output is delayed by pad_length samples to ensure the backward pass has sufficient future context.

The pad_length is computed by finding where the filter’s impulse response decays to settle_cutoff fraction of its peak value. This accounts for the filter’s actual time constant rather than just its order.

Parameters:

  • axis (str | None)

  • coef_type (str)

  • use_fast_sosfilt (bool)

  • use_mlx_metal (bool)

  • mlx_metal_chunk_sizes (tuple[int, ...])

  • thread_min_bytes (int)

  • fir_fft_min_taps (int)

  • order (int)

  • cuton (float | None)

  • cutoff (float | None)

  • wn_hz (bool)

  • settle_cutoff (float)

  • max_pad_duration (float | None)

settle_cutoff: float = 0.01#

Fraction of peak impulse response used to determine settling time. The pad_length is set to the number of samples until the impulse response decays to this fraction of its peak. Default is 0.01 (1% of peak).

max_pad_duration: float | None = None#

Maximum pad duration in seconds. If set, the pad_length will be capped at this value times the sampling rate. Use this to limit latency for filters with very long impulse responses. Default is None (no limit).

__init__(axis=None, coef_type='ba', use_fast_sosfilt=True, use_mlx_metal=True, mlx_metal_chunk_sizes=(512,), thread_min_bytes=1048576, fir_fft_min_taps=64, order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)#
Parameters:

  • axis (str | None)

  • coef_type (str)

  • use_fast_sosfilt (bool)

  • use_mlx_metal (bool)

  • mlx_metal_chunk_sizes (tuple[int, ...])

  • thread_min_bytes (int)

  • fir_fft_min_taps (int)

  • order (int)

  • cuton (float | None)

  • cutoff (float | None)

  • wn_hz (bool)

  • settle_cutoff (float)

  • max_pad_duration (float | None)

Return type:

None

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

Bases: CompositeProcessor[ButterworthZeroPhaseSettings, AxisArray, AxisArray]

Streaming zero-phase Butterworth filter as a composite of two stages.

Stage 1 (forward): Standard causal Butterworth filter with state Stage 2 (backward): Acausal Butterworth filter with buffering

The output is delayed by pad_length samples.

classmethod get_message_type(dir)[source]#
Parameters:

dir (str)

Return type:

type[AxisArray]