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)

Bases: FilterByDesignTransformer[ButterworthFilterSettings, tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]] | ndarray[tuple[Any, …], dtype[_ScalarT]]]

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.

get_design_function()

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

Return type:

Callable[[float], tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]] | ndarray[tuple[Any, …], dtype[_ScalarT]] | None]

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

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

Parameters:

settings (Settings | None)

SETTINGS

alias of ButterworthZeroPhaseSettings

class ButterworthZeroPhaseSettings(axis=None, coef_type='ba', order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)

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)

• 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', order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)

Parameters:

• axis (str | None)

• coef_type (str)

• 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)

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)

Parameters:

dir (str)

Return type:

type[AxisArray]

class ButterworthZeroPhaseSettings(axis=None, coef_type='ba', order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)

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)

• 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', order=0, cuton=None, cutoff=None, wn_hz=True, settle_cutoff=0.01, max_pad_duration=None)

Parameters:

• axis (str | None)

• coef_type (str)

• order (int)

• cuton (float | None)

• cutoff (float | None)

• wn_hz (bool)

• settle_cutoff (float)

• max_pad_duration (float | None)

Return type:

None

class ButterworthBackwardFilterTransformer(*args, **kwargs)

Bases: FilterByDesignTransformer[ButterworthFilterSettings, tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]] | ndarray[tuple[Any, …], dtype[_ScalarT]]]

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.

get_design_function()

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

Return type:

Callable[[float], tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]] | ndarray[tuple[Any, …], dtype[_ScalarT]] | None]

class ButterworthZeroPhaseTransformer(*args, **kwargs)

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)

Parameters:

dir (str)

Return type:

type[AxisArray]

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

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

Parameters:

settings (Settings | None)

SETTINGS

alias of ButterworthZeroPhaseSettings