mne_denoise.sspsir.SSPSIR

class mne_denoise.sspsir.SSPSIR(*, n_components=None, forward=None, art_window=None, blend: str = 'auto', high_pass: float = 100.0, M=None, smooth_length: float = 0.01, sfreq=None, n_dipoles: int = 5000, verbose: bool | str | int | None = None)

Source-informed signal-space projection for TMS-evoked muscle artifact removal.

SSP-SIR projects out an artifact subspace, reconstructs through a lead field, and blends the projected and unprojected reconstructions around the artifact window.

Parameters:

n_componentsint or float

Number of artifact components, or high-frequency variance fraction in (0, 1).

forwardmne.Forward or None, default=None

Optional explicit forward solution. For compatible EEG MNE input with a montage, None uses a spherical fallback; MEG or mixed-channel MNE input and NumPy input require an explicit forward.

art_windowtuple of float or None, default=None

Artifact interval (tmin, tmax) in seconds; None derives a high-frequency envelope from the epoch.

blend{“auto”, “constant”}, default=”auto”

Crossfade rule.

high_passfloat, default=100.0

High-pass cutoff in Hz for artifact-subspace estimation.

Mint or None, default=None

Source-informed reconstruction rank; None uses data rank minus artifact rank.

smooth_lengthfloat, default=0.010

Crossfade transition width in seconds.

sfreqfloat or None, default=None

Sampling frequency for NumPy input.

n_dipolesint, default=5000

Dipoles for a generated spherical EEG lead field.

verbosebool, str, int, or None, default=None

Logging level.

Attributes:

leadfield_ndarray

Lead field used during fitting.

artifact_topographies_ndarray

Fitted artifact subspace.

operator_ndarray

Projected reconstruction operator.

operator_orig_ndarray

Unprojected reconstruction operator.

kernel_ndarray

Temporal crossfade weights.

n_components_int

Effective artifact-component count.

M_int

Effective reconstruction rank.

singular_values_ndarray

Singular values used for artifact-subspace selection.

projs_list of mne.Projection

Artifact directions when fitted on named MNE data.

See also

mne_denoise.sound.SOUND

Another forward-model-based denoising method with a different noise model.

Notes

NumPy input uses (n_channels, n_times) or (n_epochs, n_channels, n_times). MNE Raw, Epochs, and Evoked inputs are supported and returned without mutation. The artifact-window reconstruction is time-locked to the fitted data [1][2][3][4].

References

[1]

Tuomas P. Mutanen, Matleena Kukkonen, Jaakko O. Nieminen, Matti Stenroos, Jukka Sarvas, and Risto J. Ilmoniemi. Recovering tms-evoked eeg responses masked by muscle artifacts. NeuroImage, 139:157–166, 2016. doi:10.1016/j.neuroimage.2016.05.028.

[2]

Tuomas P. Mutanen, Johanna Metsomaa, Matilda Makkonen, Giuseppe Varone, Laura Marzetti, and Risto J. Ilmoniemi. Source-based artifact-rejection techniques for tms–eeg. Journal of Neuroscience Methods, 382:109693, 2022. doi:10.1016/j.jneumeth.2022.109693.

[3]

Tuomas P. Mutanen, Ida Ilmoniemi, Iiris Atti, Johanna Metsomaa, and Risto J. Ilmoniemi. A simulation study: comparing independent component analysis and signal-space projection–source-informed reconstruction for rejecting muscle artifacts evoked by transcranial magnetic stimulation. Frontiers in Human Neuroscience, 18:1324958, 2024. doi:10.3389/fnhum.2024.1324958.

[4]

Julio C. Hernandez-Pavon, Dimitris Kugiumtzis, Christoph Zrenner, Vasilios K. Kimiskidis, and Johanna Metsomaa. Removing artifacts from tms-evoked eeg: a methods review and a unifying theoretical framework. Journal of Neuroscience Methods, 376:109591, 2022. doi:10.1016/j.jneumeth.2022.109591.

Examples

A preloaded MNE Epochs object with a compatible EEG montage and a sampling rate whose Nyquist frequency is above the configured high-pass cutoff can use the spherical fallback:

from mne_denoise.sspsir import SSPSIR

model = SSPSIR(
    n_components=3,
    art_window=(0.005, 0.050),
)
clean = model.fit_transform(epochs)

fit(X, y=None, *, verbose: bool | str | int | None = None)

Fit the SSP-SIR artifact subspace and reconstruction operators.

Parameters:

Xndarray, Raw, Epochs, or Evoked

EEG data used for fitting. NumPy input is channel-first.

yNone, default=None

Ignored for scikit-learn compatibility.

verbosebool, str, int, or None, default=None

Logging level.

Returns:

SSPSIR

The fitted estimator.

transform(X, *, verbose: bool | str | int | None = None)

Apply the fitted SSP-SIR operators.

Parameters:

Xndarray, Raw, Epochs, or Evoked

Data with the fitted channel layout and, for time-varying blending, time axis.

verbosebool, str, int, or None, default=None

Logging level.

Returns:

same type as X

Reconstructed data; non-fitted MNE channels are preserved.