# jacobyhsi/tabrep architecture

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

- Interactive diagram: https://gitdiagram.com/jacobyhsi/tabrep
- Repository: https://github.com/jacobyhsi/tabrep

## Overview

TabRep is a research toolkit for training and comparing tabular synthetic-data generators. The principal workflow is to prepare a dataset, select a method and train or sample through the command-line entry point, then evaluate generated data. The repository also includes documented baseline generators and a low-dimensional TabSYN-style VAE/diffusion experiment. Training and sampling internals are only partly sampled, so method-to-internal-model links are shown only where the source index or excerpts support them; documented capabilities are retained without assuming their internal call graphs.

Main entry points: [`main.py`](https://github.com/jacobyhsi/tabrep/blob/main/main.py) (Experiment CLI), [`tabrep_ddpm/train.py`](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/train.py) (DDPM training), [`tabrep_ddpm/sample.py`](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/sample.py) (DDPM sampling), [`tabrep_flow/train.py`](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/train.py) (Flow training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Data and CLI"]
  node_cli["Experiment CLI<br/>[main.py]"]
  node_download["Dataset download"]
  node_process["Dataset processing<br/>[process_dataset.py]"]
  node_preprocess["Shared preprocessing<br/>[utils_train.py]"]
  node_data["Dataset transforms<br/>[data.py]"]
  node_env["Dataset environment<br/>[env.py]"]
  node_metrics["Task metrics<br/>[metrics.py]"]
end

subgraph group_tabrep["TabRep Models"]
  node_ddpm_train["DDPM training<br/>[train.py]"]
  node_ddpm_diffusion["Mixed diffusion"]
  node_ddpm_modules["DDPM networks<br/>[modules.py]"]
  node_ddpm_sample["DDPM sampling<br/>[sample.py]"]
  node_flow_train["Flow training<br/>[train.py]"]
  node_flow_matching["Flow matching<br/>[flow_matching.py]"]
  node_flow_modules["Flow networks<br/>[modules.py]"]
  node_flow_sample["Flow sampling<br/>[sample.py]"]
end

subgraph group_baselines["Baseline Models"]
  node_codi["CoDi generator"]
  node_ctgan["CTGAN and TVAE"]
  node_goggle["Goggle generator<br/>[GoggleModel.py]"]
  node_great["GReaT generator<br/>[great.py]"]
  node_smote["SMOTE baseline<br/>[main.py]"]
  node_stasy["STaSy generator<br/>[losses.py]"]
  node_tabddpm["TabDDPM baseline"]
  node_tabsyn["TabSYN baseline<br/>[latent_utils.py]"]
  node_lowdim["Low-dim VAE<br/>[model.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_mle["ML efficiency<br/>[eval_mle.py]"]
  node_eval_density["Density evaluation<br/>[eval_density.py]"]
  node_eval_quality["Quality evaluation<br/>[eval_quality.py]"]
  node_eval_detection["Detection evaluation<br/>[eval_detection.py]"]
  node_eval_privacy["Privacy evaluation<br/>[eval_privacy.py]"]
end

node_user(("Researcher"))

node_user -->|"obtains data"| node_download
node_user -->|"prepares data"| node_process
node_user -->|"selects method"| node_cli
node_download -->|"provides datasets"| node_process
node_cli -->|"dispatches train"| node_ddpm_train
node_cli -->|"dispatches sample"| node_ddpm_sample
node_cli -->|"dispatches train"| node_flow_train
node_cli -->|"dispatches sample"| node_flow_sample
node_cli -->|"selects baseline"| node_codi
node_cli -->|"selects baseline"| node_ctgan
node_cli -->|"selects baseline"| node_goggle
node_cli -->|"selects baseline"| node_great
node_cli -->|"selects baseline"| node_smote
node_cli -->|"selects baseline"| node_stasy
node_cli -->|"selects baseline"| node_tabddpm
node_cli -->|"selects baseline"| node_tabsyn
node_preprocess -->|"transforms dataset"| node_data
node_ddpm_train -->|"preprocesses data"| node_preprocess
node_ddpm_train -->|"uses networks"| node_ddpm_modules
node_ddpm_train -->|"trains diffusion"| node_ddpm_diffusion
node_ddpm_sample -->|"uses networks"| node_ddpm_modules
node_ddpm_sample -.->|"samples diffusion"| node_ddpm_diffusion
node_flow_train -.->|"trains flow"| node_flow_matching
node_flow_train -.->|"uses networks"| node_flow_modules
node_flow_sample -->|"samples flow"| node_flow_matching
node_flow_sample -->|"uses networks"| node_flow_modules
node_user -->|"evaluates output"| node_eval_mle
node_user -->|"evaluates output"| node_eval_density
node_user -->|"evaluates output"| node_eval_quality
node_user -->|"evaluates output"| node_eval_detection
node_user -->|"evaluates output"| node_eval_privacy

click node_cli "https://github.com/jacobyhsi/tabrep/blob/main/main.py"
click node_download "https://github.com/jacobyhsi/tabrep/blob/main/download_dataset.py"
click node_process "https://github.com/jacobyhsi/tabrep/blob/main/process_dataset.py"
click node_preprocess "https://github.com/jacobyhsi/tabrep/blob/main/utils_train.py"
click node_data "https://github.com/jacobyhsi/tabrep/blob/main/src/data.py"
click node_env "https://github.com/jacobyhsi/tabrep/blob/main/src/env.py"
click node_metrics "https://github.com/jacobyhsi/tabrep/blob/main/src/metrics.py"
click node_ddpm_train "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/train.py"
click node_ddpm_diffusion "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/models/gaussian_multinomial_distribution.py"
click node_ddpm_modules "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/models/modules.py"
click node_ddpm_sample "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/sample.py"
click node_flow_train "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/train.py"
click node_flow_matching "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/models/flow_matching.py"
click node_flow_modules "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/models/modules.py"
click node_flow_sample "https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/sample.py"
click node_codi "https://github.com/jacobyhsi/tabrep/blob/main/baselines/codi/diffusion_discrete.py"
click node_ctgan "https://github.com/jacobyhsi/tabrep/tree/main/baselines/ctgan/models"
click node_goggle "https://github.com/jacobyhsi/tabrep/blob/main/baselines/goggle/GoggleModel.py"
click node_great "https://github.com/jacobyhsi/tabrep/blob/main/baselines/great/models/great.py"
click node_smote "https://github.com/jacobyhsi/tabrep/blob/main/baselines/smote/main.py"
click node_stasy "https://github.com/jacobyhsi/tabrep/blob/main/baselines/stasy/losses.py"
click node_tabddpm "https://github.com/jacobyhsi/tabrep/blob/main/baselines/tabddpm/models/gaussian_multinomial_distribution.py"
click node_tabsyn "https://github.com/jacobyhsi/tabrep/blob/main/baselines/tabsyn/latent_utils.py"
click node_lowdim "https://github.com/jacobyhsi/tabrep/blob/main/ablations/tabsyn_lowdim/vae/model.py"
click node_eval_mle "https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_mle.py"
click node_eval_density "https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_density.py"
click node_eval_quality "https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_quality.py"
click node_eval_detection "https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_detection.py"
click node_eval_privacy "https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_privacy.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_cli,node_download,node_process,node_preprocess,node_data,node_env,node_metrics toneBlue
class node_ddpm_train,node_ddpm_diffusion,node_ddpm_modules,node_ddpm_sample,node_flow_train,node_flow_matching,node_flow_modules,node_flow_sample toneAmber
class node_codi,node_ctgan,node_goggle,node_great,node_smote,node_stasy,node_tabddpm,node_tabsyn,node_lowdim toneMint
class node_eval_mle,node_eval_density,node_eval_quality,node_eval_detection,node_eval_privacy toneRose
class node_user toneIndigo
```

## Components

### Data and CLI

- [Experiment CLI](https://github.com/jacobyhsi/tabrep/blob/main/main.py): `main.py`
- [Dataset download](https://github.com/jacobyhsi/tabrep/blob/main/download_dataset.py): `download_dataset.py`
- [Dataset processing](https://github.com/jacobyhsi/tabrep/blob/main/process_dataset.py): `process_dataset.py`
- [Shared preprocessing](https://github.com/jacobyhsi/tabrep/blob/main/utils_train.py): `utils_train.py`
- [Dataset transforms](https://github.com/jacobyhsi/tabrep/blob/main/src/data.py): `src/data.py`
- [Dataset environment](https://github.com/jacobyhsi/tabrep/blob/main/src/env.py): `src/env.py`
- [Task metrics](https://github.com/jacobyhsi/tabrep/blob/main/src/metrics.py): `src/metrics.py`

### TabRep Models

- [DDPM training](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/train.py): `tabrep_ddpm/train.py`
- [Mixed diffusion](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/models/gaussian_multinomial_distribution.py): `tabrep_ddpm/models/gaussian_multinomial_distribution.py`
- [DDPM networks](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/models/modules.py): `tabrep_ddpm/models/modules.py`
- [DDPM sampling](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_ddpm/sample.py): `tabrep_ddpm/sample.py`
- [Flow training](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/train.py): `tabrep_flow/train.py`
- [Flow matching](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/models/flow_matching.py): `tabrep_flow/models/flow_matching.py`
- [Flow networks](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/models/modules.py): `tabrep_flow/models/modules.py`
- [Flow sampling](https://github.com/jacobyhsi/tabrep/blob/main/tabrep_flow/sample.py): `tabrep_flow/sample.py`

### Baseline Models

- [CoDi generator](https://github.com/jacobyhsi/tabrep/blob/main/baselines/codi/diffusion_discrete.py): `baselines/codi/diffusion_discrete.py`
- [CTGAN and TVAE](https://github.com/jacobyhsi/tabrep/tree/main/baselines/ctgan/models): `baselines/ctgan/models`
- [Goggle generator](https://github.com/jacobyhsi/tabrep/blob/main/baselines/goggle/GoggleModel.py): `baselines/goggle/GoggleModel.py`
- [GReaT generator](https://github.com/jacobyhsi/tabrep/blob/main/baselines/great/models/great.py): `baselines/great/models/great.py`
- [SMOTE baseline](https://github.com/jacobyhsi/tabrep/blob/main/baselines/smote/main.py): `baselines/smote/main.py`
- [STaSy generator](https://github.com/jacobyhsi/tabrep/blob/main/baselines/stasy/losses.py): `baselines/stasy/losses.py`
- [TabDDPM baseline](https://github.com/jacobyhsi/tabrep/blob/main/baselines/tabddpm/models/gaussian_multinomial_distribution.py): `baselines/tabddpm/models/gaussian_multinomial_distribution.py`
- [TabSYN baseline](https://github.com/jacobyhsi/tabrep/blob/main/baselines/tabsyn/latent_utils.py): `baselines/tabsyn/latent_utils.py`
- [Low-dim VAE](https://github.com/jacobyhsi/tabrep/blob/main/ablations/tabsyn_lowdim/vae/model.py): `ablations/tabsyn_lowdim/vae/model.py`

### Evaluation

- [ML efficiency](https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_mle.py): `eval/eval_mle.py`
- [Density evaluation](https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_density.py): `eval/eval_density.py`
- [Quality evaluation](https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_quality.py): `eval/eval_quality.py`
- [Detection evaluation](https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_detection.py): `eval/eval_detection.py`
- [Privacy evaluation](https://github.com/jacobyhsi/tabrep/blob/main/eval/eval_privacy.py): `eval/eval_privacy.py`

### Other components

- **Researcher**

## Connections

- Researcher → Dataset download: obtains data
- Researcher → Dataset processing: prepares data
- Researcher → Experiment CLI: selects method
- Dataset download → Dataset processing: provides datasets
- Experiment CLI → DDPM training: dispatches train
- Experiment CLI → DDPM sampling: dispatches sample
- Experiment CLI → Flow training: dispatches train
- Experiment CLI → Flow sampling: dispatches sample
- Experiment CLI → CoDi generator: selects baseline
- Experiment CLI → CTGAN and TVAE: selects baseline
- Experiment CLI → Goggle generator: selects baseline
- Experiment CLI → GReaT generator: selects baseline
- Experiment CLI → SMOTE baseline: selects baseline
- Experiment CLI → STaSy generator: selects baseline
- Experiment CLI → TabDDPM baseline: selects baseline
- Experiment CLI → TabSYN baseline: selects baseline
- Shared preprocessing → Dataset transforms: transforms dataset (evidence: `utils_train.py`)
- DDPM training → Shared preprocessing: preprocesses data (evidence: `utils_train.py`)
- DDPM training → DDPM networks: uses networks (evidence: `tabrep_ddpm/train.py`)
- DDPM training → Mixed diffusion: trains diffusion (evidence: `tabrep_ddpm/train.py`)
- DDPM sampling → DDPM networks: uses networks
- DDPM sampling → Mixed diffusion: samples diffusion
- Flow training → Flow matching: trains flow
- Flow training → Flow networks: uses networks
- Flow sampling → Flow matching: samples flow (evidence: `tabrep_flow/sample.py`)
- Flow sampling → Flow networks: uses networks (evidence: `tabrep_flow/sample.py`)
- Researcher → ML efficiency: evaluates output
- Researcher → Density evaluation: evaluates output
- Researcher → Quality evaluation: evaluates output
- Researcher → Detection evaluation: evaluates output
- Researcher → Privacy evaluation: evaluates output
