📊 statistics

Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series

This paper introduces Causal-TS, an open-source Python library designed for causal discovery in high-dimensional, nonstationary multivariate time series, featuring specialized algorithms, GPU-accelerated conditional independence testing, and an end-to-end pipeline that integrates regime detection, causal structure learning, and effect estimation.

Original authors: Mohammad Fesanghary

Published 2026-07-28

📖 4 min read☕ Coffee break read

CC BY 4.0

Original authors: Mohammad Fesanghary

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you are a detective trying to solve a mystery, but instead of looking at fingerprints or footprints, you are looking at a stream of numbers that change every second. This is the world of time series data, a tool used by scientists to understand everything from how the weather changes to how stock markets move. Usually, detectives look for clues that happen before the crime to figure out what caused it. In science, this is called causal discovery: figuring out if A actually makes B happen, or if they just happen to happen at the same time.

But there's a tricky twist in this mystery. Sometimes, the "rules" of the game change while you are watching. Imagine a river that flows fast in the spring but slow in the winter. If you only look at the water in July, you might think the river always moves slowly, missing the fact that it was rushing just a few months ago. This changing of rules is called nonstationarity. For a long time, computers struggled to solve these puzzles because they assumed the rules stayed the same forever. They also got overwhelmed when there were too many clues (variables) to check at once. This is where a new tool comes in to help the detective.

The paper introduces Causal-TS, a new, free software tool written in Python that acts like a super-powered magnifying glass for these changing, complex time series. Think of it as a detective's toolkit that doesn't just look at the clues; it realizes that the crime scene might have changed over time. The tool is designed to handle situations where the "rules" of cause and effect shift, such as when a financial market behaves differently during a crisis than during a boom, or when a forest ecosystem reacts differently in a drought versus a rainy season.

The main thing Causal-TS does is provide a unified library to find cause-and-effect links in data that is both huge (high-dimensional) and constantly changing (nonstationary). It does this by offering four special "algorithms"—which are just fancy recipes for solving the puzzle. Two of these recipes, called CDNOTS and CDNOTS+, are like detectives who keep a special notebook of how the rules change over time, allowing them to spot connections that other tools might miss due to their static assumptions. Another recipe, Cedar, is great for spotting simple, direct links between two things, while Grace uses a neural network trick to cut through the noise when there are too many variables to count.

What makes this tool really special is how fast it is. The authors built it to run on GPUs (the powerful chips usually used for video games), which lets it check for connections much faster than standard computer processors. In their tests, using a GPU made the tool nearly 3 times faster for some of the hardest checks. It also includes a "regime discovery" feature, which is like a smart assistant that automatically notices when the rules of the game have changed (like a sudden shift from dry to wet weather) and splits the investigation into separate cases for each period. This ensures the detective doesn't mix up clues from two different eras.

The paper demonstrates the tool's capabilities by running simulations on made-up data where the scientists already knew the answer. In these tests, Causal-TS successfully performed the discovery tasks and reported speed benchmarks, showing it can handle the specific challenges of nonstationary and high-dimensional data. It also comes with a simple command-line tool, meaning you don't even need to be a coding expert to use it; you can just type a single command to start the investigation. While the tool is powerful, the authors are careful to note that it assumes the data is sampled well enough and that it cannot magically solve mysteries where hidden factors are secretly pulling the strings behind the scenes. However, for anyone trying to untangle the complex, shifting relationships in time-based data, Causal-TS offers a fresh, fast, and flexible way to get to the truth.

Technical Summary of "Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series"

Problem Statement
Identifying causal relationships from observational time series is a critical challenge across disciplines such as climate science, neuroscience, finance, and economics. While temporal order provides a structural advantage by ruling out certain causal directions, existing tools often fail to adequately address two specific complexities: nonstationarity (changes in causal mechanisms over time) and high dimensionality. Furthermore, current software ecosystems (e.g., Causal-learn, Tigramite, DoWhy) generally lack a unified pipeline that combines nonstationarity-aware discovery, GPU-accelerated conditional independence (CI) testing, and an integrated workflow from discovery to causal effect estimation.

Methodology and Architecture
Causal-TS is an open-source Python library designed to address these gaps through a modular architecture centered on a unified CI test layer. The library's methodology is built on three core components:

