mne_denoise.dss.IterativeDSS#

class mne_denoise.dss.IterativeDSS(denoiser: Callable[[ndarray], ndarray], n_components: int, *, method: str = 'deflation', rank: int | None = None, reg: float = 1e-09, normalize_input: bool = True, max_iter: int = 100, tol: float = 1e-06, verbose: bool = False, alpha: float | Callable | None = None, beta: float | Callable | None = None, gamma: float | Callable | None = None, random_state: int | Generator | None = None)[source]#

Iterative (Nonlinear) Denoising Source Separation Transformer.

Implements Iterative DSS as a scikit-learn compatible transformer that fits natively on MNE-Python objects (Raw, Epochs) or numpy arrays.

Unlike linear DSS which uses closed-form eigendecomposition, Iterative DSS uses fixed-point iteration with a nonlinear denoising function, making it equivalent to FastICA when using ICA contrast functions (tanh, gauss, cube).

Parameters:

  • denoiser (callable or NonlinearDenoiser) – Nonlinear denoising function f(s) → s_denoised. Must be an instance of mne_denoise.dss.NonlinearDenoiser (e.g. TanhMaskDenoiser, WienerMaskDenoiser) or a callable.

  • n_components (int) – Number of components to extract.

  • method ({'deflation', 'symmetric'}) –

    Component extraction method:

    • 'deflation': Extract one-by-one, orthogonalizing after each.

    • 'symmetric': Update all simultaneously, then orthogonalize.

    Default 'deflation'.

  • rank (int, optional) – Rank for whitening. If None, auto-determined from eigenvalue threshold.

  • reg (float) – Regularization for whitening. Default 1e-9.

  • max_iter (int) – Maximum iterations per component. Default 100.

  • tol (float) – Convergence tolerance. Default 1e-6.

  • verbose (bool) – Print convergence info. Default False.

  • alpha (float or callable, optional) – Signal normalization factor applied after denoising.

  • beta (float or callable, optional) – Spectral shift (Newton step) for faster convergence. Use beta_tanh for TanhMaskDenoiser, beta_pow3 for cubic.

  • gamma (float or callable, optional) – Learning rate / relaxation parameter.

  • random_state (int, RandomState, Generator, optional) – Seed for random initialization.

filters_#

The spatial filters (un-mixing matrix). Apply as: sources = filters_ @ data.

Type:

ndarray, shape (n_components, n_channels)

patterns_#

The spatial patterns (mixing matrix). Reconstruct as: data = patterns_ @ sources.

Type:

ndarray, shape (n_channels, n_components)

sources_#

Extracted sources from fit data.

Type:

ndarray, shape (n_components, n_times)

convergence_info_#

[n_iterations, converged] for each component.

Type:

ndarray, shape (n_components, 2)

Examples

>>> from mne_denoise.dss import IterativeDSS
>>> from mne_denoise.dss.denoisers import TanhMaskDenoiser, beta_tanh
>>>
>>> # With numpy array
>>> dss = IterativeDSS(denoiser=denoiser, n_components=3)
>>> dss.fit(data)
>>> sources = dss.transform(data)
>>>
>>> # With MNE Raw object
>>> dss.fit(raw)
>>> sources = dss.transform(raw)

See also

DSS

Linear DSS transformer.

iterative_dss

Functional API.

__init__(denoiser: Callable[[ndarray], ndarray], n_components: int, *, method: str = 'deflation', rank: int | None = None, reg: float = 1e-09, normalize_input: bool = True, max_iter: int = 100, tol: float = 1e-06, verbose: bool = False, alpha: float | Callable | None = None, beta: float | Callable | None = None, gamma: float | Callable | None = None, random_state: int | Generator | None = None) → None[source]#

Methods

__init__(denoiser, n_components, *[, ...])

fit(X)

Compute Iterative DSS spatial filters.

fit_transform(X)

Fit and transform in one step.

get_normalized_patterns()

Get L2-normalized spatial patterns for visualization.

inverse_transform(sources)

Reconstruct data from sources.

transform(X)

Apply fitted filters to extract sources.