# Singular Spectrum Analysis Library (SSALib)
[](https://github.com/ADSCIAN/ssalib/actions/workflows/python-tests.yml)
[](https://www.python.org)
[](https://github.com/ADSCIAN/ssalib/actions)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://pypi.org/project/ssalib/)
> [!NOTE]
> This repository contains a beta version of SSALib. User may use the issue
> tracker to provide feedback.
## Overview
The Singular Spectrum Analysis Library (SSALib) is a Python package
implementing the Singular Spectrum Analysis (SSA) univariate timeseries
decomposition technique. It relies on different Singular Value Decomposition
(SVD) methods from existing Python scientific packages and provides a convenient
API along with plotting capabilities.
## Key Features
- Univariate SSA implementation with both Broemhead & King and Vautard and Ghil
approaches
- Multiple SVD solver options (NumPy, SciPy, scikit-learn)
- Monte Carlo SSA for significance testing
- Built-in visualization tools for analysis
- Include example datasets
- Comprehensive test coverage
- Type-annotated codebase
## Quick Start
### Requirements
- Python ≥ 3.9
- NumPy
- SciPy
- Pandas
- Matplotlib
- Scikit-learn
- Statsmodels
### Installation
Use
```bash
pip install git+https://github.com/ADSCIAN/ssalib.git
```
or
```bach
pip install vassal==0.1.0b1
```
### Basic Usage
```python
from ssalib import SingularSpectrumAnalysis
from ssalib.datasets import load_sst
# Load example data
ts = load_sst()
# Create SSA instance and decompose
ssa = SingularSpectrumAnalysis(ts)
ssa.decompose()
# Visualize results
fig, ax = ssa.plot(kind='values')
# Reconstruct groups
ssa.reconstruct(groups={'trend': [0, 1], 'seasonality': [2, 3]})
# Export
df_ssa = ssa.to_frame()
```
### Available Datasets
| Dataset | Loading Function | Description | Time Range | Source | License |
|-----------|--------------------|----------------------------------------------------------------------------|--------------------------|-------------------------------------------------------------------|-----------|
| Mortality | `load_mortality()` | Daily counts of deaths in Belgium. | 1992-01-01 to 2023-12-31 | [STATBEL](https://statbel.fgov.be/en/open-data/number-deaths-day) | Open Data |
| SST | `load_sst()` | Monthly mean sea surface temperature globally between 60° North and South. | 1982-01-01 to 2023-12-31 | [Climate Reanalyzer](https://climatereanalyzer.org/) | CC-BY |
| Sunspots | `load_sunspots()` | Monthly mean total sunspot number. | 1749-01 to 2023-12 | [Royal Observatory of Belgium](https://www.sidc.be/SILSO/) | CC-BY-NC |
### Available SVD Methods
SSALib supports multiple SVD solvers:
| Solver Name | Underlying Method | Status |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|-----------|
| `numpy_standard` | [`numpy.linalg.svd`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.svd.html) | Default |
| `scipy_standard` | [`scipy.linalg.svd`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.svd.html) | Available |
| `scipy_sparse` | [`scipy.sparse.linalg.svds`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.svds.html) | Available |
| `sklearn_randomized` | [`sklearn.utils.extmath.randomized_svd`](https://scikit-learn.org/stable/modules/generated/sklearn.utils.extmath.randomized_svd.html) | Available |
Select the solver with the `svd_solver` argument.
```python
from ssalib import SingularSpectrumAnalysis
from ssalib.datasets import load_sst
# Load example data
ts = load_sst()
# Create SSA instance with solver 'sklearn_randomized'
ssa = SingularSpectrumAnalysis(ts, svd_solver='sklearn_randomized')
```
### Available Visualizations
| `kind` | Description | Decomposition Required | Reconstruction Required |
|---------------|-------------------------------------------------------------------------------|:----------------------:|:-----------------------:|
| `matrix` | Plot the matrix or its group reconstruction | Optional | Optional |
| `paired` | Plot pairs (x,y) of successive left-eigenvectors | Yes | No |
| `periodogram` | Plot periodogram associated with eigenvectors | Yes | No |
| `timeseries` | Plot original, preprocessed, or reconstructed time series | Optional | Optional |
| `values` | Plot the singular values ranked by value norm or dominant component frequency | Yes | No |
| `vectors` | Plot the left eigen vectors | Yes | No |
| `wcorr` | Plot the weighted correlation matrix | Yes | No |
Pass the `kind` argument to the `SingularSpectrumAnalysis.plot` method.
## Documentation
For more in-depth examples and tutorials, check the Jupyter notebooks in the
`notebooks` folder:
- [Tutorial 1: Introduction to SSA](/notebooks/01_basic_ssa_introduction.ipynb)
- [Tutorial 2: Plotting Guide](/notebooks/02_ssa_plotting_guide.ipynb)
- [Tutorial 3: SVD Matrix Construction and Window Sizes](/notebooks/03_ssa_svd_matrices.ipynb)
- [Tutorial 4: Comparison of SVD Solvers and Speed Performances](/notebooks/04_svd_solver_comparison.ipynb)
In more advanced tutorials, we cover:
- [A1: Testing Significance with `MonteCarloSSA`](/notebooks/A1_montecarlo_ssa.ipynb)
## References
The main references used to develop SSALib were:
1. Golyandina, N., & Zhigljavsky, A. (2020). Singular Spectrum Analysis for Time
Series. Berlin, Heidelberg:
Springer. https://doi.org/10.1007/978-3-662-62436-4
2. Hassani, H. (2007). Singular Spectrum Analysis: Methodology and Comparison.
Journal of Data Science, 5(2),
239–257. https://doi.org/10.6339/JDS.2007.05(2).396
3. Broomhead, D. S., & King, G. P. (1986). Extracting qualitative dynamics from
experimental data. Physica D: Nonlinear Phenomena, 20(2),
217–236. https://doi.org/10.1016/0167-2789(86)90031-X
4. Vautard, R., & Ghil, M. (1989). Singular spectrum analysis in nonlinear
dynamics, with applications to paleoclimatic time series. Physica D:
Nonlinear Phenomena, 35(3). https://doi.org/10.1016/0167-2789(89)90077-8
5. Allen, M. R., & Smith, L. A. (1996). Monte Carlo SSA: Detecting irregular
oscillations in the Presence of Colored Noise. Journal of Climate, 9(12),
3373–3404.
[https://doi.org/10.1175/1520-0442(1996)009<3373:MCSDIO>2.0.CO;2](https://doi.org/10.1175/1520-0442(1996)009<3373:MCSDIO>2.0.CO;2)
## How to Cite
Awaiting the release of the first non-beta version, you can refer to SSALib
using:
```bibtex
@software{ssalib2024,
author = {Delforge, Damien and Alonso, Alice},
title = {{SSALib}: A {Python} Package for {Singular Spectrum Analysis}},
year = {2024},
version = {0.1.0b1},
url = {https://github.com/ADSCIAN/ssalib}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ADSCIAN/ssalib",
"name": "ssalib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "singular spectrum analysis, time series, decomposition",
"author": "Alice Alonso",
"author_email": "Damien Delforge <damien.delforge@adscian.be>",
"download_url": "https://files.pythonhosted.org/packages/b1/2a/b73dd32e8fc1dc47a0eeb3ccf70cca4e22ea96883e72924492ac2cc338fd/ssalib-0.1.0b1.tar.gz",
"platform": null,
"description": "# Singular Spectrum Analysis Library (SSALib)\n\n[](https://github.com/ADSCIAN/ssalib/actions/workflows/python-tests.yml)\n[](https://www.python.org)\n[](https://github.com/ADSCIAN/ssalib/actions)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://pypi.org/project/ssalib/)\n\n\n> [!NOTE]\n> This repository contains a beta version of SSALib. User may use the issue\n> tracker to provide feedback. \n\n## Overview\n\nThe Singular Spectrum Analysis Library (SSALib) is a Python package\nimplementing the Singular Spectrum Analysis (SSA) univariate timeseries\ndecomposition technique. It relies on different Singular Value Decomposition\n(SVD) methods from existing Python scientific packages and provides a convenient\nAPI along with plotting capabilities.\n\n\n\n## Key Features\n\n- Univariate SSA implementation with both Broemhead & King and Vautard and Ghil\n approaches\n- Multiple SVD solver options (NumPy, SciPy, scikit-learn)\n- Monte Carlo SSA for significance testing\n- Built-in visualization tools for analysis\n- Include example datasets\n- Comprehensive test coverage\n- Type-annotated codebase\n\n## Quick Start\n\n### Requirements\n\n- Python \u2265 3.9\n- NumPy\n- SciPy\n- Pandas\n- Matplotlib\n- Scikit-learn\n- Statsmodels\n\n### Installation\n\nUse\n```bash\npip install git+https://github.com/ADSCIAN/ssalib.git\n```\nor\n```bach\npip install vassal==0.1.0b1\n```\n\n### Basic Usage\n\n```python\nfrom ssalib import SingularSpectrumAnalysis\nfrom ssalib.datasets import load_sst\n\n# Load example data\nts = load_sst()\n\n# Create SSA instance and decompose\nssa = SingularSpectrumAnalysis(ts)\nssa.decompose()\n\n# Visualize results\nfig, ax = ssa.plot(kind='values')\n\n# Reconstruct groups\nssa.reconstruct(groups={'trend': [0, 1], 'seasonality': [2, 3]})\n\n# Export\ndf_ssa = ssa.to_frame()\n```\n\n### Available Datasets\n\n| Dataset | Loading Function | Description | Time Range | Source | License |\n|-----------|--------------------|----------------------------------------------------------------------------|--------------------------|-------------------------------------------------------------------|-----------|\n| Mortality | `load_mortality()` | Daily counts of deaths in Belgium. | 1992-01-01 to 2023-12-31 | [STATBEL](https://statbel.fgov.be/en/open-data/number-deaths-day) | Open Data | \n| SST | `load_sst()` | Monthly mean sea surface temperature globally between 60\u00b0 North and South. | 1982-01-01 to 2023-12-31 | [Climate Reanalyzer](https://climatereanalyzer.org/) | CC-BY |\n| Sunspots | `load_sunspots()` | Monthly mean total sunspot number. | 1749-01 to 2023-12 | [Royal Observatory of Belgium](https://www.sidc.be/SILSO/) | CC-BY-NC |\n\n### Available SVD Methods\n\nSSALib supports multiple SVD solvers:\n\n| Solver Name | Underlying Method | Status |\n|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|-----------|\n| `numpy_standard` | [`numpy.linalg.svd`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.svd.html) | Default |\n| `scipy_standard` | [`scipy.linalg.svd`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.svd.html) | Available |\n| `scipy_sparse` | [`scipy.sparse.linalg.svds`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.svds.html) | Available |\n| `sklearn_randomized` | [`sklearn.utils.extmath.randomized_svd`](https://scikit-learn.org/stable/modules/generated/sklearn.utils.extmath.randomized_svd.html) | Available |\n\nSelect the solver with the `svd_solver` argument.\n\n```python\nfrom ssalib import SingularSpectrumAnalysis\nfrom ssalib.datasets import load_sst\n\n# Load example data\nts = load_sst()\n\n# Create SSA instance with solver 'sklearn_randomized'\nssa = SingularSpectrumAnalysis(ts, svd_solver='sklearn_randomized')\n```\n\n### Available Visualizations\n\n| `kind` | Description | Decomposition Required | Reconstruction Required |\n|---------------|-------------------------------------------------------------------------------|:----------------------:|:-----------------------:|\n| `matrix` | Plot the matrix or its group reconstruction | Optional | Optional |\n| `paired` | Plot pairs (x,y) of successive left-eigenvectors | Yes | No |\n| `periodogram` | Plot periodogram associated with eigenvectors | Yes | No |\n| `timeseries` | Plot original, preprocessed, or reconstructed time series | Optional | Optional |\n| `values` | Plot the singular values ranked by value norm or dominant component frequency | Yes | No |\n| `vectors` | Plot the left eigen vectors | Yes | No |\n| `wcorr` | Plot the weighted correlation matrix | Yes | No |\n\nPass the `kind` argument to the `SingularSpectrumAnalysis.plot` method.\n\n## Documentation\n\nFor more in-depth examples and tutorials, check the Jupyter notebooks in the\n`notebooks` folder:\n\n- [Tutorial 1: Introduction to SSA](/notebooks/01_basic_ssa_introduction.ipynb)\n- [Tutorial 2: Plotting Guide](/notebooks/02_ssa_plotting_guide.ipynb)\n- [Tutorial 3: SVD Matrix Construction and Window Sizes](/notebooks/03_ssa_svd_matrices.ipynb)\n- [Tutorial 4: Comparison of SVD Solvers and Speed Performances](/notebooks/04_svd_solver_comparison.ipynb)\n\nIn more advanced tutorials, we cover:\n- [A1: Testing Significance with `MonteCarloSSA`](/notebooks/A1_montecarlo_ssa.ipynb)\n\n## References\n\nThe main references used to develop SSALib were:\n\n1. Golyandina, N., & Zhigljavsky, A. (2020). Singular Spectrum Analysis for Time\n Series. Berlin, Heidelberg:\n Springer. https://doi.org/10.1007/978-3-662-62436-4\n2. Hassani, H. (2007). Singular Spectrum Analysis: Methodology and Comparison.\n Journal of Data Science, 5(2),\n 239\u2013257. https://doi.org/10.6339/JDS.2007.05(2).396\n3. Broomhead, D. S., & King, G. P. (1986). Extracting qualitative dynamics from\n experimental data. Physica D: Nonlinear Phenomena, 20(2),\n 217\u2013236. https://doi.org/10.1016/0167-2789(86)90031-X\n4. Vautard, R., & Ghil, M. (1989). Singular spectrum analysis in nonlinear\n dynamics, with applications to paleoclimatic time series. Physica D:\n Nonlinear Phenomena, 35(3). https://doi.org/10.1016/0167-2789(89)90077-8\n5. Allen, M. R., & Smith, L. A. (1996). Monte Carlo SSA: Detecting irregular \n oscillations in the Presence of Colored Noise. Journal of Climate, 9(12), \n 3373\u20133404. \n [https://doi.org/10.1175/1520-0442(1996)009<3373:MCSDIO>2.0.CO;2](https://doi.org/10.1175/1520-0442(1996)009<3373:MCSDIO>2.0.CO;2)\n\n\n## How to Cite\n\nAwaiting the release of the first non-beta version, you can refer to SSALib \nusing:\n\n```bibtex\n@software{ssalib2024,\n author = {Delforge, Damien and Alonso, Alice},\n title = {{SSALib}: A {Python} Package for {Singular Spectrum Analysis}},\n year = {2024},\n version = {0.1.0b1},\n url = {https://github.com/ADSCIAN/ssalib}\n}\n```\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Singular Spectrum Analysis Library (SSALib)",
"version": "0.1.0b1",
"project_urls": {
"Homepage": "https://github.com/ADSCIAN/ssalib"
},
"split_keywords": [
"singular spectrum analysis",
" time series",
" decomposition"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bfd0ee668cf5a4c6a713a06791ce8d7d1ba628d914d1bc604931ef1bc9d63732",
"md5": "a484251bffbcb26330bb4b085671596d",
"sha256": "da78b963cde6588d1792d1818fc981c705234c4b873fccbb22de47f7494b1de4"
},
"downloads": -1,
"filename": "ssalib-0.1.0b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a484251bffbcb26330bb4b085671596d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 115197,
"upload_time": "2024-11-28T19:21:22",
"upload_time_iso_8601": "2024-11-28T19:21:22.529175Z",
"url": "https://files.pythonhosted.org/packages/bf/d0/ee668cf5a4c6a713a06791ce8d7d1ba628d914d1bc604931ef1bc9d63732/ssalib-0.1.0b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b12ab73dd32e8fc1dc47a0eeb3ccf70cca4e22ea96883e72924492ac2cc338fd",
"md5": "ad8e2fd5f24df5813ef5d5c185e6f3b8",
"sha256": "29ba30e648c5eaee4826fdee9fbb424d8d4e52502452df9b2547e9feecb9f1f4"
},
"downloads": -1,
"filename": "ssalib-0.1.0b1.tar.gz",
"has_sig": false,
"md5_digest": "ad8e2fd5f24df5813ef5d5c185e6f3b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 129047,
"upload_time": "2024-11-28T19:21:24",
"upload_time_iso_8601": "2024-11-28T19:21:24.070980Z",
"url": "https://files.pythonhosted.org/packages/b1/2a/b73dd32e8fc1dc47a0eeb3ccf70cca4e22ea96883e72924492ac2cc338fd/ssalib-0.1.0b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 19:21:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ADSCIAN",
"github_project": "ssalib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ssalib"
}
JSON
