`ts-stat-tests`

📚 Overview🔗

ts-stat-tests is a comprehensive, production-ready Python suite for time-series statistical testing. It provides a unified, highly-consistent interface to established tests from statsmodels, scipy, arch, antropy, and more.

Whether you are performing exploratory data analysis, validating model assumptions, or building automated forecasting pipelines, ts-stat-tests simplifies the process by normalising inputs, outputs, and hypothesis testing logic into a single, cohesive framework.

💡 Motivation🔗

Time Series Analysis has been around for a long time, especially for doing Statistical Testing. Some Python packages are going a long way to make this even easier than it has ever been before. Such as sktime and pycaret and pmdarima and statsmodels.

There are some typical Statistical Tests which are accessible in these Python (Normality, Stationarity, Correlation, Stability, etc). However, there are still some statistical tests which are not yet ported over to Python, but which have been written in R and are quite stable.

Moreover, there is no one single library package for doing time-series statistical tests in Python.

That's exactly what this package aims to achieve.

A single package for doing all the standard time-series statistical tests.

🚀 Key Features🔗

Unified Dispatcher API: Every test category (e.g., Stationarity, Normality) has a single entry point. No more hunting through different libraries for different algorithms.
Smart Boolean Checkers: Every module includes is_<test>() functions (e.g., is_stationary()) that return clear Boolean results based on significance levels (\(\alpha\)).
Strictly Typed & Verified: Full compliance with Pyright (strict mode) and @typechecked decorators for robust runtime reliability.
Comprehensive Documentation: Every algorithm is documented with its mathematical foundation (\(\LaTeX\)), usage examples, and direct links to source implementation papers.
Production Quality: Maintains a 10.00/10 Pylint score and 100% path coverage across the entire codebase.
Simplified Results: Standardised ResultsStore and dictionary outputs make it easy to integrate into larger data pipelines.

📦 Installation🔗

Install the package via pip:

pip install ts-stat-tests

Or using uv (recommended):

uv add ts-stat-tests

🛠️ Quick Start🔗

Using ts-stat-tests is designed to be intuitive. You can use the high-level dispatcher or the boolean checkers.

Using the Boolean Checker🔗

Perfect for automated pipelines where you need to branch logic based on statistical properties.

Python
import numpy as np
from ts_stat_tests.stationarity import is_stationary

# Create some random data
data = np.random.normal(0, 1, 100)

# Check for stationarity using the ADF test
result = is_stationary(data, algorithm="adf", alpha=0.05)

if result["result"]:
    print(f"Data is stationary (p-value: {result['pvalue']:.4f})")
else:
    print("Data is non-stationary")

Using the Unified Dispatcher🔗

Get the raw statistical results from any supported algorithm.

Python
from ts_stat_tests.normality import normality

# Run multiple normality tests via the same interface
jb_stat, jb_pvalue = normality(data, algorithm="jarque_bera")
sw_stat, sw_pvalue = normality(data, algorithm="shapiro_wilk")

📊 Supported Tests🔗

Full credit goes to the packages listed in this table.

Type	Name	Source Package	Source Language

Correlation	Auto-Correlation function (ACF)	`statsmodels`	Python
Correlation	Partial Auto-Correlation function (PACF)	`statsmodels`	Python
Correlation	Cross-Correlation function (CCF)	`statsmodels`	Python
Correlation	Ljung-Box test of autocorrelation in residuals (LB)	`statsmodels`	Python
Correlation	Lagrange Multiplier tests for autocorrelation (LM)	`statsmodels`	Python
Correlation	Breusch-Godfrey Lagrange Multiplier tests for residual autocorrelation (BGLM)	`statsmodels`	Python

