How renero/causalgraph works
Project type and purpose
• This is a Python library and CLI tool (causalexplain) for causal-graph discovery from tabular data.
• It exposes:
• A command-line interface (python -m causalexplain)
• A Notebook/Library API (GraphDiscovery class)
• Internally it implements multiple causal-inference methods (ReX, PC, FCI, GES, LiNGAM, CAM, NOTEARS), data generators, explainability routines, and evaluation metrics.
High-level architecture overview
• Layers / Components:
A. Presentation layer
• CLI module (__main__.py)
• Notebook/API client (GraphDiscovery in causalexplain/causalexplainer.py)
B. Orchestrator / Pipeline engine
• GraphDiscovery.run(): loads config (fit/predict YAML), invokes submodules
• fit_pipeline.yaml / predict_pipeline.yaml define ordered steps
C. Core domain modules
1. Data ingestion
• CSV reader, schema loader (common/utils.py)
2. Generators (causalexplain/generators)
• Synthetic data creation (GP, linear, polynomial, sigmoid, additive noise models)
3. Estimators (causalexplain/estimators/*)
• Strategy pattern: each subpackage implements one algorithm (ReX, PC, etc.)
4. Explainability (causalexplain/explainability)
• Shapley, permutation importance, regression quality
5. Independence tests (causalexplain/independence)
• CI tests, HSIC, MIC, regressors, graph independence
6. Models (causalexplain/models)
• ML models (DNN, GBT), loss functions, weight utilities
7. Metrics (causalexplain/metrics)
• SID, graph comparison
D. Common utilities (causalexplain/common)
• Plotting, notebook helpers, metrics configuration, generic utils
E. Output & Exporters
• Plot (matplotlib/graphviz), DOT‐export (experiment.export()), console metrics
F. Data folder
• Example datasets (.csv/.dot in data/) used in examples and tests
G. Tests
• Unit tests for each module (pytest)
Relationships and data flow
• User invokes CLI or API → GraphDiscovery
• GraphDiscovery:
• reads dataset (.csv) + optional true DAG (.dot)
• loads pipeline config → sequentially calls:
– generators (if synthetic)
– estimator strategy (e.g. ReX, PC…)
• this may call independence tests or explainability routines
– explainability module (ReX combines model + Shapley)
– metrics module (compare inferred DAG vs true DAG)
• collects results → passes to exporters (plot, DOT, console)
• Common utilities are shared across all submodules
Architectural patterns & design principles
• Pipeline configuration (fit & predict pipelines in YAML)
• Strategy pattern: estimator interfaces and concrete implementations
• Modular package structure for easy extension (add new estimators, generators)
• Separation of concerns: data gen vs inference vs explainability vs metrics
• Lightweight orchestration: GraphDiscovery as single entrypoint
• CLI & Notebook API layer
• Orchestrator / Pipeline Engine
• Domain modules (Generators, Estimators, Explainability, Independence, Models, Metrics)
• Common utilities
• Exporters (Plot, DOT, Console)
b. Inputs:
• CSV dataset (→ Data ingestion)
• True DAG (.dot) optional (→ Metrics)
• YAML configs (→ Pipeline Engine)
• CLI/API → Orchestrator → (Generators →) Estimators → Explainability → Metrics → Exporters
• CLI/API (blue rectangles)
• Pipeline (green)
• Core services (yellow)
• Utilities (gray)
• Data & output (white)