# suwonglab/causalbgm architecture

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

- Interactive diagram: https://gitdiagram.com/suwonglab/causalbgm
- Repository: https://github.com/suwonglab/causalbgm

## Overview

##### Project Type and Purpose
- This is a Python package offering an AI-powered Bayesian generative modeling framework tailored for causal inference in observational studies.
- The README emphasizes that the system is built to provide point and interval estimates (ATE, ITE, ADRF, CATE) for causal analysis using state-of-the-art Bayesian iterative techniques.
- The project supports both a Python and an R package interface, but the codebase is mainly in Python (with TensorFlow and TensorFlow Probability as core dependencies).

##### Analyzing the File Structure
- Top-Level Directories and Files:
- “docs/” contains documentation sources (Sphinx/ReST structure, notebooks for tutorials), indicating that the system is well-documented.
- “src/” is the core source code folder.
- “src/bayesgm/” is the main package, containing submodules like “cli”, “datasets”, “models”, “tests”, and “utils”.
- “src/configs/” holds YAML configuration files for different simulation/data scenarios (e.g., Semi_Twins.yaml, Sim_Hirano_Imbens.yaml), signaling that how the models run (parameters, simulation setups) is configurable.
- “src/main.py” provides a primary entry point for command-line or script-based execution.
- This structure suggests a clear separation between interfaces (CLI), core functionality (modeling, dataset handling, utilities), and configuration/testing.

##### Key Components
a. Core Components:
- CLI Layer – Represented by “src/bayesgm/cli”. This is the command-line interface that provides user interaction.
- Datasets Module – “src/bayesgm/datasets” contains samplers and dataset loaders that simulate or load observational data.
- Models Module – “src/bayesgm/models” hosts the core modeling algorithms, including the primary CausalBGM model implementation along with supporting model classes.
- Utilities Module – “src/bayesgm/utils” holds helper functions, including I/O operations which support data manipulation and other ancillary functions.
- Configurations – “src/configs” folder for simulation and experimental configurations, which supply parameter files (YAML) used when initializing and training models.
- Main Entry Point – “src/main.py” which ties together configuration, data loading, and model execution.

b. External Dependencies and Technologies:
- TensorFlow (v2.10) and TensorFlow Probability: Core engines for model training and probabilistic computations.
- Python 3.9 environment.
- Testing (unit tests in “src/bayesgm/tests”) to ensure module reliability.
- Integration with documentation tools (ReadTheDocs, Sphinx) as indicated by the “docs” folder and provided notebooks.
- Third-party package management (pip, PyPI) for distribution.

##### Relationships and Data Flow
- Data Flow starts at the input stage using either built-in simulation datasets (via the datasets module) or external data provided by the user.
- The CLI layer or the main script reads in configuration files from the “configs” directory.
- Datasets acquired are fed into the Models module, specifically the CausalBGM model, which carries out the initialization (EGM initialization) and iterative training.
- The Models module communicates with utility functions (data_io, helpers) to process and manage data flows.
- TensorFlow/TensorFlow Probability form the runtime engine for training and prediction tasks.
- Outputs include causal effect estimates and prediction intervals, which can be further processed or displayed.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separation between CLI, data handling, model logic, and utilities.
- Configurability: External YAML configuration files allow flexible experiments.
- Test-Driven Development: Presence of multiple tests to validate the components.
- Layered Architecture: External interface (CLI and main script) interacting with core libraries (models, datasets, utils), with dependencies clearly organized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        CLI["CLI (bayesgm/cli)"]:::ui
        MAIN["Main Entry Point"]:::ui
    end

    %% Configuration & Data Management Layer
    subgraph "Configuration & Data Management"
        CONFIG["Configurations (src/configs)"]:::config
        DATA["Datasets (bayesgm/datasets)"]:::data
    end

    %% Core Modeling & Utilities Layer
    subgraph "Core Modeling & Utilities"
        MODELS["Models (bayesgm/models)"]:::model
        UTILS["Utilities (bayesgm/utils)"]:::util
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        TF["TensorFlow (v2.10)"]:::ext
        TFP["TensorFlow Probability"]:::ext
        PY["Python (3.9)"]:::ext
    end

    %% Quality Assurance & Documentation Layer
    subgraph "Quality & Documentation"
        DOCS["Documentation (docs)"]:::qa
        TESTS["Tests (bayesgm/tests)"]:::qa
    end

    %% Relationships
    %% User Interaction triggers configuration and data loading
    CLI -->|"initiates"| CONFIG
    CLI -->|"initiates"| DATA
    MAIN -->|"reads_config"| CONFIG
    MAIN -->|"loads_data"| DATA

    %% Data Management feeds into core modeling
    CONFIG -->|"provides_settings"| MODELS
    DATA -->|"feeds_data"| MODELS

    %% Core Modeling uses utilities and performs iterative training
    MODELS -->|"calls_utilities"| UTILS
    MODELS -->|"iterative_update"| MODELS

    %% Core Modeling relies on external computation engines
    MODELS -->|"computations"| TF
    MODELS -->|"prob_distributions"| TFP
    MODELS -->|"runs_on"| PY

    %% Output from Models sent back to user interface
    MODELS -->|"outputs_estimates"| CLI

    %% Class Definitions for Colors
    classDef ui fill:#f9d6d5,stroke:#D95F02,stroke-width:2px;
    classDef config fill:#c6e2ff,stroke:#1f78b4,stroke-width:2px;
    classDef data fill:#d5f5e3,stroke:#33a02c,stroke-width:2px;
    classDef model fill:#fff2cc,stroke:#ff7f00,stroke-width:2px;
    classDef util fill:#fefbd8,stroke:#8a8a00,stroke-width:2px;
    classDef ext fill:#d0e1f9,stroke:#4575b4,stroke-width:2px;
    classDef qa fill:#e6ccf2,stroke:#6a51a3,stroke-width:2px;

    %% Click Events for Component Mapping
    click CLI "https://github.com/suwonglab/causalbgm/blob/main/src/bayesgm/cli/cli.py"
    click DATA "https://github.com/suwonglab/causalbgm/tree/main/src/bayesgm/datasets"
    click MODELS "https://github.com/suwonglab/causalbgm/tree/main/src/bayesgm/models"
    click UTILS "https://github.com/suwonglab/causalbgm/tree/main/src/bayesgm/utils"
    click CONFIG "https://github.com/suwonglab/causalbgm/tree/main/src/configs"
    click MAIN "https://github.com/suwonglab/causalbgm/blob/main/src/main.py"
```
