# amazon-science/tabsyn architecture

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

- Interactive diagram: https://gitdiagram.com/amazon-science/tabsyn
- Repository: https://github.com/amazon-science/tabsyn

## Overview

TabSyn is a mixed-type tabular-data synthesis research repository. Its principal workflow prepares tabular datasets, trains a VAE to encode them into a continuous latent space, trains score-based diffusion over those embeddings, and samples synthetic tables. The repository also offers six baseline synthesizers, several synthetic-data evaluation metrics, and target-column imputation. The README documents these capabilities; some baseline sampling and evaluation internals were not excerpted, so their links are limited to documented workflows.

Main entry points: [`tabsyn/vae/main.py`](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/vae/main.py) (VAE training), [`tabsyn/main.py`](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/main.py) (Latent diffusion training), [`impute.py`](https://github.com/amazon-science/tabsyn/blob/main/impute.py) (Target imputation), [`src/data.py`](https://github.com/amazon-science/tabsyn/blob/main/src/data.py) (Shared data transforms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_download["Dataset download"]
  node_processing["Dataset processing<br/>[process_dataset.py]"]
  node_shared_data["Shared data transforms<br/>[data.py]"]
  node_train_helpers["Training preprocessing<br/>[utils_train.py]"]
end

subgraph group_tabsyn["TabSyn synthesis"]
  node_vae_training["VAE training<br/>[main.py]"]
  node_vae_model["VAE encoder<br/>[model.py]"]
  node_latent["Latent preparation<br/>[latent_utils.py]"]
  node_diffusion_training["Latent diffusion training<br/>[main.py]"]
  node_diffusion_model["Diffusion model<br/>[model.py]"]
  node_tabsyn_sampling["TabSyn sampling<br/>[sample.py]"]
end

subgraph group_baselines["Baseline synthesis"]
  node_baseline_smote["SMOTE baseline<br/>[main.py]"]
  node_baseline_codi["CoDi baseline"]
  node_baseline_goggle["GOGGLE baseline<br/>[GoggleModel.py]"]
  node_baseline_great["GReaT baseline<br/>[great.py]"]
  node_baseline_stasy["STaSy baseline<br/>[main.py]"]
  node_baseline_tabddpm["TabDDPM baseline"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Synthetic data evaluation"]
  node_density["Density metrics<br/>[eval_density.py]"]
  node_quality["Quality metrics<br/>[eval_quality.py]"]
  node_mle["ML efficiency<br/>[eval_mle.py]"]
  node_privacy["Privacy distance<br/>[eval_dcr.py]"]
  node_detection["Two-sample detection<br/>[eval_detection.py]"]
end

subgraph group_imputation["Imputation"]
  node_impute["Target imputation<br/>[impute.py]"]
  node_impute_eval["Imputation evaluation<br/>[eval_impute.py]"]
end

node_user(("Researcher"))
node_raw_data[("Raw tables")]
node_synthetic[("Synthetic tables")]

node_user -->|"requests datasets"| node_download
node_download -->|"downloads"| node_raw_data
node_raw_data -->|"processes"| node_processing
node_processing -.->|"prepares splits"| node_shared_data
node_user -->|"starts training"| node_vae_training
node_shared_data -->|"provides dataset data"| node_train_helpers
node_vae_training -->|"loads preprocessing"| node_train_helpers
node_vae_training -->|"trains"| node_vae_model
node_vae_model -->|"encodes tables"| node_latent
node_user -->|"starts diffusion training"| node_diffusion_training
node_diffusion_training -->|"loads embeddings"| node_latent
node_diffusion_training -->|"trains"| node_diffusion_model
node_user -->|"requests synthesis"| node_tabsyn_sampling
node_tabsyn_sampling -->|"writes samples"| node_synthetic
node_user -->|"selects baseline"| node_baseline_smote
node_user -->|"selects baseline"| node_baseline_codi
node_user -->|"selects baseline"| node_baseline_goggle
node_user -->|"selects baseline"| node_baseline_great
node_user -->|"selects baseline"| node_baseline_stasy
node_user -->|"selects baseline"| node_baseline_tabddpm
node_baseline_smote -.->|"writes samples"| node_synthetic
node_baseline_codi -.->|"writes samples"| node_synthetic
node_baseline_goggle -.->|"writes samples"| node_synthetic
node_baseline_great -.->|"writes samples"| node_synthetic
node_baseline_stasy -.->|"writes samples"| node_synthetic
node_baseline_tabddpm -.->|"writes samples"| node_synthetic
node_user -->|"evaluates samples"| node_evaluation
node_synthetic -->|"supplies samples"| node_density
node_synthetic -->|"supplies samples"| node_quality
node_synthetic -->|"supplies samples"| node_mle
node_synthetic -->|"supplies samples"| node_privacy
node_synthetic -->|"supplies samples"| node_detection
node_user -->|"requests imputation"| node_impute
node_impute -.->|"uses dataset data"| node_shared_data
node_impute -->|"evaluates imputations"| node_impute_eval

click node_download "https://github.com/amazon-science/tabsyn/blob/main/download_dataset.py"
click node_processing "https://github.com/amazon-science/tabsyn/blob/main/process_dataset.py"
click node_shared_data "https://github.com/amazon-science/tabsyn/blob/main/src/data.py"
click node_train_helpers "https://github.com/amazon-science/tabsyn/blob/main/utils_train.py"
click node_vae_training "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/vae/main.py"
click node_vae_model "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/vae/model.py"
click node_latent "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/latent_utils.py"
click node_diffusion_training "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/main.py"
click node_diffusion_model "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/model.py"
click node_tabsyn_sampling "https://github.com/amazon-science/tabsyn/blob/main/tabsyn/sample.py"
click node_baseline_smote "https://github.com/amazon-science/tabsyn/blob/main/baselines/smote/main.py"
click node_baseline_codi "https://github.com/amazon-science/tabsyn/blob/main/baselines/codi/diffusion_discrete.py"
click node_baseline_goggle "https://github.com/amazon-science/tabsyn/blob/main/baselines/goggle/GoggleModel.py"
click node_baseline_great "https://github.com/amazon-science/tabsyn/blob/main/baselines/great/models/great.py"
click node_baseline_stasy "https://github.com/amazon-science/tabsyn/blob/main/baselines/stasy/main.py"
click node_baseline_tabddpm "https://github.com/amazon-science/tabsyn/blob/main/baselines/tabddpm/models/gaussian_multinomial_distribution.py"
click node_evaluation "https://github.com/amazon-science/tabsyn/tree/main/eval"
click node_density "https://github.com/amazon-science/tabsyn/blob/main/eval/eval_density.py"
click node_quality "https://github.com/amazon-science/tabsyn/blob/main/eval/eval_quality.py"
click node_mle "https://github.com/amazon-science/tabsyn/blob/main/eval/eval_mle.py"
click node_privacy "https://github.com/amazon-science/tabsyn/blob/main/eval/eval_dcr.py"
click node_detection "https://github.com/amazon-science/tabsyn/blob/main/eval/eval_detection.py"
click node_impute "https://github.com/amazon-science/tabsyn/blob/main/impute.py"
click node_impute_eval "https://github.com/amazon-science/tabsyn/blob/main/eval_impute.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_download,node_processing,node_shared_data,node_train_helpers toneBlue
class node_vae_training,node_vae_model,node_latent,node_diffusion_training,node_diffusion_model,node_tabsyn_sampling,node_raw_data,node_synthetic toneAmber
class node_baseline_smote,node_baseline_codi,node_baseline_goggle,node_baseline_great,node_baseline_stasy,node_baseline_tabddpm toneMint
class node_evaluation,node_density,node_quality,node_mle,node_privacy,node_detection toneRose
class node_impute,node_impute_eval,node_user toneIndigo
```

## Components

### Data preparation

- [Dataset download](https://github.com/amazon-science/tabsyn/blob/main/download_dataset.py): `download_dataset.py`
- [Dataset processing](https://github.com/amazon-science/tabsyn/blob/main/process_dataset.py): `process_dataset.py`
- [Shared data transforms](https://github.com/amazon-science/tabsyn/blob/main/src/data.py): `src/data.py`
- [Training preprocessing](https://github.com/amazon-science/tabsyn/blob/main/utils_train.py): `utils_train.py`

### TabSyn synthesis

- [VAE training](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/vae/main.py): `tabsyn/vae/main.py`
- [VAE encoder](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/vae/model.py): `tabsyn/vae/model.py`
- [Latent preparation](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/latent_utils.py): `tabsyn/latent_utils.py`
- [Latent diffusion training](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/main.py): `tabsyn/main.py`
- [Diffusion model](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/model.py): `tabsyn/model.py`
- [TabSyn sampling](https://github.com/amazon-science/tabsyn/blob/main/tabsyn/sample.py): `tabsyn/sample.py`

### Baseline synthesis

- [SMOTE baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/smote/main.py): `baselines/smote/main.py`
- [CoDi baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/codi/diffusion_discrete.py): `baselines/codi/diffusion_discrete.py`
- [GOGGLE baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/goggle/GoggleModel.py): `baselines/goggle/GoggleModel.py`
- [GReaT baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/great/models/great.py): `baselines/great/models/great.py`
- [STaSy baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/stasy/main.py): `baselines/stasy/main.py`
- [TabDDPM baseline](https://github.com/amazon-science/tabsyn/blob/main/baselines/tabddpm/models/gaussian_multinomial_distribution.py): `baselines/tabddpm/models/gaussian_multinomial_distribution.py`

### Evaluation

- [Synthetic data evaluation](https://github.com/amazon-science/tabsyn/tree/main/eval): `eval`
- [Density metrics](https://github.com/amazon-science/tabsyn/blob/main/eval/eval_density.py): `eval/eval_density.py`
- [Quality metrics](https://github.com/amazon-science/tabsyn/blob/main/eval/eval_quality.py): `eval/eval_quality.py`
- [ML efficiency](https://github.com/amazon-science/tabsyn/blob/main/eval/eval_mle.py): `eval/eval_mle.py`
- [Privacy distance](https://github.com/amazon-science/tabsyn/blob/main/eval/eval_dcr.py): `eval/eval_dcr.py`
- [Two-sample detection](https://github.com/amazon-science/tabsyn/blob/main/eval/eval_detection.py): `eval/eval_detection.py`

### Imputation

- [Target imputation](https://github.com/amazon-science/tabsyn/blob/main/impute.py): `impute.py`
- [Imputation evaluation](https://github.com/amazon-science/tabsyn/blob/main/eval_impute.py): `eval_impute.py`

### Other components

- **Researcher**
- **Raw tables**
- **Synthetic tables**

## Connections

- Researcher → Dataset download: requests datasets (evidence: `README.md`)
- Dataset download → Raw tables: downloads (evidence: `README.md`)
- Raw tables → Dataset processing: processes (evidence: `README.md`)
- Dataset processing → Shared data transforms: prepares splits
- Researcher → VAE training: starts training (evidence: `README.md`)
- Shared data transforms → Training preprocessing: provides dataset data (evidence: `utils_train.py`)
- VAE training → Training preprocessing: loads preprocessing (evidence: `tabsyn/vae/main.py`)
- VAE training → VAE encoder: trains (evidence: `tabsyn/vae/main.py`)
- VAE encoder → Latent preparation: encodes tables (evidence: `tabsyn/latent_utils.py`)
- Researcher → Latent diffusion training: starts diffusion training (evidence: `README.md`)
- Latent diffusion training → Latent preparation: loads embeddings (evidence: `tabsyn/main.py`)
- Latent diffusion training → Diffusion model: trains (evidence: `tabsyn/main.py`)
- Researcher → TabSyn sampling: requests synthesis (evidence: `README.md`)
- TabSyn sampling → Synthetic tables: writes samples (evidence: `README.md`)
- Researcher → SMOTE baseline: selects baseline (evidence: `README.md`)
- Researcher → CoDi baseline: selects baseline (evidence: `README.md`)
- Researcher → GOGGLE baseline: selects baseline (evidence: `README.md`)
- Researcher → GReaT baseline: selects baseline (evidence: `README.md`)
- Researcher → STaSy baseline: selects baseline (evidence: `README.md`)
- Researcher → TabDDPM baseline: selects baseline (evidence: `README.md`)
- SMOTE baseline → Synthetic tables: writes samples
- CoDi baseline → Synthetic tables: writes samples
- GOGGLE baseline → Synthetic tables: writes samples
- GReaT baseline → Synthetic tables: writes samples
- STaSy baseline → Synthetic tables: writes samples
- TabDDPM baseline → Synthetic tables: writes samples
- Researcher → Synthetic data evaluation: evaluates samples (evidence: `README.md`)
- Synthetic tables → Density metrics: supplies samples (evidence: `README.md`)
- Synthetic tables → Quality metrics: supplies samples (evidence: `README.md`)
- Synthetic tables → ML efficiency: supplies samples (evidence: `README.md`)
- Synthetic tables → Privacy distance: supplies samples (evidence: `README.md`)
- Synthetic tables → Two-sample detection: supplies samples (evidence: `README.md`)
- Researcher → Target imputation: requests imputation (evidence: `README.md`)
- Target imputation → Shared data transforms: uses dataset data
- Target imputation → Imputation evaluation: evaluates imputations (evidence: `README.md`)