Unified CI Test Layer with GPU Acceleration:
All discovery algorithms in Causal-TS share a common interface for conditional independence testing. This layer implements eight distinct tests: ParCorr, KCI, SplitKCI, DFCIT, LinSig (a linear-kernel variant of the signature kernel), RCOT, CMIknn, and GCMI. Crucially, all eight tests include GPU-accelerated implementations via PyTorch, significantly reducing computational overhead for large datasets.
Specialized Discovery Algorithms:
The library provides four specialized algorithms for nonstationary and high-dimensional data, alongside wrappers for established baselines (GES, Granger, LASSO-VAR, LGES):
- CDNOTS: Extends the PC algorithm with temporal constraints and a multidimensional conditioning variable $C$ (incorporating time indices, seasonal cycles, or regime indicators) to capture nonstationarity.
- CDNOTS+: A variant that replaces the skeleton phase with a PCMCI+-style procedure. It restricts conditioning to discovered parents to mitigate over-conditioning issues common in hub-structured and scale-free graphs.
- Cedar: Utilizes partial distance correlation for lag selection, AR(p)-aware CI testing, and stable MCI pruning to avoid exponential conditioning sets. It employs a deterministic C-node to handle nonstationarity.
- Grace: Refines a CDNOTS skeleton using Hard Concrete gates and L0 regularization, specifically optimized for high-dimensional scenarios ( $d \le 100$ ).
Regime Discovery Pipeline:
To address structural breaks where causal lag structures shift across operating conditions (e.g., flood vs. dry seasons), Causal-TS includes a regime discovery module. This pipeline uses pluggable changepoint detectors (including PELT, HMM, CUSUM, KS, Levene, ensemble, quantile, and seasonal methods) to segment the time series. Discovery is then executed independently per regime using regime-specific parameters, with results aggregated via union, majority, weighted, or intersection methods.

Key Contributions and Features

Algorithmic Diversity: The library offers a suite of algorithms tailored for nonstationarity (CDNOTS), scale-free graphs (CDNOTS+), autoregressive processes (Cedar), and high-dimensional neural approaches (Grace).
End-to-End Workflow: Causal-TS bridges the gap between discovery and inference. Result objects natively support DoWhy for effect estimation (.estimate_effect(), .fit_scm(), .counterfactual()), allowing users to move from raw data to causal effect estimates within a single ecosystem.
Usability and Integration: The library features a command-line interface (CLI) for users without Python expertise, synthetic data generators for testing, and optional integration with DoWhy. It supports domain knowledge through AncestralKnowledge, allowing for direct edge constraints and path-level ancestral constraints.
Performance: Benchmarks on synthetic data ( $T=1000, d=20$ ) using an NVIDIA L4 GPU demonstrate significant speedups for CI tests compared to CPU implementations (e.g., KCI shows a 2.9× speedup, SplitKCI a 2.0× speedup).

Results and Validation
The paper presents the library's capabilities through:

Performance Metrics: Table 2 quantifies the wall-clock time reductions achieved via GPU acceleration for the most expensive CI tests.
Feature Comparison: Table 3 positions Causal-TS against existing libraries (Causal-learn, Tigramite, DoWhy), highlighting its unique combination of temporal graph discovery, nonstationarity-awareness, GPU acceleration, and CLI workflow.
Software Quality: The library is rigorously tested across Python 3.10–3.12 with 22 test modules, continuous integration workflows (linting, security analysis), and comprehensive documentation including 25 example notebooks.

Significance and Scope
The authors position Causal-TS as filling a complementary niche in the causal discovery landscape: enabling the analysis of nonstationary temporal dynamics at scale. The library is designed to provide a unified pipeline from raw time series to causal effect estimates, specifically targeting scenarios where causal mechanisms change over time.

The paper maintains a modest scope regarding its limitations:

It assumes sufficiently sampled multivariate time series.
It does not inherently resolve hidden confounding or selection bias; these assumptions are documented per algorithm.
The current version (v0.25.0) is available as open-source software, with the primary contribution being the integration of these specific algorithms and the GPU-accelerated infrastructure into a cohesive, user-friendly library.

Technical Summary of "Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series"

More like this