ezmsg.sigproc.fir_hilbert

Functions

fir_hilbert_design_fun(fs, order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Hilbert FIR filter design using the Remez exchange algorithm. Design an order`th-order FIR Hilbert filter and return the filter coefficients. See :obj:`FIRHilbertFilterSettings for argument description.

Returns:

The filter coefficients as a tuple of (b, a).

Parameters:

• fs (float)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

Return type:

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

Classes

class FIRHilbertEnvelopeState

Bases: object

filter: FIRHilbertFilterTransformer | None = None

delay_buf: ndarray | None = None

dly: int | None = None

class FIRHilbertEnvelopeTransformer(*args, **kwargs)

Bases: BaseStatefulTransformer[FIRHilbertFilterSettings, AxisArray, AxisArray, FIRHilbertEnvelopeState]

Processor for computing the envelope of a signal using the Hilbert transform.

This processor applies a Hilbert FIR filter to the input signal to obtain the analytic signal, from which the envelope is computed.

The processor expects and outputs AxisArray messages with a “time” (time) axis.

Settings:

orderint

Filter order (taps = order + 1). Hilbert (type-III) filters require even order (odd taps). If odd order (even taps), order will be incremented by 1.

f_lofloat

Lower corner of Hilbert “pass” band (Hz). Transition starts at f_lo.

f_hifloat, optional

Upper corner of Hilbert “pass” band (Hz). Transition starts at f_hi. If None, highpass from f_lo to Nyquist.

trans_lofloat

Transition width (Hz) below f_lo. Decrease to sharpen transition.

trans_hifloat

Transition width (Hz) above f_hi. Decrease to sharpen transition.

weight_passfloat

Weight for Hilbert pass region.

weight_stop_lofloat

Weight for low stop band.

weight_stop_hifloat

Weight for high stop band.

norm_bandtuple(float, float), optional

Optional normalization band (f_lo, f_hi) in Hz for gain normalization. If None, no normalization is applied.

norm_freqfloat, optional

Optional normalization frequency in Hz for gain normalization. If None, no normalization is applied.

Example:

```python processor = FIRHilbertEnvelopeTransformer(

settings=FIRHilbertFilterSettings(

order=170, f_lo=1.0, f_hi=50.0,

)

)

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

Bases: BaseTransformerUnit[FIRHilbertFilterSettings, AxisArray, AxisArray, FIRHilbertEnvelopeTransformer]

Unit wrapper for the FIRHilbertEnvelopeTransformer.

This unit provides a plug-and-play interface for calculating the envelope using the FIR Hilbert transform on a signal in an ezmsg graph-based system. It takes in AxisArray inputs and outputs processed data in the same format.

Example:

```python unit = FIRHilbertEnvelopeUnit(

settings=FIRHilbertFilterSettings(

order=170, f_lo=1.0, f_hi=50.0,

)

)

SETTINGS

alias of FIRHilbertFilterSettings

Parameters:

settings (Settings | None)

class FIRHilbertFilterSettings(axis=None, coef_type='ba', order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Bases: FilterBaseSettings

Settings for FIRHilbertFilter.

Parameters:

• axis (str | None)

• coef_type (str)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

coef_type: str = 'ba'

Coefficient type. Must be ‘ba’ for FIR.

order: int = 170

Filter order (taps = order + 1). Hilbert (type-III) filters require even order (odd taps). If odd order (even taps), order will be incremented by 1.

f_lo: float = 1.0

Lower corner of Hilbert “pass” band (Hz). Transition starts at f_lo.

f_hi: float | None = None

Upper corner of Hilbert “pass” band (Hz). Transition starts at f_hi. If None, highpass from f_lo to Nyquist.

trans_lo: float = 1.0

Transition width (Hz) below f_lo. Decrease to sharpen transition.

trans_hi: float = 1.0

Transition width (Hz) at high end. Decrease to sharpen transition.

weight_pass: float = 1.0

Weight for Hilbert pass region.

weight_stop_lo: float = 1.0

Weight for low stop band.

weight_stop_hi: float = 1.0

Weight for high stop band.

norm_band: tuple[float, float] | None = None

Optional normalization band (f_lo, f_hi) in Hz for gain normalization. If None, no normalization is applied.

norm_freq: float | None = None

Optional normalization frequency in Hz for gain normalization. If None, no normalization is applied.

__init__(axis=None, coef_type='ba', order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Parameters:

• axis (str | None)

• coef_type (str)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

Return type:

None

class FIRHilbertFilterTransformer(*args, **kwargs)

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

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]]] | None]

get_taps()

Return type:

int | None

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

