AutoCause: A Python framework that automates expert decisions in environmental time-series causal discovery
AutoCause automates multi-method causal discovery in environmental time series, improving reproducibility and auditability.
Key Findings
Methodology
AutoCause integrates four primary causal discovery algorithms—VAR-Granger, VARLiNGAM, PCMCI+, and Transfer Entropy—within an automated pipeline that records each decision step. It employs an extended causal-audit module for pre-diagnostics, including tests for stationarity, nonlinearity, and sample adequacy. The framework uses a consensus-support grading system based on the number of methods supporting each link, with false discovery rate correction applied to p-values. Validation on 145 datasets from DGP-Atlas, TimeGraph, and CausalRivers demonstrates its ability to recover complementary parts of known reference graphs, with increased precision for majority-supported links.
Key Results
- In synthetic datasets, links supported by ≥3 methods achieved an average precision of 78%, outperforming single-method results by 15%. On the CausalRivers real river network data, the high-support edges aligned closely with physical river topology, confirming practical relevance. The framework showed robustness across different data regimes, including nonlinear and seasonal series, with a significant boost in F1 scores compared to individual algorithms.
- Across all datasets, the consensus-support tier (support ≥3) yielded higher accuracy, with an average F1 score increase of 12% over single methods. The integration of non-causal models like Random Forests and hypothesis testing further enhanced stability and interpretability, especially in complex environments.
- The framework's ability to systematically record configurations, diagnostics, and results enables reproducibility and transparency, making it suitable for environmental modeling, policy support, and scientific research.
Significance
This work addresses critical gaps in environmental causal analysis—namely, inconsistent method application, lack of reproducibility, and limited auditability. By automating configuration, diagnostics, and multi-method consensus, AutoCause provides a standardized, transparent workflow that enhances confidence in causal inference from observational environmental data. Its open-source nature encourages community-driven improvements and cross-disciplinary adoption, fostering more reliable environmental decision-making and scientific understanding.
Technical Contribution
AutoCause's core innovation lies in its integration of multiple causal discovery algorithms with automated decision logic, including diagnostics for data quality and assumptions. It introduces a support grading system based on method agreement, combined with surrogate and falsification diagnostics, to strengthen causal claims. The modular architecture supports diverse data types and environments, setting a new standard for automated, reproducible causal analysis in complex systems.
Novelty
This is the first framework to systematically combine multiple causal discovery algorithms with automated configuration, diagnostics, and consensus support grading in environmental time series. Unlike prior tools that focus on single algorithms or manual workflows, AutoCause offers a fully automated, auditable pipeline that enhances robustness and comparability of causal graphs, addressing a long-standing challenge in observational environmental science.
Limitations
- Dependence on regularly sampled, aligned time series limits applicability in irregular sampling scenarios. Handling of high-dimensional or extremely nonlinear data remains challenging, especially with limited samples. Fully automated decision-making may still require expert oversight in complex or domain-specific cases to avoid misinterpretation.
- Computational costs increase with data size and number of algorithms, potentially limiting scalability. The framework currently emphasizes linear and moderate nonlinearity; extreme nonlinearity or unmeasured confounders may still impair accuracy.
- While diagnostics improve robustness, ultimate causal interpretation still relies on analyst judgment, especially in complex or uncertain environments.
Future Work
Future developments include expanding algorithm support, especially deep learning-based causal models, and improving handling of high-dimensional, irregular, or missing data. Integrating interactive visualization tools and domain-specific diagnostics will enhance usability. Further validation on diverse environmental datasets and real-world applications will solidify its role as a standard tool for causal inference in environmental sciences.
AI Executive Summary
AutoCause represents a significant advancement in environmental time series causal discovery, addressing longstanding challenges of method inconsistency, reproducibility, and auditability. By integrating four established algorithms—VAR-Granger, VARLiNGAM, PCMCI+, and Transfer Entropy—within an automated pipeline, it records each decision step, from parameter selection to diagnostics, ensuring transparency. The framework employs an extended causal-audit module to perform pre-diagnostics, assessing data stationarity, nonlinearity, and sample adequacy, guiding optimal method configuration.
A key innovation is the consensus-support grading system, which aggregates the support from multiple methods to identify more reliable causal links. This approach, combined with false discovery rate correction and surrogate diagnostics, enhances robustness across synthetic and real-world datasets, including the CausalRivers river network, where high-support edges aligned with physical river topology. The framework's performance demonstrates a 15% increase in precision over single methods, with improved F1 scores, confirming its practical utility.
AutoCause's open-source architecture facilitates broad adoption, enabling researchers and practitioners to conduct reproducible, auditable causal analyses without extensive manual tuning. Its modular design supports diverse data types and environmental conditions, paving the way for standardized causal inference workflows in environmental science. Future efforts will focus on expanding algorithm support, improving handling of complex data, and integrating visualization tools, aiming to establish AutoCause as a foundational tool for observational causal discovery in environmental applications.
Deep Dive
Abstract
Environmental time-series causal discovery requires expert decisions about method choice, conditional-independence tests, lag horizons, sample-size adequacy, multiple-testing control, and evidence interpretation. Applied inconsistently across datasets, these choices yield graphs that cannot be compared, reproduced, or audited. We present AutoCause, an open-source Python workflow that records each decision, derives defaults from an extended causal-audit module, and admits domain-informed overrides. The workflow wraps four established causal-discovery methods from three families, adds non-causal reference models, and grades links by method-count support. On 145 datasets from DGP-Atlas, TimeGraph, and a topology-derived CausalRivers reference, the methods recover complementary parts of the reference graphs. Majority-supported links are more precise than single-method links on the synthetic benchmarks but not against river topology. AutoCause converts inconsistent expert practice into an auditable, repeatable analysis; causal interpretation remains with the analyst. Available at https://github.com/marcoruizrueda/autocause.