bloomberg/causal-ts
bloomberg/causal-ts has 116 GitHub stars and 39 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:52 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Causal discovery (structure learning) for stationary and nonstationary multivariate time series in Python.
Machine LearningREADME.md
OriginalCausal-TS
Causal discovery for stationary and nonstationary multivariate time series in Python.
About the Project
📚 Full documentation is on Read the Docs — algorithm deep-dives, CI test guide, CLI reference, and worked example notebooks.
Causal-TS (causalts on PyPI) is an open-source Python library for causal
discovery (also called causal structure learning) from stationary and
nonstationary multivariate time series. It learns lagged and contemporaneous
causal graphs with constraint-based, score-based and hybrid methods;
provides linear and nonlinear conditional-independence tests on CPU and GPU;
and supports graph refinement, regime discovery, latent-confounder correction,
missing and mixed data, and optional causal effect estimation and
counterfactual analysis through DoWhy.
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 — Hybrid 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).
- Score-based — LGES, TGES and GES (BIC score search over lag-embedded data), plus Lasso-VAR, VARLiNGAM and Granger causality.
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 |
Residual score (regression) | fast |
wgcm / pcm |
Residual score (regression) | moderate |
cmiknn-gpu |
Nonparametric (k-NN) | slow |
cmiknn-mixed-gpu |
Mixed discrete-continuous (k-NN) | slow |
Getting Started
Installation
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 causalts
For 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.
Quick Start
On your own data (a CSV with one column per variable, rows in time order):
causal-ts inspect data.csv # data health + recommended settings
causal-ts discover data.csv -a cdnots --ci-test raft --max-lag 3 # learn the causal graph
Use the CI test and settings that inspect recommends; raft is a fast
nonlinear choice, while the default parcorr-gpu assumes linear relations.
Reproducible example with known ground truth
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))
Roadmap
See the open issues for a list of proposed features (and known issues).
Contributing
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.
License
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.
Contact
Mohammad Fesanghary - @fesanghary
Project Link: https://github.com/bloomberg/causal-ts
Acknowledgements
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.
Citations
If you use causal-ts in your research, please cite the following papers:
Causal-TS: A Python Library for Causal Discovery in Stationary 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 Stationary 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}
}
Contributors
Thanks goes to these wonderful people (emoji key):