AutoCause

📄 Paper (arXiv:2608.00198)

Automated expert decisions for environmental time-series causal discovery: method selection, lag choice, CI-test selection, sample-size adequacy, FDR correction, and evidence grading.

Ruiz, M.¹, Arana-Catania, M.², Ardila, D. R.³ & Ventura, R.¹ (2026). Environmental Modelling & Software.

¹ ISR-Lisbon, Instituto Superior Técnico, Lisbon   ² Digital Scholarship at Oxford, University of Oxford   ³ Jet Propulsion Lab., Caltech

Contents

• Install
• Quickstart
• Usage
• Framework & pipeline
• Citation
• License

Install

Users

Install the released package with uv (recommended) or pip:

uv pip install autocause
# or
pip install autocause

The optional causal-audit pre-discovery module is installed with the causal-audit extra, or on its own:

uv pip install "autocause[causal-audit]"
# or install the companion package directly
pip install causal-audit

Contributors

Clone the repository and install an editable copy into a fresh environment:

git clone https://github.com/marcoruizrueda/autocause.git
cd autocause
uv venv .venv --python 3.13
source .venv/bin/activate
uv pip install -e .

To include the pre-discovery audit, add the extra, which pulls causal-audit from PyPI:

uv pip install -e '.[causal-audit]'

To co-develop both packages, clone causal-audit beside autocause and install it editable as well, which overrides the PyPI copy:

git clone https://github.com/marcoruizrueda/causal-audit.git ../causal-audit
uv pip install -e ../causal-audit -e '.[causal-audit]'

The supported interpreter is Python 3.13, including the companion audit package. numba is a required dependency for the CMIknn transfer-entropy estimator; LiNGAM brings its own dependencies, including psy, through the resolver.

Quickstart

import pandas as pd
from autocause.core.run_workflow import run_causal_discovery_workflow

# DataFrame with a DatetimeIndex and one column per variable
df = pd.read_csv("data.csv", index_col=0, parse_dates=True)

result = run_causal_discovery_workflow(
    data_df=df,
    output_dir="results/",
    enable_causal_audit=True,
    apply_audit_recommendation=True,
    enable_consensus=True,
)
print(result["success"])

This enables the companion audit and consensus alongside the default workflow stages. The audit fills unset configuration fields; review saved warnings and evidence before interpreting links. See Usage for configured runs.

Run the quickstart notebook for the complete workflow and its figures. Use the independent walkthrough for configuration, statistical interpretation, and auditing. See Quickstart validation for reproducible checks.

Usage

import pandas as pd
from autocause.core.run_workflow import run_causal_discovery_workflow

# Input: DataFrame with DatetimeIndex, one column per variable, NaN for missing
df = pd.read_csv("data.csv", index_col=0, parse_dates=True)

results = run_causal_discovery_workflow(
    data_df=df,
    output_dir="results/",
    target_var="FCH4",
    alpha=0.05,
    sampling_days=1,
    deseasonalize=True,  # subtract rolling mean before discovery
    true_edges={
        ("X", "Y")
    },  # optional: if ground truth available, computes F1, AUROC, AUPRC
    enable_consensus=True,  # multi-method voting
    enable_causal_audit=True,  # run causal-audit assumption diagnostics first
    method_config={
        "granger": {"enabled": True},  # conditional VAR-based Granger (statsmodels)
        "transfer_entropy": {
            "enabled": True
        },  # CMIknn nearest-neighbour estimator (tigramite)
        "pcmci": {
            "enabled": True,
            "test_method": "parcorr",
        },  # PCMCI+ constraint-based (tigramite)
        "varlingam": {"enabled": True},  # ICA-based VAR-LiNGAM (lingam)
        "lpcmci": {"enabled": False},  # LPCMCI for latent confounders (tigramite)
        "correlation": {
            "enabled": True
        },  # lagged Pearson/Spearman (non-causal baseline)
        "predictive_baseline": {
            "enabled": True
        },  # Random Forest permutation importance (scikit-learn)
        "ci_sensitivity": {
            "enabled": True
        },  # compare ParCorr vs RobustParCorr vs CMIknn
    },
)

For detailed options (audit-only mode, CI-test auto-selection, sample size adequacy, PCMCI vs PCMCI+, graph recovery metrics), see docs/USAGE.md.

Methods

The first five are causal discovery methods from the dominant paradigms. The RF-baseline is a predictive reference included to answer: "does causal discovery find something different from feature importance?"

Framework & pipeline

The end-to-end architecture figure and the full 21-step workflow (data and assumptions, discovery, validation and synthesis) are documented in FRAMEWORK.md.

Reproducing the paper experiments

All experiment scripts, configurations, and reproduction instructions are in experiments/README.md.

Citation

@article{ruiz2026autocause,
  title={AutoCause: A Python framework that automates expert decisions in environmental time-series causal discovery},
  author={Ruiz, Marco and Arana-Catania, Miguel and Ardila, David R and Ventura, Rodrigo},
  journal={arXiv preprint arXiv:2608.00198},
  year={2026}
}
# APA:
Ruiz, M., Arana-Catania, M., Ardila, D. R., & Ventura, R. (2026). AutoCause: A Python framework that automates expert decisions in environmental time-series causal discovery. arXiv preprint arXiv:2608.00198.

License

AGPL-3.0-or-later. Depends on Tigramite (GPL-3.0-or-later), which remains under its original license.