# z-dragonl/causal-learner architecture

> Architecture diagram of the GitHub repository z-dragonl/causal-learner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z-dragonl/causal-learner
- Repository: https://github.com/z-dragonl/causal-learner

## Overview

##### Project Type and Purpose
- Causal Learner is an open-source research toolbox (not a client/server app) for causal structure and Markov blanket learning.
- It provides:
- R code for simulated Bayesian network data generation
- MATLAB code for global causal structure algorithms (alg_GCS), local causal structure algorithms (alg_LCS), and Markov blanket algorithms (alg_MB)
- Common utility functions and external dependencies (GPML, Feast, MIToolbox)
- Evaluation scripts and example usage

##### File Structure Analysis
- Top level:
- Code/ – all source code
– Causal_Learner.m – main MATLAB entry point
– Gen_Data/ – R scripts and generated .rds datasets
– alg_GCS/, alg_LCS/, alg_MB/ – algorithm families, each with subdirectories per algorithm
– common/ – shared MATLAB functions and third-party libraries (GPML, Feast, MIToolbox)
– data/ – sample network definitions and datasets
– evaluation/ – evaluation metrics and scripts (SHD, ARRHD, adjacency)
– example_*.m – MATLAB usage examples
- Documentation/ – user manual and copyright
- README.md, LICENSE

##### Key Insights from README
- R for data generation (Gen_Data) outputs .rds files
- MATLAB for algorithms and evaluation
- Intended extensibility: add new algorithms by dropping new .m files into the correct alg_* folder and invoking them from Causal_Learner.m or example scripts

##### Components
a. Data Generation (R)
– Gen_Data.R → produces .rds files
– R environment
b. Data Loader (MATLAB)
– Reads .rds via Causal_Learner.m or helper functions
c. Core Algorithm Modules (MATLAB)
– Global Causal Structure (alg_GCS)
– Local Causal Structure (alg_LCS)
– Markov Blanket Learning (alg_MB)
d. Common Utilities & Third-Party Libraries
– common/ (draw_graph, tests, pdag-dag…)
– GPML (used by some GES/KCI tests)
– Feast and MIToolbox (feature selection C-libraries, MATLAB/Java wrappers)
e. Evaluation & Reporting
– evaluation/ scripts → metrics computation
– example_*.m → demonstration flows
f. Documentation & User Interface
– Documentation/ Manual.pdf
– README.md

##### Relationships and Data Flow
1. User invokes Causal_Learner.m or an example script
2. (Optional) Trigger Gen_Data.R in R → .rds datasets
3. MATLAB Data Loader imports .rds
4. MATLAB core dispatch: select algorithm family (alg_GCS, alg_LCS, alg_MB)
5. Algorithms call common utilities and third-party libs as needed
6. Output learned structures (graphs)
7. Evaluation modules compute SHD/ARRHD/adjacency metrics
8. Results visualized or saved (via draw_graph, example scripts)