Bases: BaseFilterByDesignTransformerUnit[FIRHilbertFilterSettings, FIRHilbertFilterTransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of FIRHilbertFilterSettings

class FIRHilbertFilterSettings(axis=None, coef_type='ba', order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Bases: FilterBaseSettings

Settings for FIRHilbertFilter.

Parameters:

• axis (str | None)

• coef_type (str)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

coef_type: str = 'ba'

Coefficient type. Must be ‘ba’ for FIR.

order: int = 170

Filter order (taps = order + 1). Hilbert (type-III) filters require even order (odd taps). If odd order (even taps), order will be incremented by 1.

f_lo: float = 1.0

Lower corner of Hilbert “pass” band (Hz). Transition starts at f_lo.

f_hi: float | None = None

Upper corner of Hilbert “pass” band (Hz). Transition starts at f_hi. If None, highpass from f_lo to Nyquist.

trans_lo: float = 1.0

Transition width (Hz) below f_lo. Decrease to sharpen transition.

trans_hi: float = 1.0

Transition width (Hz) at high end. Decrease to sharpen transition.

weight_pass: float = 1.0

Weight for Hilbert pass region.

weight_stop_lo: float = 1.0

Weight for low stop band.

weight_stop_hi: float = 1.0

Weight for high stop band.

norm_band: tuple[float, float] | None = None

Optional normalization band (f_lo, f_hi) in Hz for gain normalization. If None, no normalization is applied.

norm_freq: float | None = None

Optional normalization frequency in Hz for gain normalization. If None, no normalization is applied.

__init__(axis=None, coef_type='ba', order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Parameters:

• axis (str | None)

• coef_type (str)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

Return type:

None

fir_hilbert_design_fun(fs, order=170, f_lo=1.0, f_hi=None, trans_lo=1.0, trans_hi=1.0, weight_pass=1.0, weight_stop_lo=1.0, weight_stop_hi=1.0, norm_band=None, norm_freq=None)

Hilbert FIR filter design using the Remez exchange algorithm. Design an order`th-order FIR Hilbert filter and return the filter coefficients. See :obj:`FIRHilbertFilterSettings for argument description.

Returns:

The filter coefficients as a tuple of (b, a).

Parameters:

• fs (float)

• order (int)

• f_lo (float)

• f_hi (float | None)

• trans_lo (float)

• trans_hi (float)

• weight_pass (float)

• weight_stop_lo (float)

• weight_stop_hi (float)

• norm_band (tuple[float, float] | None)

• norm_freq (float | None)

Return type:

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

class FIRHilbertFilterTransformer(*args, **kwargs)

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

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]]] | None]

get_taps()

Return type:

int | None

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

Bases: BaseFilterByDesignTransformerUnit[FIRHilbertFilterSettings, FIRHilbertFilterTransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of FIRHilbertFilterSettings

class FIRHilbertEnvelopeState

Bases: object

filter: FIRHilbertFilterTransformer | None = None

delay_buf: ndarray | None = None

dly: int | None = None

class FIRHilbertEnvelopeTransformer(*args, **kwargs)

Bases: BaseStatefulTransformer[FIRHilbertFilterSettings, AxisArray, AxisArray, FIRHilbertEnvelopeState]

Processor for computing the envelope of a signal using the Hilbert transform.

This processor applies a Hilbert FIR filter to the input signal to obtain the analytic signal, from which the envelope is computed.

The processor expects and outputs AxisArray messages with a “time” (time) axis.

Settings:

orderint

Filter order (taps = order + 1). Hilbert (type-III) filters require even order (odd taps). If odd order (even taps), order will be incremented by 1.

f_lofloat

Lower corner of Hilbert “pass” band (Hz). Transition starts at f_lo.

f_hifloat, optional

Upper corner of Hilbert “pass” band (Hz). Transition starts at f_hi. If None, highpass from f_lo to Nyquist.

trans_lofloat

Transition width (Hz) below f_lo. Decrease to sharpen transition.

trans_hifloat

Transition width (Hz) above f_hi. Decrease to sharpen transition.

weight_passfloat

Weight for Hilbert pass region.

weight_stop_lofloat

Weight for low stop band.

weight_stop_hifloat

Weight for high stop band.

norm_bandtuple(float, float), optional

Optional normalization band (f_lo, f_hi) in Hz for gain normalization. If None, no normalization is applied.

norm_freqfloat, optional

Optional normalization frequency in Hz for gain normalization. If None, no normalization is applied.

Example:

```python processor = FIRHilbertEnvelopeTransformer(

settings=FIRHilbertFilterSettings(

order=170, f_lo=1.0, f_hi=50.0,

)

)

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

Bases: BaseTransformerUnit[FIRHilbertFilterSettings, AxisArray, AxisArray, FIRHilbertEnvelopeTransformer]

Unit wrapper for the FIRHilbertEnvelopeTransformer.

This unit provides a plug-and-play interface for calculating the envelope using the FIR Hilbert transform on a signal in an ezmsg graph-based system. It takes in AxisArray inputs and outputs processed data in the same format.

Example:

```python unit = FIRHilbertEnvelopeUnit(

settings=FIRHilbertFilterSettings(

order=170, f_lo=1.0, f_hi=50.0,

)

)

SETTINGS

alias of FIRHilbertFilterSettings

Parameters:

settings (Settings | None)