# ggbioing/mcvae architecture

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

- Interactive diagram: https://gitdiagram.com/ggbioing/mcvae
- Repository: https://github.com/ggbioing/mcvae

## Overview

##### Project type and purpose
- This is an open-source Python library (mcvae) implementing “Multi-Channel Variational Autoencoders” (MCVAE) and “Multi-Task MCVAE.”
- It provides core model code, data‐loading utilities, distribution helpers, GPU acceleration, diagnostic tools, and plotting functions.
- Example scripts demonstrate training and evaluation on synthetic and real‐world multi‐modal datasets.

##### File structure
- Top-level:
- setup.py, environment.yml, README.md, LICENSE – packaging, build and install scripts, environment spec.
- examples/ – end-to-end usage scripts and pre‐trained models.
- src/mcvae/ – the actual library code, subdivided into:
- datasets/ – data‐loading and synthetic data generators.
- distributions/ – likelihood, KL utilities, normal distributions.
- gpu/ – CUDA‐enabled helpers and device management.
- models/ – core VAE, multi‐channel wrapper, utilities for encoder/decoder architectures.
- imputation/ – handling of missing data when training multi‐task settings.
- diagnostics/ – model introspection, convergence checks, logging.
- plot/ – visualization routines for reconstructions, latent spaces.
- utilities/ and os/ – file I/O, configuration, general helper functions.

##### README for additional insights
- It lists dependencies (conda environment), install instructions, and cites the papers.

##### Main components and interactions
a. Components
1. User/API Layer
– scripts in examples/ or external client code calling mcvae API.
2. Data Ingestion
– src/mcvae/datasets for loading real or synthetic channels.
3. Preprocessing & Imputation
– src/mcvae/imputation handles missing entries.
4. Distribution Utilities
– src/mcvae/distributions houses likelihood and KL computations.
5. Model Core
– src/mcvae/models:
- VAE core (encoder/decoder)
- Multi-Channel wrapper (combines multiple encoders/decoders)
- Sparse latent option
- Multi-Task extension
6. GPU Acceleration
– src/mcvae/gpu for dispatching tensors to GPU, optimizing training loops.
7. Training Loop & Diagnostics
– integrates model, data, distribution utilities; logs loss, convergence via src/mcvae/diagnostics.
8. Visualization
– src/mcvae/plot generates sampling figures, latent traversals, diagnostic plots.
9. Configuration & Utilities
– environment.yml for dependencies, setup.py for packaging, src/mcvae/utilities & os for file paths and logging.

b. Relationships & Data Flow
- User/API → Data Ingestion → (optionally) Imputation
- Data batches + model definitions → Training Loop
- Training Loop uses Distribution Utilities for loss computation → GPU module for acceleration
- Diagnostics module hooks into Training Loop to record metrics
- Plot module consumes outputs from Diagnostics and model checkpoints to generate figures
- Examples drive the entire flow end-to-end

c. Architectural Patterns & Principles
- Modular package structure: separation of concerns (data, model, distribution, GPU, diagnostics, plotting).
- Plug-in design: new data loaders, distributions, or model variants can be added under their namespaces.
- Single Responsibility: each subpackage handles a narrowly defined task.
- Dependency injection via configuration/environment files.

d. Key Technologies
- Python 3.x, PyTorch (implied by GPU and tensor ops)
- Conda environment management
- Package installation via setup.py (install/develop)
- Typical ML stack (NumPy, SciPy, Matplotlib for plotting)

