mne_denoise.ssa.ssa_decompose#

mne_denoise.ssa.ssa_decompose(x: ndarray, window_length: int | None = None, *, window_seconds: float | None = None, sfreq: float | None = None, max_window: int = 100) → tuple[ndarray, dict[str, Any]][source]#

Decompose a one-dimensional series into additive Basic SSA components.

Parameters:

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

  • window_length (int | None, default=None) – Embedding dimension in samples. It must satisfy 2 <= window_length <= (n_times + 1) // 2. If None, an automatic value is selected.

  • window_seconds (float | None, default=None) – Embedding duration in seconds. It is mutually exclusive with window_length and requires sfreq.

  • sfreq (float | None, default=None) – Sampling frequency in Hz. It converts window_seconds to samples and sets the automatic window to at most 0.5 seconds.

  • max_window (int, default=100) – Maximum embedding dimension used by automatic selection.

Returns:

  • components (ndarray, shape (window_length, n_times)) – Elementary reconstructed series ordered by decreasing singular value. Their sum reconstructs x to floating-point precision.

  • info (dict) – Resolved embedding dimension, trajectory-matrix shape, singular values, and numerical rank.

Raises:

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

  • ValueError – If x is not a finite one-dimensional series or the requested embedding is invalid.

See also

ssa_w_correlation

Measure weighted component separability.

ssa_clean_channel

Group and subtract components by dominant frequency.

Notes

Direct SVD of the trajectory matrix is algebraically equivalent to eigendecomposition of its lag-covariance matrix, without squaring the condition number. Anti-diagonal averaging includes the smaller edge multiplicities described for Basic SSA [1].

References

[1]

Golyandina, N., & Zhigljavsky, A. (2013). Singular Spectrum Analysis for Time Series. Springer. https://doi.org/10.1007/978-3-642-34913-3