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

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