# ku-medai/deg2mol architecture

> Architecture diagram of the GitHub repository ku-medai/deg2mol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ku-medai/deg2mol
- Repository: https://github.com/ku-medai/deg2mol

## Overview

DEG2MOL trains a conditional flow model to map transcriptomic profiles to the latent space of a pretrained scaffold-aware VAE, then decodes sampled latents into molecules. Its user-facing workflow accepts DEG tables, orders and validates gene features, encodes them with the GO-informed autoencoder, generates molecules, and saves results; training and test-set evaluation are separate entry points. The graph reflects README-documented capabilities where source excerpts were unavailable; those links cite the README rather than implying unsampled code was inspected.

Main entry points: [`inference.py`](https://github.com/ku-medai/deg2mol/blob/main/inference.py) (Inference entry), [`train.py`](https://github.com/ku-medai/deg2mol/blob/main/train.py) (Flow training), [`utils/generation.py`](https://github.com/ku-medai/deg2mol/blob/main/utils/generation.py) (Molecule generation), [`test.py`](https://github.com/ku-medai/deg2mol/blob/main/test.py) (Test evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_inference["Inference entry<br/>[inference.py]"]
  node_test["Test evaluation<br/>[test.py]"]
end

subgraph group_conditioning["DEG conditioning"]
  node_deg_input["DEG table"]
  node_deg_loader["DEG table loader<br/>[data.py]"]
  node_runtime["Runtime helpers<br/>[runtime.py]"]
  node_go_encoder["GO autoencoder<br/>[DEG_AE.py]"]
end

subgraph group_generation["Latent generation"]
  node_flow["Conditional flow<br/>[MLP.py]"]
  node_generation_engine["Molecule generation<br/>[generation.py]"]
  node_scafvae["ScafVAE decoder"]
  node_outputs["Generated molecules"]
end

subgraph group_training["Training and evaluation"]
  node_training_data[("Training data")]
  node_training_loop["Flow training<br/>[train.py]"]
  node_evaluation["Generation metrics<br/>[evaluation.py]"]
  node_training_utils["Training utilities<br/>[training_utils.py]"]
end

node_user(("Researcher"))

node_user -->|"submits profile"| node_inference
node_inference -->|"reads table"| node_deg_input
node_inference -->|"loads profiles"| node_deg_loader
node_inference -->|"loads assets"| node_runtime
node_inference -->|"conditions with"| node_go_encoder
node_inference -->|"initializes"| node_flow
node_inference -->|"invokes"| node_generation_engine
node_generation_engine -->|"encodes DEG"| node_go_encoder
node_generation_engine -->|"integrates flow"| node_flow
node_generation_engine -->|"decodes latents"| node_scafvae
node_generation_engine -->|"writes molecules"| node_outputs
node_user -->|"starts training"| node_training_loop
node_training_loop -->|"reads splits"| node_training_data
node_training_loop -->|"uses frozen encoder"| node_go_encoder
node_training_loop -->|"trains model"| node_flow
node_training_loop -->|"encodes molecules"| node_scafvae
node_training_loop -->|"saves checkpoints"| node_training_utils
node_user -->|"requests evaluation"| node_test
node_test -->|"generates samples"| node_generation_engine
node_test -->|"scores samples"| node_evaluation

click node_inference "https://github.com/ku-medai/deg2mol/blob/main/inference.py"
click node_test "https://github.com/ku-medai/deg2mol/blob/main/test.py"
click node_deg_loader "https://github.com/ku-medai/deg2mol/blob/main/utils/data.py"
click node_runtime "https://github.com/ku-medai/deg2mol/blob/main/utils/runtime.py"
click node_go_encoder "https://github.com/ku-medai/deg2mol/blob/main/models/DEGMON/DEG_AE.py"
click node_flow "https://github.com/ku-medai/deg2mol/blob/main/models/flow/MLP.py"
click node_generation_engine "https://github.com/ku-medai/deg2mol/blob/main/utils/generation.py"
click node_scafvae "https://github.com/ku-medai/deg2mol/tree/main/third_party/ScafVAE"
click node_training_loop "https://github.com/ku-medai/deg2mol/blob/main/train.py"
click node_evaluation "https://github.com/ku-medai/deg2mol/blob/main/utils/evaluation.py"
click node_training_utils "https://github.com/ku-medai/deg2mol/blob/main/utils/training_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inference,node_test toneBlue
class node_deg_input,node_deg_loader,node_runtime,node_go_encoder toneAmber
class node_flow,node_generation_engine,node_scafvae,node_outputs toneMint
class node_training_data,node_training_loop,node_evaluation,node_training_utils toneRose
class node_user toneIndigo
```

## Components

### Entry points

- [Inference entry](https://github.com/ku-medai/deg2mol/blob/main/inference.py): `inference.py`
- [Test evaluation](https://github.com/ku-medai/deg2mol/blob/main/test.py): `test.py`

### DEG conditioning

- **DEG table**
- [DEG table loader](https://github.com/ku-medai/deg2mol/blob/main/utils/data.py): `utils/data.py`
- [Runtime helpers](https://github.com/ku-medai/deg2mol/blob/main/utils/runtime.py): `utils/runtime.py`
- [GO autoencoder](https://github.com/ku-medai/deg2mol/blob/main/models/DEGMON/DEG_AE.py): `models/DEGMON/DEG_AE.py`

### Latent generation

- [Conditional flow](https://github.com/ku-medai/deg2mol/blob/main/models/flow/MLP.py): `models/flow/MLP.py`
- [Molecule generation](https://github.com/ku-medai/deg2mol/blob/main/utils/generation.py): `utils/generation.py`
- [ScafVAE decoder](https://github.com/ku-medai/deg2mol/tree/main/third_party/ScafVAE): `third_party/ScafVAE`
- **Generated molecules**

### Training and evaluation

- **Training data**
- [Flow training](https://github.com/ku-medai/deg2mol/blob/main/train.py): `train.py`
- [Generation metrics](https://github.com/ku-medai/deg2mol/blob/main/utils/evaluation.py): `utils/evaluation.py`
- [Training utilities](https://github.com/ku-medai/deg2mol/blob/main/utils/training_utils.py): `utils/training_utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Inference entry: submits profile (evidence: `README.md`)
- Inference entry → DEG table: reads table (evidence: `README.md`)
- Inference entry → DEG table loader: loads profiles (evidence: `inference.py`)
- Inference entry → Runtime helpers: loads assets (evidence: `inference.py`)
- Inference entry → GO autoencoder: conditions with (evidence: `inference.py`)
- Inference entry → Conditional flow: initializes (evidence: `inference.py`)
- Inference entry → Molecule generation: invokes (evidence: `inference.py`)
- Molecule generation → GO autoencoder: encodes DEG (evidence: `utils/generation.py`)
- Molecule generation → Conditional flow: integrates flow (evidence: `utils/generation.py`)
- Molecule generation → ScafVAE decoder: decodes latents (evidence: `utils/generation.py`)
- Molecule generation → Generated molecules: writes molecules (evidence: `utils/generation.py`)
- Researcher → Flow training: starts training (evidence: `README.md`)
- Flow training → Training data: reads splits (evidence: `README.md`)
- Flow training → GO autoencoder: uses frozen encoder (evidence: `train.py`)
- Flow training → Conditional flow: trains model (evidence: `train.py`)
- Flow training → ScafVAE decoder: encodes molecules (evidence: `train.py`)
- Flow training → Training utilities: saves checkpoints (evidence: `README.md`)
- Researcher → Test evaluation: requests evaluation (evidence: `README.md`)
- Test evaluation → Molecule generation: generates samples (evidence: `README.md`)
- Test evaluation → Generation metrics: scores samples (evidence: `README.md`)
