filter_lowpass

selfeeg.augmentation.functional.filter_lowpass(x: ArrayLike, Fs: float, Wp: float = 50, Ws: float = 70, rp: float = np.float64(0.44552789422304506), rs: float = np.float64(16.478174818886377), filter_type: str = 'butter', order: int = None, Wn: float = None, a: ndarray | float = None, b: ndarray | float = None, return_filter_coeff: bool = False) → tuple[ArrayLike, tuple[ArrayLike, ArrayLike] | None][source]

applies a lowpass filter on the last dimension of the ArrayLike.

If a and b coefficient are not given, internally calls get_filter_coeff with the other arguments to get them. The filter design follows this hierarchical order:

(Wp,Ws,rp,rs) –> (Wn, order) –> (a,b)

Therefore the arguments closer to a and b in the scheme are used to get the filter coefficients.

Parameters:

  • x (ArrayLike) – The input Tensor or Array. The last two dimensions must refer to the EEG recording (Channels x Samples).

  • Fs (float) – The sampling frequency in Hz.

  • Wp (float, optional) –

    Passband edge in Hz.

    Default = 50

  • Ws (float, optional) –

    Stopband edge in Hz.

    Default = 70

  • rp (float, optional) –

    Ripple at bandpass in dB.

    Default = -20*log10(0.95)

  • rs (float, optional) –

    Ripple at stopband in dB.

    Default = -20*log10(0.15)

  • filter_type (str, optional) –

    Which filter design. The accepted values are ‘butter’, ‘ellip’, ‘cheby1’, ‘cheby2’.

    Default = ‘butter’

  • order (int, optional) –

    The order of the filter.

    Default = None

  • Wn (ArrayLike, optional) –

    The critical frequency or frequencies.

    Default = None

  • a (ArrayLike, optional) –

    The denominator coefficients of the filter.

    Default = None

  • b (ArrayLike, optional) –

    The numerator coefficients of the filer.

    Default = None

  • return_filter_coeff (bool, optional) –

    Whether to return the filter coefficients or not.

    Default = False

Returns:

  • x (ArrayLike) – the augmented version of the input Tensor or Array.

  • b (ArrayLike, optional) – Array with the numerator coefficients of rational transfer function.

  • a (ArrayLike, optional) – Array with the denominator coefficients of rational transfer function.

Note

Many parameters are those used in scipy’s implementation of Matlab-style filters, except for Wp and Ws, which must be specified directly in Hz. The normalization to [0,1] with respect to half-cycles/sample (i.e., Nyquist frequency) is done directly inside the get_filter_coeff function.

Note

Pytorch filtfilt works differently on edges and is pretty unstable with high order filters, so avoid restrictive conditions that can increase the order of the filter.

Example

>>> import torch
>>> import numpy as np
>>> from scipy.signal import periodogram
>>> import selfeeg.augmentation as aug
>>> x = torch.zeros(16,32,1024) + torch.sin(torch.linspace(0, 8*torch.pi,1024))
>>> x += torch.sin(torch.linspace(0, 48*2*torch.pi,1024))
>>> x += torch.sin(torch.linspace(0, 256*2*torch.pi,1024))
>>> f, per1 = periodogram(x[0,0], 128)
>>> xaug = aug.filter_lowpass(x, 128, 20, 30)
>>> f, per2 = periodogram(xaug[0,0], 128)
>>> print(np.isclose(np.max(per2[f>30]), 0, rtol=1e-04, atol=1e-04))