pybispectra.utils.SpatioSpectralFilter#
- class pybispectra.utils.SpatioSpectralFilter(data: ndarray, sampling_freq: int | float, verbose: bool = True)[source]#
Class for performing spatiospectral filtering.
- Parameters:
Notes
The filtering methods used here rely on generalised eigendecomposition: a multivariate method for generating filters that maximise discrimination between signal and noise features of the data [1]. Two approaches are available: spatio-spectral decomposition (SSD) [2]; and harmonic power maximisation (HPMax) [3].
In SSD, a signal band of interest and a flanking noise band are selected, with the goal of generating a spatial filter that will maximise information in the signal band of interest, and minimise information from the flanking noise frequencies. In practice, this is implemented by bandpass filtering the data at a frequency range of interest and computing the covariance matrices on the signal and noise periods which are passed to the generalised eigendecomposition.
HPMax is an extension of SSD, in which not only the signal band of interest, but also information from the harmonics of these frequencies is maximised with the spatial filters. HPMax is implemented by computing the cross-spectral density of the data, which can then be summed across the signal and noise frequencies of interest, taking advantage of the fact that the cross-spectral density is a frequency-resolved representation of the covariance matrix.
Depending on the signal-to-noise ratio (SNR) of the data, the performance of these methods for recovering the underlying signal of interest - measured by the ability to suppress noise whilst retaining the original waveshape - can vary [3]:
Low SNRs: SSD filters applied to bandpass-filtered data (SSD+) can show favourable performance compared to SSD applied to broadband data (SSD-) and HPMax. The distortion of waveshape with bandpass filtering in SSD+ is compensated for by the higher level of noise reduction.
Intermediate SNRs: SSD- and HPMax performance can match or surpass SSD+ performance, and HPMax can outperform SSD-. The lower level of noise in the base signal means that the weaker degree of noise reduction with SSD- and HPMax is sufficient to uncover the signal without the distorting effects of bandpass filtering on waveshape.
High SNRs: HPMax can show increased or similar performance to SSD-.
It is therefore recommended that you explore the performance of the different methods on your data.
Generalised eigendecompositions have the general form
\(\textbf{NW} \boldsymbol{\Lambda}=\textbf{SW}\) ,
which can also be represented in the ratio form
\(\boldsymbol{\Lambda}=\Large{\frac{\textbf{W}^T\textbf{SW}}{ \textbf{W}^T\textbf{NW}}}\) ,
where \(\textbf{S}\) and \(\textbf{N}\) are the covariance matrices for the signal and noise information in the data, respectively; \(\textbf{W}\) is a common set of spatial filters (which, when applied to the data, will maximise signal information content and minimise noise information content); and \(\boldsymbol{\Lambda}\) is a diagonal matrix of eigenvalues representing the ratio of signal-to-noise information content in the data transformed with each spatial filter. Accordingly, spatial filters for with an SNR > 1 are generally of interest.
References
- Attributes:
- filters
ndarray
, shape of [channels, rank] Spatial filters (eigenvectors of the eigendecomposition). Sorted in descending order according to the size of the signal-to-noise ratios of
ratios
.- patterns
ndarray
, shape of [rank, channels] Spatial patterns for each of the spatial filters.
- ratios
ndarray
, shape of [rank] Signal-to-noise ratios for each of the spatial filters (eigenvalues of the eigendecomposition). Sorted in descending order.
- filters
Methods
fit_transform_hpmax
(signal_bounds, noise_bounds)Fit HPMax filters and transform the data.
fit_transform_ssd
(signal_bounds, noise_bounds)Fit SSD filters and transform the data.
get_transformed_data
([min_ratio])Return the transformed data.
- fit_transform_hpmax(signal_bounds: tuple[int | float], noise_bounds: tuple[int | float], n_harmonics: int = -1, indices: tuple[int] | None = None, rank: int | None = None, csd_method: str = 'multitaper', n_fft: int | None = None, mt_bandwidth: int | float = 5.0, mt_adaptive: bool = True, mt_low_bias: bool = True, n_jobs: int = 1) None [source]#
Fit HPMax filters and transform the data.
- Parameters:
- signal_bounds
tuple
ofint
orfloat
, length of 2 Lower and upper frequencies (in Hz), respectively, to treat as the signal of interest.
- noise_bounds
tuple
ofint
orfloat
, length of 2 Lower and upper frequencies (in Hz) to treat as the noise, excluding the frequencies in
signal_bounds
. For harmonics, the same number of frequency bins around the harmonic frequencies are taken as noise frequencies.- n_harmonics
int
(default-1
) Number of harmonic frequencies of
signal_bounds
to use when computing the filters. If0
, no harmonics are used. If-1
, all harmonics are used.- indices
tuple
ofint
|None
(defaultNone
) Channel indices to fit the filters to. If
None
, all channels are used.- rank
int
|None
(defaultNone
) Rank subspace to project the data to. If
None
, the rank of the data is automatically computed and projected to.- csd_method
str
(default"multitaper"
) Method to use when computing the CSD. Can be
"multitaper"
or"fourier"
.- n_fft
int
|None
(defaultNone
) Number of samples in the FFT. If
None
, the number of times in each epoch is used.- mt_bandwidth
int
|float
(default5.0
) Bandwidth of the multitaper windowing function (in Hz). Only used if
csd_method
is"multitaper"
.- mt_adaptive
bool
(defaultTrue
) Whether to use adaptive weights when combining tapered spectra. Only used if
csd_method
is"multitaper"
.- mt_low_bias
bool
(defaultTrue
) Whether to only use tapers with > 90% spectral concentration within the bandwidth. Only used if
csd_method
is"multitaper"
.- n_jobs
int
(default1
) Number of jobs to use when computing the CSD. If
-1
, all available CPUs are used.
- signal_bounds
Notes
MNE is used to compute the CSD, from which the covariance matrices are obtained [3] (
mne.time_frequency.csd_array_multitaper()
andmne.time_frequency.csd_array_fourier()
).
- fit_transform_ssd(signal_bounds: tuple[int | float], noise_bounds: tuple[int | float], signal_noise_gap: int | float = 1.0, bandpass_filter: bool = False, indices: tuple[int] | None = None, rank: int | None = None) None [source]#
Fit SSD filters and transform the data.
- Parameters:
- signal_bounds
tuple
ofint
orfloat
, length of 2 Lower and upper frequencies (in Hz), respectively, to treat as the signal of interest.
- noise_bounds
tuple
ofint
orfloat
, length of 2 Lower and upper frequencies (in Hz) to treat as the noise, excluding the frequencies in
signal_bounds
.- signal_noise_gap
int
|float
(default1.0
) Frequency count (in Hz) to treat as a transition boundary between
signal_bounds
andnoise_bounds
. Used to reduce spectral leakage between the signal and noise frequencies.- bandpass_filter
bool
(defaultFalse
) Whether or not to bandpass filter the data before transforming with the SSD filters.
- indices
tuple
ofint
|None
(defaultNone
) Channel indices to fit the filters to. If
None
, all channels are used.- rank
int
|None
(defaultNone
) Rank subspace to project the data to. If
None
, the rank of the data is automatically computed and projected to.
- signal_bounds
Notes
The SSD implementation in MNE is used to compute the filters (
mne.decoding.SSD
).
- get_transformed_data(min_ratio: int | float = 1.0) ndarray [source]#
Return the transformed data.
- Parameters:
- Returns:
- transformed_data
ndarray
, shape of [epochs, components, times] Transformed data with only those components created with filters whose signal-to-noise ratios are >
min_ratio
.
- transformed_data
Notes
Raises a warning if no components have a signal-to-noise ratio >
min_ratio
andverbose
isTrue
.