pyspi is a comprehensive python library for computing statistics of pairwise interactions (SPIs) from multivariate time-series (MTS) data.
The toolbox provides easy access to hundreds of methods for evaluating the relationship between pairs of time series, from simple statistics (like correlation) to advanced multi-step algorithms (like Granger causality).
The code is licensed under the GNU GPL v3 license (or later).
Feel free to reach out for help with real-world applications.
Feedback is much appreciated through issues, or pull requests.
Installation 📥
pyspi requires Python 3.11 or newer.
Upgrading from 2.x? Version 3.0 removes the Java/JIDT dependency and
changes the Calculator API. See CHANGELOG.md for the
migration table.
pip install pyspi
pyspi depends on a large scientific stack, so installing into a dedicated
environment is strongly recommended:
python -m venv .venv && source .venv/bin/activate
pip install pyspi
Developing on pyspi itself, with uv:
git clone https://github.com/DynamicsAndNeuralSystems/pyspi.git
cd pyspi
uv sync # runtime + dev dependencies from uv.lock
uv run pytest -q # fast test suite
Optional extras: .[tsfile] to load sktime/aeon .ts files, .[bench] for the
compute-cost benchmark suite in bench/.
For a more detailed guide, see the full documentation,
the troubleshooting guide,
and alternative installation options.
Getting Started 🚀
import numpy as np
import pyspi
from pyspi.calculator import Calculator
dataset = np.random.randn(5, 500) # 5 processes, 500 observations
calc = Calculator(dataset=dataset) # z-scores each process by default
calc.compute() # compute every SPI
calc.table # rows = processes, columns = (SPI, process)
calc.table["cov_EmpiricalCovariance"] # one SPI's 5x5 matrix
calc.save("results.npz") # canonical on-disk format
pyspi.load_table("results.npz") # round-trips exactly
Results are stored as an (n_spis, M, M) array plus the SPI and process names,
which is the data's natural shape. .csv is also accepted for eyeballing small
results, but it is one-way and impractical for the full SPI set.
Or from the command line, writing a results table next to your data:
python -m pyspi compute --data ts.npy --config fast --n-jobs 4 --output results.npz
Try it on a bundled example dataset:
from pyspi.data import load_dataset, available_datasets
available_datasets() # forex, cml, standard_normal
calc = Calculator(dataset=load_dataset("forex"), config="fabfour")
calc.compute()
forex is quantised: every one of its seven processes contains repeated
values (24–212 distinct values across 250 observations). Consequently, all
KSG/kraskov variants refuse it under pyspi's continuous, tie-free input
contract. pyspi does not provide a general discrete MI, TLMI or DI plug-in
estimator; its symbolic support is TE-specific. Use an external discrete
estimator when the missing quantities are needed.
Walkthrough tutorials in the full documentation:
simple demonstration ·
finance ·
neuroimaging
Choosing an SPI set
Computing all 306 SPIs is expensive, and cost grows steeply in both the number
of processes M and the series length T. config= takes either a bundled
name or a path to your own YAML:
config= | SPIs | Use when |
|---|
"full" (default) | 306 | You want everything and can afford it. |
"fast" | 197 | General use; drops the slowest SPIs. |
"benchmarked_p99" | 291 | Near-complete, with only the worst cost outliers removed. |
"benchmarked_p95" | 278 | Good coverage/cost trade-off. |
"benchmarked_p90" | 264 | Recommended default for large batches. |
"benchmarked_p80" | 237 | Cost-constrained sweeps. |
"sonnet" | 14 | One representative SPI per module (M01-M14). |
"fabfour" | 4 | Smoke tests and quick sanity checks. |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
