Ruiz, M.¹, Arana-Catania, M.², Ardila, D. R.³ & Ventura, R.¹ (2026). Journal of Causal Inference.

¹ ISR, Instituto Superior Técnico, Lisbon   ² University of Oxford   ³ Jet Propulsion Laboratory, Caltech

Contents

• Install
• Quickstart
• Usage
• Framework, figures & benchmarks
• Reproducing paper experiments
• Citation
• License

Install

Users

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

uv pip install causal-audit
# or
pip install causal-audit

Optional extras pull in the figure and graph dependencies:

uv pip install "causal-audit[viz]"     # IEEE-style figures (SciencePlots)
uv pip install "causal-audit[graphs]"  # optional exploratory PCMCI+ graph via tigramite
uv pip install "causal-audit[all]"     # viz + graphs + earth-observation helpers

The package installs as causal-audit and imports as causal_audit.

Contributors

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

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

Quickstart

import pandas as pd
from causal_audit import RiskAwareGatekeeper

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

gk = RiskAwareGatekeeper(random_seed=42)
result = gk.analyze(data=df, output_dir="results/")
print(result["policy"].decision)  # "recommend" or "abstain"
print(result["policy"].recommended_method)  # e.g. "PCMCI+" or "LPCMCI"

Run the quickstart notebook for a complete audit and its summary figure. Use the independent walkthrough to configure the audit, inspect diagnostics, and handle abstention. See Usage for the per-stage API.

The default audit does not run causal discovery. The optional exploratory graph requires include_dependency_network=True and Tigramite; it is skipped when the audit abstains.

Usage

Input: a pandas.DataFrame with a DatetimeIndex, one column per variable, NaN for missing values.

import pandas as pd
from causal_audit import AssumptionAuditor  # Stage I
from causal_audit import RiskQuantifier  # Stage II
from causal_audit import MethodRecommender  # Stage III
from causal_audit import RiskAwareGatekeeper  # Stages I → II → III

df = pd.read_csv("data.csv", index_col=0, parse_dates=True)

# Stage I — diagnostics (stationarity, irregularity, persistence, nonlinearity, confounding)
auditor = AssumptionAuditor(alpha=0.05)
evidence = auditor.audit(df)  # → AuditEvidence with per-variable effect sizes

# Stage II — diagnostic-derived risk scores with approximate uncertainty bounds
quantifier = RiskQuantifier()
risk_profile = quantifier.quantify(evidence)  # → RiskProfile (6 scores, bounds, ledger)

# Stage III — recommend a method or abstain
recommender = MethodRecommender()
policy, scorecard = recommender.recommend(risk_profile)  # → Policy + Scorecard

# Or run all three stages at once:
gk = RiskAwareGatekeeper(random_seed=42)
result = gk.analyze(data=df, output_dir="results/")
print(result["policy"].decision)  # "recommend" or "abstain"
print(result["policy"].recommended_method)  # "PCMCI+" or "LPCMCI"

Stage I can be used alone for structured assumption auditing in individual studies. Use the gatekeeper for the complete configured pipeline: per-stage defaults do not automatically load its calibration configuration or retain all downstream diagnostic inputs.

The paper evaluates four calibrated risk dimensions. The current implementation returns six scores and includes heuristic fallbacks and overrides. Its uncertainty bounds and policy confidence are not probabilities that a causal graph is correct; low confounding proxies cannot establish causal sufficiency. Investigate severe nonstationarity and re-audit any justified preprocessing before selecting a discovery method.

Framework, figures & benchmarks

The pipeline figure, the figure catalogue (six diagnostic figures plus an optional exploratory graph), the synthetic DGP atlas (F1–F10), the framework extension points, and the nonlinearity-diagnostic notes live in FRAMEWORK.md.

Reproducing paper experiments

See the step-by-step commands in FRAMEWORK.md.

Citation

@misc{ruiz2026causalaudit,
  title   = {Causal-Audit: A Framework for Risk Assessment of Assumption
             Violations in Time-Series Causal Discovery},
  author  = {Marco Ruiz and Miguel Arana-Catania and David R. Ardila
             and Rodrigo Ventura},
  year    = {2026},
  eprint  = {2604.02488},
  archivePrefix = {arXiv},
  primaryClass  = {cs.LG},
  doi     = {10.48550/arXiv.2604.02488},
  url     = {https://arxiv.org/abs/2604.02488},
}

MIT License