Detailed Analysis of Algorithms🔗

This page provides a comprehensive overview of the statistical algorithms integrated into ts-stat-tests. It details the rationale behind our library selections, provides an exhaustive catalog of implemented tests, and demonstrates advanced usage patterns for power users and developers.

TL;DR

There are a number of other really good libraries which implement these tests individually:

These packages all implement the statistical tests in a slightly different way.
However, no one library contains all of the required tests, all in one place.
That's precisely why we created ts-stat-tests - to provide a unified interface to all of these great libraries, wrapped in a consistent and easy-to-use API.

💡 Selection Rationale🔗

The primary goal of ts-stat-tests is to provide a single, unified interface to the vast landscape of Python's time-series statistical tools. We have selected specific underlying libraries based on several key criteria:

Reliability: Using industry-standard libraries like statsmodels and scipy ensures the mathematical correctness of the implementations.
Popularity: Libraries with strong community support and active maintenance were prioritised to ensure longevity and compatibility.
Performance: Where possible, we leverage libraries that utilise Numba or Cython for high-speed computation (e.g., antropy, arch).
API Consistency: We wrap diverse APIs (which often vary in return types and parameter naming) into a consistent, predictable structure.
Coverage: We fill gaps where no single library provides a complete suite of tests for a specific domain (e.g., combining statsmodels for stationarity with arch for variance ratios).

📚 Exhaustive Test Catalog🔗

The following tables detail every test currently implemented or planned for the library.

Details

Legend:

icon	description
✅	Already implemented in this package
🔲	To be developed and implemented
❎	Will not be implemented as it is covered by a function from a different package

Test InfoPython Import

category	algorithm	library:test
Correlation	Auto-Correlation function (ACF)	✅`statsmodels`:`acf()` ❎`pmdarima`:`acf()`
Correlation	Partial Auto-Correlation function (PACF)	✅`statsmodels`:`pacf()` ❎`pmdarima`:`pacf()`
Correlation	Cross-Correlation function (CCF)	✅`statsmodels`:`ccf()`
Correlation	Ljung-Box test of autocorrelation in residuals (LB)	✅`statsmodels`:`acorr_ljungbox()`
Correlation	Lagrange Multiplier tests for autocorrelation (LM)	✅`statsmodels`:`acorr_lm()`
Correlation	Breusch-Godfrey Lagrange Multiplier tests for residual autocorrelation (BGLM)	✅`statsmodels`:`acorr_breusch_godfrey()`
Regularity	Approximate Entropy	✅`antropy`:`app_entropy()`
Regularity	Sample Entropy	✅`antropy`:`sample_entropy()`
Regularity	Permutation Entropy	✅`antropy`:`perm_entropy()`
Regularity	Spectral Entropy	✅`antropy`:`spectral_entropy()`
Regularity	SVD Entropy	✅`antropy`:`svd_entropy()`
Seasonality	QS	✅`seastests`:`qs()`
Seasonality	Osborn-Chui-Smith-Birchenhall test of seasonality (OCSB)	✅`pmdarima`:`OCSBTest()`
Seasonality	Canova-Hansen test for seasonal differences (CH)	✅`pmdarima`:`CHTest()`
Seasonality	Seasonal Strength	✅`tsfeatures`:`stl_features()`
Seasonality	Trend Strength	✅`tsfeatures`:`stl_features()`
Seasonality	Spikiness	✅`tsfeatures`:`stl_features()`
Stability	Stability	✅`tsfeatures`:`stability()`
Stability	Lumpiness	✅`tsfeatures`:`lumpiness()`
Stationarity	Augmented Dickey-Fuller test for stationarity (ADF)	✅`statsmodels`:`adfuller()` ❎`pmdarima`:`ADFTest()` ❎`arch`:`ADF()`
Stationarity	Kwiatkowski-Phillips-Schmidt-Shin test for stationarity (KPSS)	✅`statsmodels`:`kpss()` ❎`pmdarima`:`KPSSTest()` ❎`arch`:`KPSS()`
Stationarity	Range unit-root test for stationarity (RUR)	✅`statsmodels`:`range_unit_root_test()`
Stationarity	Zivot-Andrews structural-break unit-root test (ZA)	✅`statsmodels`:`zivot_andrews()` ❎`arch`:`ZivotAndrews()`
Stationarity	Phillips-Peron test for stationarity (PP)	✅`pmdarima`:`PPTest()` ❎`arch`:`PhillipsPerron()`
Stationarity	Elliott-Rothenberg-Stock (ERS) de-trended Dickey-Fuller test	✅`arch`:`DFGLS()`
Stationarity	Variance Ratio (VR) test for a random walk	✅`arch`:`VarianceRatio()`
Normality	Jarque-Bera test of normality (JB)	✅`statsmodels`:`jarque_bera()`
Normality	Omnibus test for normality (OB)	✅`statsmodels`:`omni_normtest()`
Normality	Shapiro-Wilk test for normality (SW)	✅`scipy`:`shapiro()`
Normality	D'Agostino & Pearson's test for normality (DP)	✅`scipy`:`normaltest()`
Normality	Anderson-Darling test for normality (AD)	✅`scipy`:`anderson()`
Linearity	Harvey Collier test for linearity (HC)	✅`statsmodels`:`linear_harvey_collier()`
Linearity	Lagrange Multiplier test for linearity (LM)	✅`statsmodels`:`linear_lm()`
Linearity	Rainbow test for linearity (RB)	✅`statsmodels`:`linear_rainbow()`
Linearity	Ramsey's RESET test for neglected nonlinearity (RR)	✅`statsmodels`:`linear_reset()`
Heteroscedasticity	Engle's Test for Autoregressive Conditional Heteroscedasticity (ARCH)	✅`statsmodels`:`het_arch()`
Heteroscedasticity	Breusch-Pagan Lagrange Multiplier test for heteroscedasticity (BPL)	✅`statsmodels`:`het_breuschpagan()`
Heteroscedasticity	Goldfeld-Quandt test for homoskedasticity (GQ)	✅`statsmodels`:`het_goldfeldquandt()`
Heteroscedasticity	White's Lagrange Multiplier Test for Heteroscedasticity (WLM)	✅`statsmodels`:`het_white()`

