filter_bandstop

selfeeg.augmentation.functional.filter_bandstop(x: ArrayLike, Fs: float, Wp: list[float] = [0, 15], Ws: list[float] = [4, 8], rp: float = np.float64(0.44552789422304506), rs: float = np.float64(20.0), filter_type: str = 'butter', order: int = None, Wn: float = None, a: ndarray | float = None, b: ndarray | float = None, eeg_band: str = None, return_filter_coeff: bool = False)[source]

applies a bandstop filter on the last dimension of the ArrayLike object.

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.

If eeg_band is given, (Wp,Ws,rp,rs) are bypassed and instantiated according to the eeg band specified. The priority order remain, so if (Wn,order) or (a,b) are given, the filter will be created according to such arguments.

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 edges in Hz. It must be a length 2 scalar vector.

    Default = 30

  • Ws (float, optional) –

    Stopband edges in Hz. It must be a length 2 scalar vector.

    Default = 13

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

  • eeg_band (str, optional) –

    Any of the possible EEG bands. Accepted values are “delta”, “theta”, “alpha”, “beta”, “gamma”, “gamma_low”, “gamma_high”. Note that eeg_band bypass any (Wp, Ws, rp, rs), if given.

    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

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_bandpass(x, 128, [13,22], [5,27])
>>> f, per2 = periodogram(xaug[0,0], 128)
>>> print(np.isclose(np.max(per2[np.logical_and(f>5, f<27)]),
...                         0, rtol=1e-04, atol=1e-04))
>>> # should return True