tabstruct 2026.3.4

TabStruct is a comprehensive benchmark suite for tabular data generation, prediction, and evaluation.

[ICLR 2026 Oral] TabStruct – Tabular Structural Fidelity

[!IMPORTANT] Official code for the paper "TabStruct: Measuring Structural Fidelity of Tabular Data", published in The Fourteenth International Conference on Learning Representations (ICLR 2026 Oral).

TabStruct provides the full experimental pipeline used in the paper, including generation, predictive modelling, and evaluation protocols for structural fidelity.

Authored by Xiangjian Jiang, Nikola Simidjievski, Mateja Jamnik, University of Cambridge, UK

📌 Overview

TabStruct is an end‑to‑end benchmark for tabular data generation, prediction, and evaluation. It ships with ready‑to‑use pipelines for

• generating high‑quality synthetic tables,
• predicting with machine learning models, and
• analysing results with a rich suite of metrics – especially those that quantify structural fidelity.

The benchmark is designed for both research and applied workflows: you can run standard baselines out of the box, or plug in custom generators/predictors and fairly evaluate them under the same protocol. All components are designed to plug‑and‑play, so you can mix, match, and extend them to suit your own workflow.

📚 Key Features

Data generation

• Out‑of‑the‑box support for popular tabular generators: SMOTE, TVAE, CTGAN, NFlow, TabDDPM, ARF, and more.
• Supports customised setups (classical oversampling, deep generative models, and probabilistic approaches) so different modelling assumptions can be compared under one interface.

Evaluation dimensions

• Density estimation – How well does the synthetic data approximate the real distribution?
• Privacy preservation – Does the generator leak sensitive records?
• ML efficacy – How do models trained on synthetic data perform compared to real data?
• Structural fidelity – Does the generator respect the causal structures of real data?

Predictive tasks

• Classification & regression pipelines built on scikit‑learn, with optional neural‑network backbones.
• Unified training/evaluation entry points make it straightforward to benchmark models across datasets with consistent splits, logging, and reproducibility settings.

🚀 Installation

We recommend managing dependencies with conda + mamba.

# 1️⃣ Upgrade conda and activate the base env
conda update -n base -c conda-forge conda
conda activate base

# 2️⃣ Install the high‑performance dependency resolver
conda install conda-libmamba-solver --yes
conda config --set solver libmamba
conda install -c conda-forge mamba --yes

# 3️⃣ Create a new conda env
conda create --name tabstruct python=3.10.18 --no-default-packages
conda activate tabstruct

# 4️⃣ Set up the env
bash scripts/utils/install.sh

📊 Logging with W&B

TabStruct logs every experiment to Weights & Biases (W&B). Use the default project or set your own credentials in src/tabstruct/common/__init__.py:

WANDB_ENTITY  = "tabular-data-generation"
WANDB_PROJECT = "TabStruct"

✅ Quick sanity check

Run a toy classification job (K‑NN on the Adult dataset):

python -m src.tabstruct.experiment.run_experiment \
  --model knn \
  --save_model \
  --dataset adult \
  --test_size 0.2 \
  --valid_size 0.1 \
  --tags ENV-TEST

A successful run prints a series of green log lines like:

[YYYY‑MM‑DD] Codebase: >>>>>>>>>> Launching create_data_module() <<<<<<<<<<<
…

If you see those, congratulations – your environment is ready! 🎉

💥 Example Workflows

1. Generate synthetic data

Template script: docs/tutorial/example_scripts/generation/train.sh

python -m src.tabstruct.experiment.run_experiment \
    --pipeline "generation" \
    --generation_only \
    --model "smote" \
    --dataset "mfeat-fourier" \
    --test_size 0.2 \
    --valid_size 0.1 \
    --tags "dev"

2. Evaluate synthetic data

Template script: docs/tutorial/example_scripts/generation/eval.sh

python -m src.tabstruct.experiment.run_experiment \
	--pipeline "generation" \
	--model "smote" \
	--eval_only \
	--dataset "mfeat-fourier" \
	--test_size 0.2 \
	--valid_size 0.1 \
	--generator_tags "dev" \
	--tags "dev"

3. Predict on tabular data

Template script: docs/tutorial/example_scripts/prediction/train.sh

python -m src.tabstruct.experiment.run_experiment \
	--model 'mlp' \
	--save_model \
	--max_steps_tentative 1500 \
	--dataset 'adult' \
	--test_size 0.2 \
	--valid_size 0.1 \
	--tags 'dev'

📖 Citation

For attribution in academic contexts, please cite this work as:

@inproceedings{jiang2026tabstruct,
  title={TabStruct: Measuring Structural Fidelity of Tabular Data},
  author={Jiang, Xiangjian and Simidjievski, Nikola and Jamnik, Mateja},
  booktitle={The Fourteenth International Conference on Learning Representations},
  year={2026}
}


@inproceedings{jiang2025well,
  title={How Well Does Your Tabular Generator Learn the Structure of Tabular Data?},
  author={Jiang, Xiangjian and Simidjievski, Nikola and Jamnik, Mateja},
  booktitle={ICLR 2025 Workshop on Deep Generative Model in Machine Learning: Theory, Principle and Efficacy}
}