##### Architectural Patterns and Design Principles
- Modular separation by algorithm type (global vs. local vs. MB)
- Shared “common” layer for utilities promoting code reuse
- External dependencies isolated in common/ for GPML, Feast, MIToolbox
- Clear entry points (Causal_Learner.m, example_*.m)
- Data generation separated (R) from algorithm execution (MATLAB)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Generation Layer
    subgraph "Data Generation (R)" 
        direction TB
        REnv["R Environment"]:::rEnv
        GenData["Gen_Data.R"]:::rEnv
        RDS[".rds Datasets"]:::data
    end

    %% MATLAB Entry and Loader
    subgraph "MATLAB Entry & Data Loader"
        direction TB
        Entry["Causal_Learner.m"]:::matlab
        Loader["RDS Data Loader"]:::matlab
        CommonUtils["common/ Utilities"]:::matlab
    end

    %% Algorithm Modules
    subgraph "Core Algorithm Modules (MATLAB)"
        direction TB
        subgraph "Global Causal Structure (alg_GCS)"
            direction TB
            GES["GES_G2.m"]:::matlab
            F2SL["F2SL_c_G2.m"]:::matlab
        end
        subgraph "Local Causal Structure (alg_LCS)"
            direction TB
            CMB["CMB_G2.m"]:::matlab
            ELCS["ELCS_Z.m"]:::matlab
        end
        subgraph "Markov Blanket Learning (alg_MB)"
            direction TB
            IAMB["IAMB_G2.m"]:::matlab
            HITONMB["HITONMB_Z.m"]:::matlab
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        GPML["GPML Library"]:::ext
        Feast["Feast Library"]:::ext
        MIToolbox["MIToolbox Library"]:::ext
    end

    %% Evaluation & Examples
    subgraph "Evaluation & Examples"
        direction TB
        EvalGCS["evaluation_GCS.m"]:::matlab
        EvalLCS["evaluation_LCS.m"]:::matlab
        EvalMB["evaluation_MB.m"]:::matlab
        ExGCS["example_GCS.m"]:::matlab
        ExLCS["example_LCS.m"]:::matlab
        ExMB["example_MB.m"]:::matlab
    end

    %% Documentation
    subgraph "Documentation & UI"
        direction TB
        Manual["Manual.pdf"]:::doc
        README["README.md"]:::doc
    end

    %% Data Flow and Calls
    REnv --> GenData --> RDS
    RDS --> Loader --> Entry
    Entry --> CommonUtils
    Entry --> GES
    Entry --> F2SL
    Entry --> CMB
    Entry --> ELCS
    Entry --> IAMB
    Entry --> HITONMB

    GES --> GPML
    F2SL --> CommonUtils
    CMB --> CommonUtils
    ELCS --> CommonUtils
    IAMB --> CommonUtils
    HITONMB --> CommonUtils

    CommonUtils --> GPML
    CommonUtils --> Feast
    CommonUtils --> MIToolbox

    GES --> EvalGCS
    CMB --> EvalLCS
    IAMB --> EvalMB

    EvalGCS --> ExGCS
    EvalLCS --> ExLCS
    EvalMB --> ExMB

    ExGCS --> Manual
    ExLCS --> Manual
    ExMB --> Manual

    %% Click Events
    click GenData "https://github.com/z-dragonl/causal-learner/blob/main/Code/Gen_Data/Gen_Data.R"
    click RDS "https://github.com/z-dragonl/causal-learner/tree/main/Code/Gen_Data/RDS/"
    click Entry "https://github.com/z-dragonl/causal-learner/blob/main/Code/Causal_Learner.m"
    click CommonUtils "https://github.com/z-dragonl/causal-learner/tree/main/Code/common/"
    click GES "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_GCS/GES/GES_G2.m"
    click F2SL "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_GCS/F2SL/F2SL_c_G2.m"
    click CMB "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_LCS/CMB/CMB_G2.m"
    click ELCS "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_LCS/ELCS/ELCS_Z.m"
    click IAMB "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_MB/IAMB and its variants/IAMB_G2.m"
    click HITONMB "https://github.com/z-dragonl/causal-learner/blob/main/Code/alg_MB/HITONMB/HITONMB_Z.m"
    click GPML "https://github.com/z-dragonl/causal-learner/tree/main/Code/alg_GCS/GES/GES_subroutines/KCI-test/gpml-matlab/"
    click Feast "https://github.com/z-dragonl/causal-learner/tree/main/Code/common/Feast/FEAST/"
    click MIToolbox "https://github.com/z-dragonl/causal-learner/tree/main/Code/common/Feast/MIToolbox/"
    click EvalGCS "https://github.com/z-dragonl/causal-learner/blob/main/Code/evaluation/evaluation_GCS.m"
    click EvalLCS "https://github.com/z-dragonl/causal-learner/blob/main/Code/evaluation/evaluation_LCS.m"
    click EvalMB "https://github.com/z-dragonl/causal-learner/blob/main/Code/evaluation/evaluation_MB.m"
    click ExGCS "https://github.com/z-dragonl/causal-learner/blob/main/Code/example_GCS.m"
    click ExLCS "https://github.com/z-dragonl/causal-learner/blob/main/Code/example_LCS.m"
    click ExMB "https://github.com/z-dragonl/causal-learner/blob/main/Code/example_MB.m"
    click Manual "https://github.com/z-dragonl/causal-learner/blob/main/Documentation/Manual.pdf"
    click README "https://github.com/z-dragonl/causal-learner/blob/main/README.md"

    %% Styles
    classDef rEnv fill:lightgreen,stroke:#333,stroke-width:1px
    classDef matlab fill:lightblue,stroke:#333,stroke-width:1px
    classDef ext fill:plum,stroke:#333,stroke-width:1px
    classDef data fill:lightyellow,stroke:#333,stroke-width:1px
    classDef doc fill:lightgray,stroke:#333,stroke-width:1px
```
