ezmsg.sigproc.gaussiansmoothing#

Gaussian kernel smoothing filter.

Functions

gaussian_smoothing_filter_design(sigma=1.0, width=4, kernel_size=None, causal=False)[source]#

Design a normalized Gaussian FIR kernel. sigma is in samples; callers with a time-domain sigma must scale by the sampling rate first.

If causal is True, only the causal half of the Gaussian is kept – the peak sits at lag 0 and the tail extends into the past – and kernel_size counts causal taps. See GaussianSmoothingSettings for the group delay of each mode.

Parameters:
Return type:

tuple[NDArray, NDArray] | None

Classes

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

Bases: BaseFilterByDesignTransformerUnit[GaussianSmoothingSettings, GaussianSmoothingFilterTransformer]

Parameters:

settings (Settings | None)

SETTINGS#

alias of GaussianSmoothingSettings

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

Bases: FilterByDesignTransformer[GaussianSmoothingSettings, tuple[NDArray, NDArray]]

get_design_function()[source]#

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

Return type:

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

class GaussianSmoothingSettings(axis: str | None = None, coef_type: str = 'ba', use_fast_sosfilt: bool = True, use_mlx_metal: bool = True, mlx_metal_chunk_sizes: tuple[int, ...] = (512,), thread_min_bytes: int = 1048576, fir_fft_min_taps: int = 64, sigma: float | None = 0.01, width: int | None = 4, kernel_size: int | None = None, causal: bool = False)[source]#

Bases: FilterBaseSettings

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)

  • sigma (float | None)

  • width (int | None)

  • kernel_size (int | None)

  • causal (bool)

sigma: float | None = 0.01#

float Standard deviation of the Gaussian kernel, in seconds. Converted to samples using the sampling rate of the first message. The -3 dB corner frequency is sqrt(ln 2) / (2 * pi * sigma); the default of 0.01 s is equivalent to a ~13.2 Hz low-pass.

Type:

sigma

width: int | None = 4#

int Number of standard deviations covered by the kernel window if kernel_size is not provided.

Type:

width

kernel_size: int | None = None#

int | None Length of the kernel in samples. If provided, overrides automatic calculation. In causal mode this is the number of causal taps, i.e. the kernel spans kernel_size samples into the past rather than kernel_size // 2.

Type:

kernel_size

causal: bool = False#

bool If False (default), the kernel is a symmetric Gaussian of 2 * width * sigma + 1 taps. Filtering is applied causally (lfilter), so the acausal half of the kernel manifests purely as group delay of (kernel_size - 1) / 2 == width * sigma samples – 4 * sigma at the default width=4.

If True, the kernel is the causal half of that Gaussian (peak at lag 0, tail extending only into the past), renormalized to unit sum. Its group delay is the centroid of a half-Gaussian, sigma * sqrt(2 / pi) (~0.8 * sigma), i.e. roughly a factor of 5 less lag than the symmetric kernel at the same sigma.

The two modes are not interchangeable at equal sigma: halving the kernel also halves the effective averaging window, so the causal kernel smooths less and its stopband rolls off less steeply (-12 dB/octave versus the symmetric kernel’s much sharper Gaussian rolloff) for a given sigma. Compare them at matched white-noise variance reduction (sum(b ** 2)) rather than at matched sigma; on that footing the causal kernel reaches the same noise gain at roughly a third of the lag. For example, at 100 Hz a symmetric sigma of 20 ms gives a noise gain of 0.141 for 80 ms of delay, while a causal sigma of 38 ms gives the same 0.141 for 27 ms.

Type:

causal

__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, sigma=0.01, width=4, kernel_size=None, causal=False)#
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)

  • sigma (float | None)

  • width (int | None)

  • kernel_size (int | None)

  • causal (bool)

Return type:

None