##### Essential elements
- Clear labels: naming each subpackage and role
- Layers: User/API, Library Core, Hardware Acceleration, Visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/API Layer
    subgraph "User/API Layer"
        direction TB
        ExamplesMCVAE["examples/mcvae"]:::user
        ExamplesMT["examples/mt-mcvae"]:::user
    end

    %% mcvae Library Core
    subgraph "mcvae Library" 
        direction TB
        %% Datasets
        subgraph "Datasets" 
            direction TB
            Synthetic["synthetic.py"]:::core
        end

        %% Imputation
        subgraph "Imputation"
            direction TB
            Imputation["__init__.py"]:::core
        end

        %% Distributions
        subgraph "Distributions"
            direction TB
            LL["ll_utilities.py"]:::core
            KL["kl_utilities.py"]:::core
            Normal["normal.py"]:::core
            DistUtil["utilities.py"]:::core
        end

        %% Model Core
        subgraph "Models"
            direction TB
            VAE["vae.py"]:::core
            MC["mcvae.py"]:::core
            ModelUtil["utils.py"]:::core
        end

        %% GPU Acceleration
        subgraph "GPU Acceleration"
            direction TB
            GPU["__init__.py"]:::gpu
        end

        %% Training Loop & Diagnostics
        subgraph "Training & Diagnostics"
            direction TB
            Diagnostics["__init__.py"]:::diag
        end

        %% Visualization
        subgraph "Visualization"
            direction TB
            Plot["__init__.py"]:::plot
        end

        %% Utilities
        subgraph "Config & Utilities"
            direction TB
            FileIO["__init__.py"]:::core
            OS["__init__.py"]:::core
        end
    end

    %% External Tools and Assets
    subgraph "External & Project Metadata"
        direction TB
        Conda["environment.yml"]:::external
        Setup["setup.py"]:::external
        README["README.md"]:::external
        LICENSE["LICENSE"]:::external
        Fig["fig/"]:::external
        PyTorch["PyTorch"]:::external
    end

    %% Data Flow and Dependencies
    ExamplesMCVAE -->|"load_batch()"| Synthetic
    ExamplesMT -->|"load_batch()"| Synthetic
    Synthetic -->|"handle_missing()"| Imputation
    Imputation -->|"preprocessed_batch"| VAE
    Imputation -->|"preprocessed_batch"| MC
    VAE -->|"model_def"| Diagnostics
    MC -->|"model_def"| Diagnostics
    LL -->|"compute_loss()"| Diagnostics
    KL -->|"compute_kl()"| Diagnostics
    Normal -->|"sample_z()"| Diagnostics
    DistUtil -->|"dist_helpers()"| Diagnostics
    Diagnostics -->|"to_cuda()"| GPU
    GPU -->|"tensor_ops()"| Diagnostics
    Diagnostics -->|"metrics"| Plot

    %% Click Events
    click ExamplesMCVAE "https://github.com/ggbioing/mcvae/tree/master/examples/mcvae"
    click ExamplesMT "https://github.com/ggbioing/mcvae/tree/master/examples/mt-mcvae"
    click Synthetic "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/datasets/synthetic.py"
    click Imputation "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/imputation/__init__.py"
    click LL "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/distributions/ll_utilities.py"
    click KL "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/distributions/kl_utilities.py"
    click Normal "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/distributions/normal.py"
    click DistUtil "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/distributions/utilities.py"
    click VAE "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/models/vae.py"
    click MC "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/models/mcvae.py"
    click ModelUtil "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/models/utils.py"
    click GPU "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/gpu/__init__.py"
    click Diagnostics "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/diagnostics/__init__.py"
    click Plot "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/plot/__init__.py"
    click FileIO "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/utilities/__init__.py"
    click OS "https://github.com/ggbioing/mcvae/blob/master/src/mcvae/os/__init__.py"
    click Conda "https://github.com/ggbioing/mcvae/blob/master/environment.yml"
    click Setup "https://github.com/ggbioing/mcvae/blob/master/setup.py"
    click README "https://github.com/ggbioing/mcvae/blob/master/README.md"
    click LICENSE "https://github.com/ggbioing/mcvae/tree/master/LICENSE"
    click Fig "https://github.com/ggbioing/mcvae/tree/master/fig/"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#004A9F,color:#004A9F;
    classDef user fill:#DFFFE0,stroke:#2F8F00,color:#2F8F00;
    classDef external fill:#FFF4D6,stroke:#A66C00,color:#A66C00;
    classDef gpu fill:#FFE0F0,stroke:#D0006F,color:#D0006F;
    classDef diag fill:#F0E6FF,stroke:#5F00A6,color:#5F00A6;
    classDef plot fill:#FFEFD6,stroke:#A65B00,color:#A65B00;
```
