Causal-TS

About the Project

📚 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 four discovery algorithms and a suite of GPU-accelerated conditional independence tests, both linear and nonlinear, along with 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) for improved precision on dense graphs.
• CEDAR — Scalable pairwise discovery using minimum-lag selection. O(d²) complexity.
• GRACE — Hybrid: CDNOTS skeleton + neural gated refinement with L0 regularization for high-dimensional data.

CI Tests: Run causal-ts ci-test-info for a full selection guide.

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

import numpy as np
from causalts.synthetic_data.synthetic_datasets import load_dataset
from causalts.ci_tests import SplitKCIGPU
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 = SplitKCIGPU(np.zeros((2, 2)), device="cpu")
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:

1. Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series Mohammad Fesanghary arXiv preprint arXiv:2607.24673, 2026.

2. CEDAR: Causal Edge Discovery for Autoregressive Processes Mohammad Fesanghary arXiv preprint arXiv:2607.20696, 2026.

3. GRACE: Gated Refinement for Accurate Causal Edge Discovery in High-Dimensional Time Series Mohammad Fesanghary, Abhinav Havaldar arXiv preprint arXiv:2606.23880, 2026.

4. 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

@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{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}
}