pymcssa 0.1.0

A Monte Carlo Singular Spectrum Analysis (MCSSA) package for time series analysis.

Monte Carlo Singular Spectrum Analysis (MCSSA)

A Python implementation of Monte Carlo Singular Spectrum Analysis (MCSSA), a rigorous spectral-decomposition and hypothesis-testing toolkit for researchers working in the climate and geophysical sciences. It builds upon the foundational work of Myles R. Allen and Leonard A. Smith, and has been further extended by Andreas Groth and Michael Ghil.

---

Status

This package is experimental.

• Features may be incomplete
• No guarantees of backward compatibility
• Not actively maintained

Overview

Singular Spectrum Analysis (SSA) decomposes a univariate time series into interpretable components, trend, oscillations, and noise without requiring a predefined model.

Monte Carlo SSA (MCSSA) extends SSA by generating an ensemble of surrogate datasets based on a red-noise (AR(1)) null hypothesis, which is the standard statistical null model in climate dynamics and geophysical signal analysis.

By comparing the eigenspectrum of the observed data to that of AR(1) surrogate series, MCSSA identifies oscillatory components that are statistically significant beyond what would be expected from background red noise.

⚠️ Note: MCSSA assumes that the null hypothesis of the data follows an AR(1) process. A valid and widely used assumption in climate, atmospheric, and oceanic time series analysis. It may not be suitable for processes with fundamentally different stochastic structures.

This package provides:

• SSA decomposition and reconstruction
• MCSSA hypothesis testing with three approaches:
  1. Data-basis testing (mcssa_basic)
  2. Ensemble-basis testing (mcssa_ensemble)
  3. Procrustes-aligned testing (mcssa_procrustes)
• AR(1) parameter estimation and surrogate generation
• Publication-ready statistical output

Theoretical Background

1. Trajectory Matrix (Embedding)

Given a time series $x_t$ of length $n$ and embedding dimension $m$:

$$ \mathbf{X} = \begin{bmatrix} x_1 & x_2 & \cdots & x_m \ x_2 & x_3 & \cdots & x_{m+1} \ \vdots & \vdots & \ddots & \vdots \ x_{n-m+1} & x_{n-m+2} & \cdots & x_n \end{bmatrix} $$

This $(n-m+1)\times{m}$ matrix represents overlapping windows of the time series.

---

2. Covariance Matrix and Eigen-Decomposition

The covariance matrix summarizes how lagged versions of the time series co-vary:

$$ \mathbf{C} = \frac{1}{n-m+1} \mathbf{X}^T \mathbf{X} $$

Each element $C_{ij}$ measures the covariance between time-lagged copies of the signal, separated by $( |i-j| )$ timesteps.

Why Eigen-Decomposition?

To extract dominant and independent patterns of variability, we solve the eigenvalue problem:

$$ \mathbf{C} \mathbf{e}_k = \lambda_k \mathbf{e}_k $$

This operation identifies orthogonal directions — called Empirical Orthogonal Functions (EOFs) — that maximize variance of the lagged trajectories while maintaining mutual orthogonality.

Formally, each EOF $\mathbf{e}_k$ is obtained by solving:

$$ \max_{\mathbf{e}_k} , \mathbf{e}_k^T \mathbf{C} \mathbf{e}_k \quad \text{subject to} \quad \mathbf{e}_k^T \mathbf{e}_k = 1 $$

The solution yields:

• $\lambda_k$: the variance explained by mode ( k )
• $\mathbf{e}_k$: the orthogonal spatial (temporal-lag) pattern of that mode

Hence, SSA performs a variance-maximizing decomposition in the space of time-delayed embeddings,
analogous to Principal Component Analysis (PCA) — but applied to lagged copies of the original time series.

This allows one to separate:

• Slowly varying trends
• Quasi-periodic oscillations
• High-frequency (noise-like) components

3. AR(1) Null Model

Under the red-noise null hypothesis, the process is modeled as:

$$ x_t = \gamma x_{t-1} + \alpha w_t, \quad w_t \sim \mathcal{N}(0,1) $$

where:

• $\gamma$ = lag-1 autocorrelation coefficient
• $\alpha$= noise scaling parameter

---

4. Monte Carlo Testing

Generate $N_s$ surrogate realizations, apply SSA to each, and collect their eigenvalues $\lambda_k^{(i)}$. For each SSA mode $k$, estimate confidence bounds:

$$ \text{Upper}(k) = \text{Percentile}{97.5}{\lambda_k^{(i)}}, \quad \text{Lower}(k) = \text{Percentile}{2.5}{\lambda_k^{(i)}} $$

Modes of the real data whose eigenvalues exceed these bounds are considered significant.

Installation

You can install the package in two ways, depending on your use case:

---

Option 1 — Direct install from GitHub (recommended for users)

If you simply want to use the package without modifying the source:

pip install git+https://github.com/sayan-geoDL/pymcssa.git

This command will automatically fetch the latest version from GitHub and install all required dependencies.

Option 2 — Local editable install (recommended for development)

If you plan to modify the code or contribute:

git clone git+https://github.com/sayan-geoDL/pymcssa.git
cd pymcssa
pip install -e .

The -e flag installs the package in editable mode, meaning any local code changes will take effect immediately without reinstalling.

Optional: Verify the installation

After installation, open a Python terminal and run:

import pymcssa
print(pymcssa.__version__)

If no errors appear, the package has been successfully installed!

Quickstart Example

import numpy as np
from pymcssa import MCSSA

