mne_denoise.ssa.local_ssa_clean_channel#

mne_denoise.ssa.local_ssa_clean_channel(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, return_info: bool = False) → ndarray | tuple[ndarray, dict[str, Any]][source]#

Remove a locally reconstructed high-energy artifact from one channel.

Delay vectors are clustered, projected onto cluster-specific subspaces selected by MDL, returned to their temporal positions, and averaged along trajectory-matrix anti-diagonals.

Parameters:

  • x (array-like, shape (n_times,)) – Finite scalar time series.

  • window_length (int | None, default=None) – Delay-vector dimension in samples. It must satisfy the canonical SSA orientation and is mutually exclusive with window_seconds.

  • window_seconds (float | None, default=None) – Delay-vector duration in seconds. It requires sfreq and is 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. "auto" searches downward from the largest admissible value until the reliability conditions are met.

  • max_clusters (int, default=10) – Upper bound for automatic cluster-count selection. The source does not prescribe this computational bound.

  • 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. None permits nondeterministic initialization.

  • return_info (bool, default=False) – If True, also return clustering, eigenspectrum, MDL, and reconstructed artifact diagnostics.

Returns:

  • x_clean (ndarray, shape (n_times,)) – Residual after subtracting the local-subspace reconstruction.

  • info (dict) – Returned only when return_info=True. Contains the artifact, trajectory shape, cluster labels and sizes, covariance eigenvalues, MDL scores, and selected subspace dimensions.

Raises:

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

  • ValueError – If x, the embedding, or the requested clustering is invalid, or no reliable automatic clustering can be found.

See also

compute_local_ssa

Apply local SSA independently across channels.

LocalSingularSpectrumAnalysis

MNE/scikit-learn estimator interface.

Notes

The method assumes that coherent, high-energy structure belongs to the artifact and that desired EEG is represented more strongly in the residual subspace. This assumption can fail for genuine rhythmic neural activity. K-means initialization, the maximum cluster count, and zero-eigenvalue regularization are explicit numerical choices because the source does not uniquely specify them [1].

References

[1]

Teixeira, A. R., Tome, A. M., Lang, E. W., Gruber, P., & Martins da Silva, A. (2006). Automatic removal of high-amplitude artefacts from single-channel electroencephalograms. Computer Methods and Programs in Biomedicine, 83, 125-138. https://doi.org/10.1016/j.cmpb.2006.06.003

Examples

>>> import numpy as np
>>> from mne_denoise.ssa import local_ssa_clean_channel
>>> time = np.arange(300) / 100.0
>>> observed = np.sin(2 * np.pi * 0.5 * time)
>>> cleaned = local_ssa_clean_channel(
...     observed, window_length=20, n_clusters=2, random_state=0
... )
>>> cleaned.shape
(300,)