meegkit.ress

Rhythmic Entrainment Source Separation.

Functions

RESS(sfreq, peak_freq[, neig_freq, ...])

Rhythmic Entrainment Source Separation.

class meegkit.ress.RESS(sfreq: int, peak_freq: float, neig_freq: float = 1, peak_width: float = 0.5, neig_width: float = 1, n_keep: int = 1, gamma: float = 0.01, compute_unmixing: bool = False)

Bases: TransformerMixin, BaseEstimator

Rhythmic Entrainment Source Separation.

As described in [1].

Parameters:

• sfreq (int) – Sampling frequency.

• peak_freq (float) – Peak frequency.

• neig_freq (float) – Distance of neighbouring frequencies away from peak frequency, +/- in Hz (default=1).

• peak_width (float) – FWHM of the peak frequency (default=.5).

• neig_width (float) – FWHM of the neighboring frequencies (default=1).

• n_keep (int) – Number of components to keep (default=1). -1 keeps all components.

• gamma (float) – Regularization coefficient, between 0 and 1 (default=0.01, which corresponds to 1 % regularization and helps reduce numerical problems for noisy or reduced-rank matrices [2]).

• compute_unmixing (bool) – If True, also computing unmixing matrices (from_ress), used to transform the data back into sensor space.

Examples

To project the RESS components back into sensor space, one can proceed as follows: >>> # First create RESS estimator and fit_transform the data >>> r = ress.RESS(sfreq, peak_freq, compute_unmixing=True) >>> out = r.fit_transform(data) >>> # Then matrix multiply each trial by the unmixing matrix: >>> fromRESS = r.from_ress >>> proj = matmul3d(out, fromRESS)

To transform a new observation into RESS component space (e.g. in the context of a cross-validation, with separate train/test sets) use the transform method: >>> new_comp = r.transform(newdata)

References

[1]

Cohen, M. X., & Gulbinaite, R. (2017). Rhythmic entrainment source separation: Optimizing analyses of neural responses to rhythmic sensory stimulation. Neuroimage, 147, 43-56.

[2]

Cohen, M. X. (2021). A tutorial on generalized eigendecomposition for source separation in multichannel electrophysiology. ArXiv:2104.12356 [Eess, q-Bio].

Methods

fit(X[, y])	Learn a RESS filter.
fit_transform(X[, y])	Compute RESS filter and apply it on data.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
inverse_transform(X)	Backproject the RESS filtered data to the sensors space.
set_output(*[, transform])	Set output container.
set_params(**params)	Set the parameters of this estimator.
transform(X)	Project data using the learned RESS filter.

__init__(sfreq: int, peak_freq: float, neig_freq: float = 1, peak_width: float = 0.5, neig_width: float = 1, n_keep: int = 1, gamma: float = 0.01, compute_unmixing: bool = False)

fit(X, y=None)

Learn a RESS filter.

Xnp.array (n_samples, n_chans, n_trials)

Follow MNE format

y(ignored)

Ignored parameter.

Returns:

self – RESS class instance.

Return type:

object

fit_transform(X, y=None)

Compute RESS filter and apply it on data.

inverse_transform(X)

Backproject the RESS filtered data to the sensors space.

transform(X)

Project data using the learned RESS filter.