mne_denoise.dss.iterative_dss#

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

Extract multiple DSS components using iterative (nonlinear) algorithm.

This implements the Iterative DSS algorithm from Särelä & Valpola (2005) [1]. Unlike linear DSS which uses a closed-form eigendecomposition, iterative DSS uses fixed-point iteration with a nonlinear denoising function.

Algorithm Overview:

1. Center data: X = X - mean(X)
2. Whiten data: X_white = Whitener @ X  (identity covariance)
3. Extract components using deflation or symmetric method:

   Deflation (sequential):
       For each component i = 1..n_components:
           w_i = iterative_dss_one(X_deflated)
           Orthogonalize w_i against w_1..w_{i-1}
           Deflate: X_deflated -= w_i @ w_i.T @ X_deflated

   Symmetric (parallel):
       Initialize W = [w_1, ..., w_n] randomly
       Repeat until converged:
           Update all w_i simultaneously
           W = symmetric_orthogonalize(W)

4. Convert filters to sensor space: filters = W @ Whitener

Parameters:

data (ndarray, shape (n_channels, n_times) or (n_epochs, n_channels, n_times)) – Input multichannel data.
denoiser (callable or NonlinearDenoiser) – Nonlinear denoising function f(s) → s_denoised. Examples: TanhMaskDenoiser, GaussDenoiser, WienerMaskDenoiser.
n_components (int) – Number of components to extract.
method ({'deflation', 'symmetric'}) –
Component extraction method:
- 'deflation': Extract one-by-one, orthogonalizing after each. More stable, but order-dependent.
- 'symmetric': Update all simultaneously, then orthogonalize. Order-independent, may be less stable.
Default 'deflation'.
rank (int, optional) – Rank for whitening. If None, auto-determined from eigenvalue threshold.
reg (float) – Regularization for whitening eigenvalue cutoff. Default 1e-9.
max_iter (int) – Maximum iterations per component. Default 100.
tol (float) – Convergence tolerance. Default 1e-6.
w_init (ndarray, shape (n_components, n_whitened), optional) – Initial weight matrix. If None, random initialization.
verbose (bool) – Print convergence info. Default False.
alpha (float or callable, optional) – Signal normalization factor (see iterative_dss_one).
beta (float or callable, optional) – Newton step parameter (see iterative_dss_one).
gamma (float or callable, optional) – Learning rate / relaxation (see iterative_dss_one).

Returns:

filters (ndarray, shape (n_components, n_channels)) – DSS spatial filters in sensor space. Apply as: sources = filters @ data.
sources (ndarray, shape (n_components, n_times)) – Extracted source time series.
patterns (ndarray, shape (n_channels, n_components)) – Spatial patterns for visualization / reconstruction. Note: These are returned in original sensor units (not normalized), satisfying the identity \(X_{recon} = patterns @ sources\).
convergence_info (ndarray, shape (n_components, 2)) – [n_iterations, converged] for each component.

Examples

>>> import numpy as np
>>> from mne_denoise.dss import iterative_dss
>>> from mne_denoise.dss.denoisers import TanhMaskDenoiser
>>> # Basic usage with numpy array
>>> data = np.random.randn(10, 1000)
>>> denoiser = TanhMaskDenoiser()
>>> filters, sources, patterns, _ = iterative_dss(
...     data, denoiser, n_components=2, method="symmetric"
... )