# johnlyj/vae_omics architecture

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

- Interactive diagram: https://gitdiagram.com/johnlyj/vae_omics
- Repository: https://github.com/johnlyj/vae_omics

## Overview

##### Project type and purpose
- This is a research‐oriented full-pipeline machine learning project implementing a Multimodal Variational Autoencoder (VAE) to integrate single-cell RNA-seq and ATAC-seq data.
- The goal is to learn a shared latent representation for cross-modal imputation and downstream analysis (clustering, visualization).

##### File structure
- Top–level scripts:
- main.py – orchestrates preprocessing, model instantiation, training, and saving checkpoints
- Directories:
- data/ – raw‐data loader and preprocess.py (normalization, log-transform, HVG selection, LSI)
- models/ – encoder.py, fusion.py (MLP or Product of Experts), decoder.py, vae.py (VAE assembly)
- training/ – train.py, eval.py, loss.py (training loop, KL annealing, evaluation metrics)
- results/ – output plots
- Supporting files: requirements.txt, .gitignore, README.md

##### Key insights from README
- Separate modality pipelines (RNA vs ATAC) → two encoders, two decoders
- Fusion strategies: MLP vs PoE
- KL-annealing schedule for posterior collapse mitigation
- Quantitative evaluation: cosine similarity & Pearson correlation
- Visualization: UMAP + Leiden clustering

##### Main components
a. Data ingestion & preprocessing
- Input: 10x Multiome H5 file
- RNA-seq pipeline: normalization → log-transform → HVG selection
- ATAC-seq pipeline: filtering → LSI (SVD)
b. Model
- Encoder_RNA → latent parameters (µ_r, σ_r)
- Encoder_ATAC → latent parameters (µ_a, σ_a)
- Fusion module
– MLP Fusion: concat(µ_r, µ_a, σ_r, σ_a) → MLP → µ_z, σ_z
– PoE Fusion: combine distributions mathematically → µ_z, σ_z
- Sampling z ∼ N(µ_z, σ_z)
- Decoder_RNA(z) → reconstructed RNA
- Decoder_ATAC(z) → reconstructed ATAC
c. Training loop
- Loss computation: reconstruction losses + KL divergence (with KL-annealing schedule)
- Optimizer step (e.g., Adam)
- Checkpointing
d. Evaluation & Visualization
- eval.py: compute cosine similarity & Pearson correlation for cross-modal imputation

##### Relationships & interactions
- Data → Preprocess → Batch tensors → Model (encode → fuse → decode)
- Training orchestrates forward/backward passes → checkpoint outputs → metrics logged
- Post‐training: checkpoints + raw data → evaluation → quantitative metrics
- Visualization scripts consume checkpoints + data → output plots

##### Architectural patterns & design principles
- Modular components: clear separation of data, models, training, and visualization
- Pipeline pattern: data-flow graph from raw input to final plots
- Dependency inversion: components interact via well-defined interfaces (e.g., model.forward, preprocess functions)
- Configurable fusion strategy injected at model‐construction time

##### Technologies & frameworks
- Python 3.x
- ML framework: likely PyTorch or TensorFlow (inferred from model code structure)
- Scientific libs: NumPy, SciPy, scikit-learn (SVD/LSI), scanpy/anndata (optional)
- Visualization: Matplotlib, Seaborn, UMAP, Leiden clustering (leidenalg)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Data Layer
  subgraph "Data Layer"
    direction TB
    Raw["10x Multiome H5"]:::data
    Preprocess["Data Ingestion & Preprocessing"]:::data
  end

  %% Model Layer
  subgraph "Model Layer"
    direction TB
    ER["Encoder_RNA"]:::model
    EA["Encoder_ATAC"]:::model
    Fusion["Fusion Module\n(MLP & PoE)"]:::model
    VAES["VAE Assembly\n(Reparameterization & Forward Pass)"]:::model
    DR["Decoder_RNA"]:::model
    DA["Decoder_ATAC"]:::model
  end

  %% Training & Evaluation Layer
  subgraph "Training & Evaluation"
    direction TB
    Main["Main Orchestration Script"]:::train
    Train["Training Loop & Checkpointing"]:::train
    Loss["Loss Computation\n(Reconstruction + KL + Annealing)"]:::train
    Eval["Quantitative Evaluation\n(Cosine & Pearson)"]:::train
  end

  %% Visualization & Results Layer
  subgraph "Visualization & Results"
    direction TB
    RunVis["Visualization Entry Point"]:::viz
    VisUtil["Visualization Utilities\n(UMAP, Clustering, Plots)"]:::viz
    Plots["Output Plots Directory"]:::viz
  end

  %% Data Flow
  Raw --> Preprocess
  Preprocess --> ER
  Preprocess --> EA
  ER --> Fusion
  EA --> Fusion
  Fusion --> VAES
  VAES --> DR
  VAES --> DA

  %% Training and Control Flow
  Main --> Preprocess
  Main --> Train
  Train -->|uses Model| ER
  Train -->|uses Model| EA
  Train -->|uses Fusion| Fusion
  Train -->|uses VAE| VAES
  Train --> Loss
  Train -->|checkpoints| Train
  Train -->|outputs Checkpoints| Eval
  Eval -->|metrics| Main

  %% Visualization Flow
  Main --> RunVis
  RunVis --> VisUtil
  VisUtil --> Plots

  %% Click Events
  click Preprocess "https://github.com/johnlyj/vae_omics/blob/main/data/preprocess.py"
  click Main "https://github.com/johnlyj/vae_omics/blob/main/main.py"
  click ER "https://github.com/johnlyj/vae_omics/blob/main/models/encoder.py"
  click EA "https://github.com/johnlyj/vae_omics/blob/main/models/encoder.py"
  click Fusion "https://github.com/johnlyj/vae_omics/blob/main/models/fusion.py"
  click VAES "https://github.com/johnlyj/vae_omics/blob/main/models/vae.py"
  click DR "https://github.com/johnlyj/vae_omics/blob/main/models/decoder.py"
  click DA "https://github.com/johnlyj/vae_omics/blob/main/models/decoder.py"
  click Train "https://github.com/johnlyj/vae_omics/blob/main/training/train.py"
  click Loss "https://github.com/johnlyj/vae_omics/blob/main/training/loss.py"
  click Eval "https://github.com/johnlyj/vae_omics/blob/main/training/eval.py"
  click RunVis "https://github.com/johnlyj/vae_omics/blob/main/run_visualization.py"
  click VisUtil "https://github.com/johnlyj/vae_omics/blob/main/scripts/visualize.py"
  click Plots "https://github.com/johnlyj/vae_omics/tree/main/results/plots"

  %% Styles
  classDef data fill:#D0E6FF,stroke:#000,stroke-width:1px;
  classDef model fill:#D0FFD8,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
  classDef train fill:#FFE1B3,stroke:#000,stroke-width:1px;
  classDef viz fill:#E5D0FF,stroke:#000,stroke-width:1px;
```