# Generate synthetic AR(1) red noise
np.random.seed(0)
n = 500
gamma = 0.6
data = np.zeros(n)
for t in range(1, n):
    data[t] = gamma * data[t-1] + np.random.randn()

# Run Monte Carlo SSA
m = 40
mc = MCSSA(data, m)
results = mc.mcssa_basic(up_perc=97.5, down_perc=2.5, ns=500)

print("Data eigenvalues:", results["data_eigenvalues"][:5])
print("Upper 97.5% bounds:", results["upper_confidence"][:5])

---

Available Classes

AR1estimator

Provides AR(1) parameter estimation and surrogate generation.

Key methods:

• gambar(max_iter=1000) → estimate lag-1 autocorrelation
• alph(max_iter=1000) → estimate noise std. dev.
• ar1_model(alpha, gamma) → generate AR(1) surrogate series

SSA

Implements Singular Spectrum Analysis for time series decomposition into:

• Empirical Orthogonal Functions (EOFs)
• Principal Components (PCs)
• Reconstructed Components (RCs)

MCSSA

Builds on AR1estimator to provide:

• mcssa_basic() → data-basis testing
• mcssa_ensemble() → ensemble mean basis testing
• mcssa_procrustes() → Procrustes-aligned testing

Example Output

Each MCSSA method returns a dictionary, for example:

{
  "data_eigenvalues": ndarray,
  "upper_confidence": list,
  "lower_confidence": list,
  "gamma": float,
  "alpha": float,
  "spreads": ndarray,
  "surrogates": ndarray  # optional
}

---

Testing and Dependencies

Dependencies

• NumPy
• math
• (Optional) PyTest

Testing and Validation (for developers)

This package includes a comprehensive test suite to ensure the numerical stability and correctness of all SSA and MCSSA methods.
The tests validate decomposition accuracy, eigenvalue consistency, reconstruction fidelity, and statistical behavior of surrogate-based hypothesis testing.

Running All Tests

From the package root directory:

pytest -v

Included Test Modules

tests/test_ssa.py

Validates the Singular Spectrum Analysis (SSA) core functionality.

Tests include:

• ✅ test_ssa_basic_run — checks SSA output consistency and expected keys
• ✅ test_ssa_variance_explained_sum — ensures eigenvalue variance sums to 100%
• ✅ test_ssa_reconstruction_dimensions — verifies reconstructed matrix shape
• ✅ test_ssa_orthogonality_of_eofs — confirms orthonormal EOF basis
• ✅ test_ssa_invalid_dimension_raises — confirms error on non-1D data
• ✅ test_ssa_invalid_window_too_large — raises error if m > len(data)

tests/test_mcssa_methods.py

Validates the Monte Carlo SSA (MCSSA) routines for red-noise significance testing.

Tests include:

• ✅ test_mcssa_basic_output — validates main output keys and shapes
• ✅ test_mcssa_ensemble_output — ensures ensemble averaging returns consistent results
• ✅ test_mcssa_procrustes_output — checks Procrustes-aligned variant
• ✅ test_invalid_parameters — verifies input parameter error handling

Example Output

Typical pytest output (abridged):

=========================================================================================== test session starts ============================================================================================
platform linux -- Python 3.12.7, pytest-7.4.4
collected 10 items                                                                                                                                                                             

tests/test_mcssa_methods.py::test_mcssa_basic_output PASSED                                                                                                                                          [ 10%]
tests/test_mcssa_methods.py::test_mcssa_ensemble_output PASSED                                                                                                                                       [ 20%]
tests/test_mcssa_methods.py::test_mcssa_procrustes_output PASSED                                                                                                                                     [ 30%]
tests/test_mcssa_methods.py::test_invalid_parameters PASSED                                                                                                                                          [ 40%]
tests/test_ssa.py::test_ssa_basic_run PASSED                                                                                                                                                         [ 50%]
tests/test_ssa.py::test_ssa_variance_explained_sum PASSED                                                                                                                                            [ 60%]
tests/test_ssa.py::test_ssa_reconstruction_dimensions PASSED                                                                                                                                         [ 70%]
tests/test_ssa.py::test_ssa_orthogonality_of_eofs PASSED                                                                                                                                             [ 80%]
tests/test_ssa.py::test_ssa_invalid_dimension_raises PASSED                                                                                                                                          [ 90%]
tests/test_ssa.py::test_ssa_invalid_window_too_large PASSED                                                                                                                                          [100%]

============================================================================================ 10 passed in 0.56s ============================================================================================

---

References

• Groth, A., & Ghil, M. (2015). Monte Carlo Singular Spectrum Analysis (SSA) Revisited: Detecting Oscillator Clusters in Multivariate Datasets. Journal of Climate, 28 (19), 7873‑7893. doi:10.1175/JCLI‑D‑15‑0100.1
  Publisher Link | Google Scholar
• Allen, M. R., & Smith, L. A. (1996). Monte Carlo SSA: Detecting irregular oscillations in the presence of coloured noise. Journal of Climate, 9(12), 3373‑3404. doi:10.1175/1520‑0442(1996)009<3373:MCSDIO>2.0.CO;2 Publisher Link

---

📖 Documentation

Full documentation for pymcssa is available online at:

---

📄 License

Released under the MIT License.
See LICENSE for details.

---

📬 Contact

Sayan Jana
Affiliation: PhD. Student IISC, CAOS
Email: [e-mail] GitHub: https://github.com/sayan-geoDL