Metadata-Version: 2.4
Name: kausal
Version: 1.0.0
Summary: Deep Koopman operators for causal discovery
Author-email: Juan Nathaniel <jn2808@columbia.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/juannat7/kausal
Project-URL: Issues, https://github.com/juannat7/kausal/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: benchmark-mi>=0.1.3
Requires-Dist: causal-learn>=0.1.3.8
Requires-Dist: cdt>=0.6.0
Requires-Dist: ipdb>=0.13.13
Requires-Dist: jaxtyping>=0.3.3
Requires-Dist: lingam>=1.9.1
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: networkx>=3.4.2
Requires-Dist: numpy<2.0
Requires-Dist: pandas<2.0
Requires-Dist: parameterfree>=0.0.1
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: setuptools>=79.0.0
Requires-Dist: skccm>=0.2.dev0
Requires-Dist: statsmodels>=0.14.5
Requires-Dist: tensorly>=0.9.0
Requires-Dist: tigramite>=5.2.7.0
Requires-Dist: torch>=2.6.0
Requires-Dist: torchdiffeq>=0.2.5
Requires-Dist: tqdm>=4.66.5
Requires-Dist: jax<=0.4.33
Requires-Dist: jaxlib<=0.4.33
Requires-Dist: xarray<=2023.10.0
Requires-Dist: netcdf4>=1.7.2
Dynamic: license-file

Kausal: Deep Koopman Operators for Causal Discovery
=========

**Kausal** is a PyTorch package to perform causal inference in nonlinear, high-dimensional dynamics using deep Koopman operator-theoretic approach.

<div align="center">
  <a href="https://arxiv.org/abs/2505.14828"><img src="https://img.shields.io/badge/ArXiV-2505.14828-b31b1b.svg" alt="arXiv"/></a>
</div>
</br>

![Overview of Kausal](docs/schematic-algorithm.png)

# Features
- 🌡️ Causal measures between high-dimensional, multi-scale, nonlinear timeseries
- ⌛ Uncertainty quantification of causal measures
- 🌐 Causal graph discovery


# Abstract
Causal discovery aims to identify cause-effect mechanisms for better scientific understanding, explainable decision-making, and more accurate modeling. Standard statistical frameworks, such as Granger causality, lack the ability to quantify causal relationships in nonlinear dynamics due to the presence of complex feedback mechanisms, timescale mixing, and nonstationarity. Thus, applying these methods to study causal dynamics in real-world systems, such as the Earth, is a major challenge. Addressing this shortcoming, we leverage deep learning and a **K**oopman operator-theoretic formalism to present a new class of c**ausal** discovery algorithms. **Kausal** uses deep Koopman operator methods to approximate nonlinear dynamics in a linearized vector space in which traditional causal inference methods such as Granger causality can be more easily applied. Our idealized experiments demonstrate **Kausal**'s superior ability in discovering and characterizing causal signals compared to existing deep learning and non-deep learning state-of-the-art approaches. Finally, the successful identification of major El Niño and La Niña events in observations showcases **Kausal**'s skill to handle real-world applications.

# Installation

Kausal is available on PyPi, so installation is as easy as:

```
pip install kausal
```

If you use conda, please use the following commands:
```
conda create --name venv python=3.10
conda activate venv
pip install kausal
```

# Quickstart Guide

Please refer to our tutorial notebooks in the `tutorial/` folder for demonstration.

# Experimental Results
You can find accompanying code to reproduce the experimental results in the `experiments/` folder.

# Developer's Guide
We welcome and appreciate any contribution to improve the codebase! You can make a Pull Request or raise an Issue. During development, install the package in the editable format:

```
git clone https://github.com/juannat7/kausal.git
cd kausal/
pip install -e .

```

# Citation
If you find any of the code and dataset useful, feel free to acknowledge our work through:

```bibtex
@article{nathaniel2025deepkoopmanoperatorframework,
  title={Deep Koopman operator framework for causal discovery in nonlinear dynamical systems},
  author={Juan Nathaniel and Carla Roesch and Jatan Buch and Derek DeSantis and Adam Rupe and Kara Lamb and Pierre Gentine},
  journal={arXiv preprint arXiv:2505.14828},
  year={2025}
}

@article{rupe2024causal,
  title={Causal Discovery in Nonlinear Dynamical Systems using Koopman Operators},
  author={Rupe, Adam and DeSantis, Derek and Bakker, Craig and Kooloth, Parvathi and Lu, Jian},
  journal={arXiv preprint arXiv:2410.10103},
  year={2024}
}