test	library:import
ADF	pmdarima: `from pmdarima.arima import ADFTest` statsmodels: `from statsmodels.tsa.stattools import adfuller` arch: `from arch.unitroot import ADF`
KPSS	pmdarima: `from pmdarima.arima import KPSSTest` statsmodels: `from statsmodels.tsa.stattools import kpss` arch: `from arch.unitroot import KPSS`
PP	pmdarima: `from pmdarima.arima import PPTest` arch: `from arch.unitroot import PhillipsPerron`
RUR	statsmodels: `from statsmodels.tsa.stattools import range_unit_root_test`
ZA	statsmodels: `from statsmodels.tsa.stattools import zivot_andrews` arch: `from arch.unitroot import ZivotAndrews`
OCSB	pmdarima: `from pmdarima.arima import OCSBTest`
CH	pmdarima: `from pmdarima.arima import CHTest`
ACF	pmdarima: `from pmdarima.utils import acf` statsmodels: `from statsmodels.tsa.stattools import acf`
PACF	pmdarima: `from pmdarima.utils import pacf` statsmodels: `from statsmodels.tsa.stattools import pacf`
CCF	statsmodels: `from statsmodels.tsa.stattools import ccf`
ALB	statsmodels: `from statsmodels.stats.diagnostic import acorr_ljungbox`
ALM	statsmodels: `from statsmodels.stats.diagnostic import acorr_lm`
ABG	statsmodels: `from statsmodels.stats.diagnostic import acorr_breusch_godfrey`
JB	statsmodels: `from statsmodels.stats.stattools import jarque_bera`
OB	statsmodels: `from statsmodels.stats.stattools import omni_normtest`
HC	statsmodels: `from statsmodels.stats.diagnostic import linear_harvey_collier`
LM	statsmodels: `from statsmodels.stats.diagnostic import linear_lm`
RB	statsmodels: `from statsmodels.stats.diagnostic import linear_rainbow`
RR	statsmodels: `from statsmodels.stats.diagnostic import linear_reset`
ARCH	statsmodels: `from statsmodels.stats.diagnostic import het_arch`
BPL	statsmodels: `from statsmodels.stats.diagnostic import het_breuschpagan`
GQ	statsmodels: `from statsmodels.stats.diagnostic import het_goldfeldquandt`
WLM	statsmodels: `from statsmodels.stats.diagnostic import het_white`

🚀 Advanced Usage Patterns🔗

While the high-level dispatchers are convenient, direct access to the underlying algorithms allows for fine-grained control over the statistical testing process.

Direct Algorithm Access🔗

Importing directly from the .algorithms submodule grants access to full parameter sets and raw results stores from the underlying libraries.

Advanced Stationarity Example
from ts_stat_tests.stationarity.algorithms import adf
from ts_stat_tests.utils.data import load_airline

data = load_airline().values

# Advanced ADF usage:
# - No constant/trend ('n')
# - Fixed lag length of 12
# - Return the full ResultsStore object
stat, pval, crit, resstore = adf(
    data, regression="n", autolag=None, maxlag=12, store=True
)

print(f"Test Statistic: {stat}")
print(f"Regression Summary: \n{resstore.resols.summary()}")

Handling Complex Returns🔗

Many underlying algorithms return different shapes depending on their parameters. We use Python's @overload functionality to ensure type safety even with these dynamic returns.

Standard Return: Usually a tuple of primary statistics (e.g., (stat, pvalue, ...)).
Stored Results: Setting store=True often appends a library-specific result object (like ResultsStore) to the return tuple.

🛠️ Developer Information🔗

For those contributing to ts-stat-tests, maintaining the quality and consistency of the internal algorithms is paramount.

Strict Normalisation🔗

Every internal algorithm wrapper MUST normalise its output. We do not expose raw type inconsistencies from third-party libraries to the user. All outputs should be cast to standard numpy or float/int types before being returned.

Documentation Requirements (DFC)🔗

All algorithm docstrings must adhere to the Docstring Format Checker (DFC) standards using Google style. Specifically, they must include:

!!! note "Summary": High-level purpose.
???+ abstract "Details": Theoretical background.
??? example "Examples": Functional pycon examples.
??? equation "Calculation": LaTeX formatted math.
??? question "References": Academic sources.

Type Hinting and Overloads🔗

We aim to avoid the use of Any wherever possible. All parameters and return values must be explicitly typed. Because many statistical functions have conditional return types based on Boolean flags (like store), you must use @overload to define every possible return signature.

📖 References and External Documentation🔗

For deeper dives into the underlying implementations, we recommend consulting the official documentation of our core dependencies: