📚 Full documentation is on Read the Docs — algorithm deep-dives, CI test guide, CLI reference, and worked example notebooks.
Causal-TS is a Python framework for causal discovery in time series data. It implements five discovery algorithms, a suite of conditional independence tests (linear and nonlinear, GPU-accelerated where it helps), latent-confounder correction, DoWhy-based effect estimation, and built-in visualization and evaluation tools.
Algorithms:
- CDNOTS — Constraint-based discovery handling nonstationarity via a time-index node.
- CDNOTS+ — PCMCI+-style two-phase skeleton (MCI conditioning on discovered parents), avoiding over-conditioning on dense graphs.
- CEDAR — Pairwise discovery for autoregressive processes using minimum-lag selection. O(d²) pairs.
- GRACE / REAP — Grow-shrink refinement of a directed candidate graph (CDNOTS by default, or any method's graph), by neural L0 gates (GRACE) or by regression (REAP).
Also: causal-ts inspect / inspect_df recommend a configuration from the data; LUCID corrects a discovered graph for latent confounders; effect estimation, SCMs and counterfactuals through DoWhy; regime discovery; missing and mixed discrete-continuous data; PCMCI/PCMCI+/LPCMCI through tigramite.
CI Tests: Run causal-ts ci-test-info for a full selection guide.
| Test | Type | Speed |
|---|---|---|
parcorr-gpu |
Linear | instant |
gcmi |
Monotone nonlinear | instant |
raft / rift |
Random-feature F-test (conditional mean) | fast |
rcot |
Nonlinear (RFF, full CI) | fast |
splitkci |
Nonlinear (kernel) | moderate |
linsig |
Path-space (linear signature) | moderate |
kci |
Nonlinear (kernel) | slow |
dfcit |
Distribution-free | moderate |
gcm / wgcm / pcm |
Residual score (regression) | fast |
cmiknn-gpu |
Nonparametric (k-NN) | slow |
cmiknn-mixed-gpu |
Mixed discrete-continuous (k-NN) | slow |
Install the latest release from PyPI with pip or uv:
# Option 1: pip
pip install causalts
# Option 2 (recommended): uv
uv venv # create a virtual env
uv pip install causaltsFor development, clone the repository:
git clone https://github.com/bloomberg/causal-ts.git
cd causal-ts# Option 1: pip
pip install -e ".[dev,dowhy,tigramite]"
# Option 2 (recommended): uv
uv venv # create a virtual env
uv pip install -e ".[dev,dowhy,tigramite]"PyTorch is installed automatically. CUDA and Apple MPS are auto-detected at runtime; CPU is the fallback.
To let a coding agent drive causal-ts, run causal-ts install-skill — see the
CLI reference.
from causalts.synthetic_data.synthetic_datasets import load_dataset
from causalts.ci_tests import RAFTCI
from causalts import run_cdnots
from causalts.utils import evaluate_graph
from causalts.plotting import compare_graphs
# 1. Load a built-in dataset (ex1: 5-var nonlinear)
data = load_dataset("ex1", seed=42, T=500)
df, ground_truth = data["df"], data["ground_truth"]
# 2. Run CDNOTS causal discovery
ci_test = RAFTCI(df.values) # fast nonlinear (conditional-mean) test
res = run_cdnots(
df=df, indep_test=ci_test, num_lags=data["max_lag"],
include_C=True, alpha=0.05, stable=True,
)
# 3. Evaluate (exclude C dimension for shape match with ground truth)
d = ground_truth.shape[0]
metrics = evaluate_graph(res.cg_tig[:d, :d, :], ground_truth)
print(f"F1={metrics['F1']:.3f}, SHD={metrics['SHD']}")
# 4. Visualize
res.plot()
compare_graphs(ground_truth, res.cg_tig[:d, :d, :], var_names=list(df.columns))See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see CONTRIBUTING.md.
Distributed under the GPL-3.0-or-later License. See LICENSE for
more information.
This project includes modified code from third-party packages. See NOTICE for details on original authorship and licensing.
Mohammad Fesanghary - @fesanghary
Project Link: https://github.com/bloomberg/causal-ts
We thank the open source contributors to Tigramite and causal-learn whose implementations informed parts of Causal-TS’s design. This template was adapted from Best-README-Template.
If you use causal-ts in your research, please cite the following papers:
-
Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series Mohammad Fesanghary arXiv preprint arXiv:2607.24673, 2026.
-
CEDAR: Causal Edge Discovery for Autoregressive Processes Mohammad Fesanghary arXiv preprint arXiv:2607.20696, 2026.
-
GRACE: Gated Refinement for Accurate Causal Edge Discovery in High-Dimensional Time Series Mohammad Fesanghary, Abhinav Havaldar arXiv preprint arXiv:2606.23880, 2026.
-
LUCID: Learning Under Confounding for Inference and Discovery in Time Series Mohammad Fesanghary arXiv preprint arXiv:2609.31315, 2026.
-
Causal Discovery from Nonstationary Time Series Agathe Sadeghi, Achintya Gopal, Mohammad Fesanghary International Journal of Data Science and Analytics, 19, pp. 33–59, 2025. doi:10.1007/s41060-024-00679-7
BibTeX entries
@article{fesanghary2026causalts,
title={Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series},
author={Fesanghary, Mohammad},
journal={arXiv preprint arXiv:2607.24673},
year={2026}
}
@article{fesanghary2026cedar,
title={CEDAR: Causal Edge Discovery for Autoregressive Processes},
author={Fesanghary, Mohammad},
journal={arXiv preprint arXiv:2607.20696},
year={2026}
}
@article{fesanghary2026grace,
title={GRACE: Gated Refinement for Accurate Causal Edge Discovery in High-Dimensional Time Series},
author={Fesanghary, Mohammad and Havaldar, Abhinav},
journal={arXiv preprint arXiv:2606.23880},
year={2026}
}
@article{fesanghary2026lucid,
title={LUCID: Learning Under Confounding for Inference and Discovery in Time Series},
author={Fesanghary, Mohammad},
journal={arXiv preprint arXiv:2609.31315},
year={2026}
}
@article{sadeghi2025cdnots,
title={Causal Discovery from Nonstationary Time Series},
author={Sadeghi, Agathe and Gopal, Achintya and Fesanghary, Mohammad},
journal={International Journal of Data Science and Analytics},
volume={19},
pages={33--59},
year={2025},
publisher={Springer},
doi={10.1007/s41060-024-00679-7}
}Thanks goes to these wonderful people (emoji key):
