pybispectra.utils.SpatioSpectralFilter#

class pybispectra.utils.SpatioSpectralFilter(data: ndarray, sampling_freq: int | float, verbose: bool = True)[source]#

Class for performing spatiospectral filtering.

Parameters:

datandarray, shape of [epochs, channels, times]: Data to perform spatiospectral filtering on.
sampling_freqint | float: Sampling frequency (in Hz) of data.
verbosebool (default True): Whether or not to report the progress of the processing.

Attributes:

filtersndarray, 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.
patternsndarray, shape of [rank, channels]: Spatial patterns for each of the spatial filters.
ratiosndarray, shape of [rank]: Signal-to-noise ratios for each of the spatial filters (eigenvalues of the eigendecomposition). Sorted in descending order.

Methods

`fit_hpmax`(signal_bounds, noise_bounds[, ...])	Fit HPMax filters to the data.
`fit_ssd`(signal_bounds, noise_bounds[, ...])	Fit SSD filters to the data.
`transform`([data])	Transform the data with the fitted filters.
`fit_transform_hpmax`(args, *kwargs)	Fit HPMax filters and transform the data.
`fit_transform_ssd`(args, *kwargs)	Fit SSD filters and transform the data.
`get_transformed_data`([min_ratio, copy])	Return the transformed data.

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

fit_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 to the data.

Parameters:

signal_boundstuple of int or float, length of 2: Lower and upper frequencies (in Hz), respectively, to treat as the signal of interest.
noise_boundstuple of int or float, 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_harmonicsint (default -1): Number of harmonic frequencies of signal_bounds to use when computing the filters. If 0, no harmonics are used. If -1, all harmonics are used.
indicestuple of int | None (default None): Channel indices to fit the filters to. If None, all channels are used.
rankint | None (default None): Rank subspace to project the data to. If None, the rank of the data is automatically computed and projected to.
csd_methodstr (default "multitaper"): Method to use when computing the CSD. Can be "multitaper" or "fourier".
n_fftint | None (default None): Number of samples in the FFT. If None, the number of times in each epoch is used.
mt_bandwidthint | float (default 5.0): Bandwidth of the multitaper windowing function (in Hz). Only used if csd_method is "multitaper".
mt_adaptivebool (default True): Whether to use adaptive weights when combining tapered spectra. Only used if csd_method is "multitaper".
mt_low_biasbool (default True): Whether to only use tapers with > 90% spectral concentration within the bandwidth. Only used if csd_method is "multitaper".
n_jobsint (default 1): Number of jobs to use when computing the CSD. If -1, all available CPUs are used.

Notes

MNE is used to compute the CSD, from which the covariance matrices are obtained [3] (mne.time_frequency.csd_array_multitaper() and mne.time_frequency.csd_array_fourier()).

Added in version 1.2.

Fit SSD filters to the data.

Parameters:

signal_boundstuple of int or float, length of 2: Lower and upper frequencies (in Hz), respectively, to treat as the signal of interest.
noise_boundstuple of int or float, length of 2: Lower and upper frequencies (in Hz) to treat as the noise, excluding the frequencies in signal_bounds.
signal_noise_gapint | float (default 1.0): Frequency count (in Hz) to treat as a transition boundary between signal_bounds and noise_bounds. Used to reduce spectral leakage between the signal and noise frequencies.
bandpass_filterbool (default False): Whether or not to bandpass filter the data before transforming with the SSD filters.
indicestuple of int | None (default None): Channel indices to fit the filters to. If None, all channels are used.
rankint | None (default None): Rank subspace to project the data to. If None, the rank of the data is automatically computed and projected to.

Notes

The SSD implementation in MNE is used to compute the filters (mne.decoding.SSD).

Added in version 1.2.

fit_transform_hpmax(*args: tuple, **kwargs: dict) → ndarray[source]#

Fit HPMax filters and transform the data.

Parameters:

argstuple: Positional parameters to pass to fit_hpmax().
kwargsdict: Keyword parameters to pass to fit_hpmax().

Returns:

transformed_datandarray, shape of [epochs, components, times]: Transformed data.

Notes

Equivalent to calling fit_hpmax() followed by transform().

fit_transform_ssd(*args: tuple, **kwargs: dict) → ndarray[source]#

Fit SSD filters and transform the data.

Parameters:

argstuple: Positional parameters to pass to fit_ssd().
kwargsdict: Keyword parameters to pass to fit_ssd().

Returns:

transformed_datandarray, shape of [epochs, components, times]: Transformed data.

Notes

Equivalent to calling fit_ssd() followed by transform().

get_transformed_data(min_ratio: int | float = -inf, copy: bool = True) → ndarray[source]#

Return the transformed data.

Parameters:

min_ratioint | float (default - numpy.inf): Only returns the transformed data for those spatial filters whose ratios values is greater or equal to this value.

Changed in version 1.2: Default value changed from 1.0 to -inf.
copybool (default True): Whether or not to return a copy of the data.

Added in version 1.2.

Returns:

transformed_datandarray, shape of [epochs, components, times]: Transformed data with only those components created with filters whose signal-to-noise ratios are > min_ratio.

Notes

Raises a warning if no components have a signal-to-noise ratio > min_ratio and verbose is True.

transform(data: ndarray | None = None) → ndarray[source]#

Transform the data with the fitted filters.

Parameters:

datandarray, shape of [epochs, channels, times] | None (default None): Data to transform with the fitted filters. If None, the data used to fit the filters is transformed.

Returns:

transformed_datandarray, shape of [epochs, components, times]: Transformed data.

Notes

Added in version 1.2.