mne_denoise.ssa.compute_local_ssa#

mne_denoise.ssa.compute_local_ssa(X: ndarray, window_length: int | None = None, *, window_seconds: float | None = None, sfreq: float | None = None, n_clusters: int | str = 'auto', max_clusters: int = 10, max_window: int = 100, random_state: int | None = 0) → tuple[ndarray, dict[str, Any]][source]#

Apply local SSA independently to every input channel.

This is the channel-first functional interface to local_ssa_clean_channel(). It returns both cleaned data and the local model diagnostics required to assess the reconstruction.

Parameters:

  • X (array-like, shape (n_channels, n_times)) – Finite channel-first data. Channels are never mixed.

  • window_length (int | None, default=None) – Delay-vector dimension in samples. If None, it is selected automatically.

  • window_seconds (float | None, default=None) – Delay-vector duration in seconds, mutually exclusive with window_length.

  • sfreq (float | None, default=None) – Sampling frequency in Hz. Required for window_seconds and used by automatic window selection when available.

  • n_clusters (int | "auto", default="auto") – Number of delay-vector clusters, or automatic reliable selection.

  • max_clusters (int, default=10) – Upper bound for automatic cluster-count selection.

  • max_window (int, default=100) – Maximum delay-vector dimension used by automatic window selection.

  • random_state (int | None, default=0) – Random seed passed to k-means.

Returns:

  • X_clean (ndarray, shape (n_channels, n_times)) – Residual data after independently subtracting each channel’s local reconstruction.

  • info (dict) – Per-channel cluster counts, cluster sizes, selected dimensions, covariance eigenvalues, MDL scores, and reconstructed artifacts.

Raises:

  • TypeError – If a scalar parameter has an invalid type.

  • ValueError – If X, the embedding, or the requested clustering is invalid.

See also

local_ssa_clean_channel

Canonical single-channel implementation.

LocalSingularSpectrumAnalysis

MNE/scikit-learn estimator interface.

Notes

This function calls local_ssa_clean_channel() independently for every channel. It is repeated univariate local SSA, not multivariate SSA. No spatial covariance or cross-channel trajectory matrix is estimated.

Examples

>>> import numpy as np
>>> from mne_denoise.ssa import compute_local_ssa
>>> time = np.arange(300) / 100.0
>>> observed = np.vstack(
...     [np.sin(2 * np.pi * 0.5 * time), np.sin(2 * np.pi * 1.0 * time)]
... )
>>> cleaned, info = compute_local_ssa(
...     observed, window_length=20, n_clusters=2, random_state=0
... )
>>> cleaned.shape
(2, 300)
>>> info["n_clusters"].shape
(2,)