Regularity	Approximate Entropy	`antropy`	python
Regularity	Sample Entropy	`antropy`	python
Regularity	Permutation Entropy	`antropy`	python
Regularity	Spectral Entropy	`antropy`	python
Regularity	SVD Entropy	`antropy`	python
Seasonality	QS	`seastests`	R
Seasonality	Osborn-Chui-Smith-Birchenhall test of seasonality (OCSB)	`pmdarima`	Python
Seasonality	Canova-Hansen test for seasonal differences (CH)	`pmdarima`	Python
Seasonality	Seasonal Strength	`tsfeatures`	Python
Seasonality	Trend Strength	`tsfeatures`	Python
Seasonality	Spikiness	`tsfeatures`	Python

Stability	Stability	`tsfeatures`	Python
Stability	Lumpiness	`tsfeatures`	Python
Stationarity	Augmented Dickey-Fuller test for stationarity (ADF)	`statsmodels`	Python
Stationarity	Kwiatkowski-Phillips-Schmidt-Shin test for stationarity (KPSS)	`statsmodels`	Python
Stationarity	Range unit-root test for stationarity (RUR)	`statsmodels`	Python
Stationarity	Zivot-Andrews structural-break unit-root test (ZA)	`statsmodels`	Python
Stationarity	Phillips-Peron test for stationarity (PP)	`arch`	Python
Stationarity	Elliott-Rothenberg-Stock (ERS) de-trended Dickey-Fuller test	`arch`	Python
Stationarity	Variance Ratio (VR) test for a random walk	`arch`	Python

Normality	Jarque-Bera test of normality (JB)	`statsmodels`	Python
Normality	Omnibus test for normality (OB)	`statsmodels`	Python
Normality	Shapiro-Wilk test for normality (SW)	`scipy`	Python
Normality	D'Agostino & Pearson's test for normality	`scipy`	Python
Normality	Anderson-Darling test for normality	`scipy`	Python
Linearity	Harvey Collier test for linearity (HC)	`statsmodels`	Python
Linearity	Lagrange Multiplier test for linearity (LM)	`statsmodels`	Python
Linearity	Rainbow test for linearity (RB)	`statsmodels`	Python
Linearity	Ramsey's RESET test for neglected nonlinearity (RR)	`statsmodels`	Python

Heteroscedasticity	Engle's Test for Autoregressive Conditional Heteroscedasticity (ARCH)	`statsmodels`	Python
Heteroscedasticity	Breusch-Pagan Lagrange Multiplier test for heteroscedasticity (BPL)	`statsmodels`	Python
Heteroscedasticity	Goldfeld-Quandt test for homoskedasticity (GQ)	`statsmodels`	Python
Heteroscedasticity	White's Lagrange Multiplier Test for Heteroscedasticity (WLM)	`statsmodels`	Python

🛡️ Quality Assurance🔗

We take code quality seriously. Every commit is verified against:

Code Style: All code adheres to black formatting, including all code chunks in docstrings using the blacken-docs.
Spell Checking: All documentation and code comments are spell-checked using codespell.
Type Safety: All code is type-checked using ty and pyright and guarded during runtime by using the typeguard library.
Import Sorting: All imports are sorted and managed using isort and unused imports are removed using pycln.
Code Quality: All code is checked for quality using pylint maintaining a score of 10/10, and checked for complexity using complexipy.
Docstring Quality: All docstrings are checked for style and completeness using docstring-format-checker.
Unit Testing: All code is unit-tested using pytest achieving 100% code coverage across the entire codebase, and including all examples in all docstrings tested using doctest.
Build Testing: The package is built with uv and the docs are built with mkdocs to ensure there are no build errors.

⚠️ Known limitations🔗

These listed tests is not exhaustive, and there is probably some more that could be added. Therefore, we encourage you to raise issues or pull requests to add more statistical tests to this suite.
This package does not re-invent any of these tests. It merely calls the underlying packages, and calls the functions which are already written elsewhere.

🤝 Contributing🔗

Contributions are welcome! Please see our Contributing Guide for details on our development workflow and how to submit pull requests.

📄 License🔗

This project is licensed under the MIT License - see the LICENSE file for details.