# renero/causalgraph architecture

> Architecture diagram of the GitHub repository renero/causalgraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/renero/causalgraph
- Repository: https://github.com/renero/causalgraph

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data sources
    CSV["CSV Dataset"]:::data
    DOTFile["True DAG (.dot)"]:::data
    FitCfg["fit_pipeline.yaml"]:::config
    PredictCfg["predict_pipeline.yaml"]:::config

    subgraph "causalexplain"
        direction TB

        %% Entry points
        subgraph "Presentation Layer"
            CLI["CLI (__main__.py)"]:::entry
            API["GraphDiscovery (causalexplainer.py)"]:::entry
        end

        %% Orchestration
        Pipeline["Orchestrator / Pipeline Engine"]:::pipeline

        %% Core Domain Modules
        subgraph "Core Domain Modules"
            direction TB
            subgraph "Generators" 
                GenMain["generators.py"]:::domain
                Mech["mechanisms.py"]:::domain
            end
            Estimators["Estimators"]:::domain
            Explain["Explainability"]:::domain
            Indep["Independence"]:::domain
            Models["Models"]:::domain
            DomMetrics["Metrics"]:::domain
        end

        %% Common utilities
        subgraph "Common Utilities"
            Utils1["common/utils.py"]:::utils
            PlotUtil["common/plot.py"]:::utils
            NotebookUtil["common/notebook.py"]:::utils
            MetricsCfgUtil["common/metrics_config.py"]:::utils
        end

        %% Exporters
        subgraph "Exporters & Output"
            PlotExp["Plot Exporter"]:::output
            DOTExp["DOT Export"]:::output
            ConsoleExp["Console Metrics"]:::output
        end
    end

    %% Tests and Data folder
    DataFolder["data/"]:::data
    Tests["Tests"]:::data

    %% Flows
    CSV -->|reads| API
    DOTFile -->|optional input| DomMetrics
    CLI -->|invokes| Pipeline
    API -->|invokes| Pipeline
    FitCfg -->|configures| Pipeline
    PredictCfg -->|configures| Pipeline

    Pipeline -->|generates synthetic data| GenMain
    Pipeline -->|calls estimator| Estimators
    Estimators -->|may use| Indep
    Estimators -->|may use| Explain
    Explain -->|computes explanations| DomMetrics
    DomMetrics -->|sends results to| PlotExp
    DomMetrics -->|sends results to| DOTExp
    DomMetrics -->|sends results to| ConsoleExp

    %% Utilities dashed connections
    Utils1 -.-> GenMain
    Utils1 -.-> Estimators
    Utils1 -.-> Explain
    Utils1 -.-> Indep
    Utils1 -.-> Models
    Utils1 -.-> DomMetrics
    PlotUtil -.-> PlotExp
    NotebookUtil -.-> API
    MetricsCfgUtil -.-> DomMetrics

    %% Side components
    DataFolder -->|example data| CSV
    Tests -->|unit tests| API

    %% Click Events
    click CLI "https://github.com/renero/causalgraph/blob/main/causalexplain/__main__.py"
    click API "https://github.com/renero/causalgraph/blob/main/causalexplain/causalexplainer.py"
    click FitCfg "https://github.com/renero/causalgraph/blob/main/causalexplain/.fit_pipeline.yaml"
    click PredictCfg "https://github.com/renero/causalgraph/blob/main/causalexplain/.predict_pipeline.yaml"
    click Utils1 "https://github.com/renero/causalgraph/blob/main/causalexplain/common/utils.py"
    click PlotUtil "https://github.com/renero/causalgraph/blob/main/causalexplain/common/plot.py"
    click NotebookUtil "https://github.com/renero/causalgraph/blob/main/causalexplain/common/notebook.py"
    click MetricsCfgUtil "https://github.com/renero/causalgraph/blob/main/causalexplain/common/metrics_config.py"
    click GenMain "https://github.com/renero/causalgraph/blob/main/causalexplain/generators/generators.py"
    click Mech "https://github.com/renero/causalgraph/blob/main/causalexplain/generators/mechanisms.py"
    click DOTExp "https://github.com/renero/causalgraph/blob/main/causalexplain/causalexplainer.py"
    click DataFolder "https://github.com/renero/causalgraph/tree/main/data/"
    click Tests "https://github.com/renero/causalgraph/tree/main/causalexplain/tests/"

    %% Styles
    classDef entry fill:#D6E9F8,stroke:#4A90E2,color:#000
    classDef pipeline fill:#DFF0D8,stroke:#3C763D,color:#000
    classDef domain fill:#FCF8E3,stroke:#8A6D3B,color:#000
    classDef utils fill:#EEEEEE,stroke:#AAAAAA,color:#000
    classDef config fill:#FFFFFF,stroke:#999999,color:#000
    classDef output fill:#FFFFFF,stroke:#999999,color:#000
    classDef data fill:#FFFFFF,stroke:#999999,color:#000
```
