{"id":19932084,"url":"https://github.com/amazon-science/tabsyn","last_synced_at":"2025-09-20T23:32:58.372Z","repository":{"id":199790994,"uuid":"703165391","full_name":"amazon-science/tabsyn","owner":"amazon-science","description":"Official Implementations of \"Mixed-Type Tabular Data Synthesis with Score-based Diffusion in Latent Space\"\"","archived":false,"fork":false,"pushed_at":"2024-07-15T13:00:02.000Z","size":1460,"stargazers_count":112,"open_issues_count":16,"forks_count":37,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-01-06T04:07:48.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amazon-science.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-10T18:06:31.000Z","updated_at":"2025-01-05T05:26:07.000Z","dependencies_parsed_at":"2024-06-21T18:26:32.181Z","dependency_job_id":"d2932542-c4d6-4bda-9ca9-18ae2f5cfd7a","html_url":"https://github.com/amazon-science/tabsyn","commit_stats":null,"previous_names":["amazon-science/tabsyn"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Ftabsyn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Ftabsyn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Ftabsyn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Ftabsyn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amazon-science","download_url":"https://codeload.github.com/amazon-science/tabsyn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233694820,"owners_count":18715508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T23:08:58.727Z","updated_at":"2025-09-20T23:32:58.204Z","avatar_url":"https://github.com/amazon-science.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# (ICLR 2024 Oral) Mixed-Type Tabular Data Synthesis with Score-based Diffusion in Latent Space \n\n\u003cp align=\"center\"\u003e\n  \u003c!-- \u003ca href=\"https://github.com/hengruizhang98/tabsyn/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub License\" src=\"https://img.shields.io/github/license/hengruizhang98/tabsyn\"\u003e\n  \u003c/a\u003e --\u003e\n  \u003ca href=\"https://github.com/hengruizhang98/tabsyn/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub License\" src=\"https://img.shields.io/badge/license-Apache 2.0-green\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://openreview.net/forum?id=4Ay23yeuz0\"\u003e\n    \u003cimg alt=\"Openreview\" src=\"https://img.shields.io/badge/review-OpenReview-red\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://arxiv.org/abs/2310.09656\"\u003e\n    \u003cimg alt=\"Paper URL\" src=\"https://img.shields.io/badge/arxiv-2310.09656-blue\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis repository contains the implementation of the paper:\n\u003e **Mixed-Type Tabular Data Synthesis with Score-based Diffusion in Latent Space**  \u003cbr\u003e\n\u003e The Twelfth International Conference on Learning Representations (ICLR 2024, Oral Presentation)\u003cbr\u003e\n\u003e Hengrui Zhang, Jiani Zhang, Balasubramaniam Srinivasan, Zhengyuan Shen, Xiao Qin, Christos Faloutsos, Huzefa Rangwala, George Karypis \u003cbr\u003e\n\n## Latest Update\n- [2024-06-20]: Disable loading irrelvent packages when training individual models; update the instruction for DCR experiements; fix minor bugs in TabSyn's training script.\n- [2024-05-14]: Add demo code for missing value imputation for the target column with a well trained TabSyn.\n\n## Introduction\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/tabsyn_model.jpg\" alt=\"Model Logo\" width=\"800\" style=\"margin-left:'auto' margin-right:'auto' display:'block'\"/\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e\nTabSyn is a deep generative model for the synthesis of mixed-type tabular data (i.e., continuous/numerical and discrete/categorical). Tabsyn consists of two parts: 1) A Variational AutoEncoder (VAE) that encodes mixed-type of tabular data into the continuous latent space. 2) A score-based diffusion model for learning the densities of the latent embeddings.\n\n###### TabSyn achieves SOTA performance in recovering the ground-truth distribution of tabular data (under five distinct metrics), and has a significantly faster sampling speed than previous diffusion-based methods.\n\u003cdiv style=\"display:flex; justify-content:center;\"\u003e\n    \u003cimg src=\"images/radar.jpg\" style=\"width:350px; margin-right:50px;\"\u003e\n    \u003cimg src=\"images/nfe1.jpg\" style=\"width:300px;\"\u003e\n\u003c/div\u003e\n\n###### Visualizations of density estimation for signle column and pair-wise correlation.\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/density.jpg\" alt=\"OLMo Logo\" width=\"800\" style=\"margin-left:'auto' margin-right:'auto' display:'block'\"/\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/heat_map.jpg\" alt=\"OLMo Logo\" width=\"800\" style=\"margin-left:'auto' margin-right:'auto' display:'block'\"/\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e\n\n\u003c!-- \u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/radar.jpg\" alt=\"OLMo Logo\" width=\"800\" style=\"margin-left:'auto' margin-right:'auto' display:'block'\"/\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e --\u003e\n\n\n\n\n## Installing Dependencies\n\nPython version: 3.10\n\nCreate environment\n\n```\nconda create -n tabsyn python=3.10\nconda activate tabsyn\n```\n\nInstall pytorch\n```\npip install torch torchvision torchaudio\n```\n\nor via conda\n```\nconda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.7 -c pytorch -c nvidia\n```\n\nInstall other dependencies\n\n```\npip install -r requirements.txt\n```\n\nInstall dependencies for GOGGLE\n\n```\npip install  dgl -f https://data.dgl.ai/wheels/cu117/repo.html\n\npip install torch_geometric\npip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.0.1+cu117.html\n```\n\nCreate another environment for the quality metric (package \"synthcity\")\n\n```\nconda create -n synthcity python=3.10\nconda activate synthcity\n\npip install synthcity\npip install category_encoders\n```\n\n## Preparing Datasets\n\n### Using the datasets adopted in the paper\n\nDownload raw dataset:\n\n```\npython download_dataset.py\n```\n\nProcess dataset:\n\n```\npython process_dataset.py\n```\n\n### Using your own dataset\n\nFirst, create a directory for you dataset [NAME_OF_DATASET] in ./data:\n```\ncd data\nmkdir [NAME_OF_DATASET]\n```\n\nPut the tabular data in .csv format in this directory ([NAME_OF_DATASET].csv). **The first row should be the header** indicating the name of each column, and the remaining rows are records.\n\nThen, write a .json file ([NAME_OF_DATASET].json) recording the metadata of the tabular, covering the following information:\n```\n{\n    \"name\": \"[NAME_OF_DATASET]\",\n    \"task_type\": \"[NAME_OF_TASK]\", # binclass or regression\n    \"header\": \"infer\",\n    \"column_names\": null,\n    \"num_col_idx\": [LIST],  # list of indices of numerical columns\n    \"cat_col_idx\": [LIST],  # list of indices of categorical columns\n    \"target_col_idx\": [list], # list of indices of the target columns (for MLE)\n    \"file_type\": \"csv\",\n    \"data_path\": \"data/[NAME_OF_DATASET]/[NAME_OF_DATASET].csv\"\n    \"test_path\": null,\n}\n```\nPut this .json file in the .Info directory.\n\nFinally, run the following command to process the UDF dataset:\n```\n\n```\n\n## Training Models\n\nFor baseline methods, use the following command for training:\n\n```\npython main.py --dataname [NAME_OF_DATASET] --method [NAME_OF_BASELINE_METHODS] --mode train\n```\n\nOptions of [NAME_OF_DATASET]: adult, default, shoppers, magic, beijing, news\nOptions of [NAME_OF_BASELINE_METHODS]: smote, goggle, great, stasy, codi, tabddpm\n\nFor Tabsyn, use the following command for training:\n\n```\n# train VAE first\npython main.py --dataname [NAME_OF_DATASET] --method vae --mode train\n\n# after the VAE is trained, train the diffusion model\npython main.py --dataname [NAME_OF_DATASET] --method tabsyn --mode train\n```\n\n## Tabular Data Synthesis\n\nFor baseline methods, use the following command for synthesis:\n\n```\npython main.py --dataname [NAME_OF_DATASET] --method [NAME_OF_BASELINE_METHODS] --mode sample --save_path [PATH_TO_SAVE]\n```\n\nFor Tabsyn, use the following command for synthesis:\n\n```\npython main.py --dataname [NAME_OF_DATASET] --method tabsyn --mode sample --save_path [PATH_TO_SAVE]\n\n```\n\nThe default save path is \"synthetic/[NAME_OF_DATASET]/[METHOD_NAME].csv\"\n\n## Evaluation\nWe evaluate the quality of synthetic data using metrics from various aspects.\n\n#### Density estimation of single column and pair-wise correlation ([link](https://docs.sdv.dev/sdmetrics/reports/quality-report/whats-included))\n\n```\npython eval/eval_density.py --dataname [NAME_OF_DATASET] --model [METHOD_NAME] --path [PATH_TO_SYNTHETIC_DATA]\n```\n\n\n#### Alpha Precision and Beta Recall ([paper link](https://arxiv.org/abs/2102.08921))\n- $\\alpha$-preicison: the fidelity of synthetic data\n- $\\beta$-recall: the diversity of synthetic data\n\n```\npython eval/eval_quality.py --dataname [NAME_OF_DATASET] --model [METHOD_NAME] --path [PATH_TO_SYNTHETIC_DATA]\n```\n\n#### Machine Learning Efficiency\n\n```\npython eval/eval_mle.py --dataname [NAME_OF_DATASET] --model [METHOD_NAME] --path [PATH_TO_SYNTHETIC_DATA]\n```\n\n#### Pricavy protection: Distance to Closest Record (DCR)\n\n```\npython eval/eval_dcr.py --dataname [NAME_OF_DATASET] --model [METHOD_NAME] --path [PATH_TO_SYNTHETIC_DATA]\n```\n\nNote: the optimal DCR score depends on the ratio between #Train and #Holdout (# Test). Ideally, DCR sore should be #Train / (#Train + #Holdout). To let the optimal score be $50\\%$, you have to let the training and testing set have the same size. \n\n#### Detection: Classifier Two Sample Tests (C2ST)\n\n```\npython eval/eval_detection.py --dataname [NAME_OF_DATASET] --model [METHOD_NAME] --path [PATH_TO_SYNTHETIC_DATA]\n```\n\n#### Missing Value Imputation for the Target Column\n\n```\npython impute.py --dataname [NAME_OF_DATASET]\n```\nThe imputed tale will be saved at impute/[NAME_OF_DATASET]\n\nTo evaluate the imputed target column regarding the classification task, use the following command:\n\n ```\npython eval_impute.py --dataname adult\n```\n\nCurrently, TabSyn only supports imputing multiple numerical columns and/or a single categorical column. The demo code only imputes the target column given a dataset, as indicated by the 'target_col_idx' in the dataset metadata JSON file. Below is a basic introduction to our imputation strategy:\n\n- For numerical columns, missing values are replaced with the average values of the corresponding columns in the training set.\n\n- For the categorical column, in each imputation trial, we randomly select from all possible categories with uniform probabilities.\n\n- Next, the masked data is fed into the VAE model to obtain their embeddings.\n\n- When applying the diffusion inpainting method, we remask the corresponding dimensions of the embeddings according to the relative positions of the embeddings and the raw input. For example, if the masked column index for the raw data is 0, and the token dimension is 4, we mask dimensions [0, 1, 2, 3] in their embeddings. Then, we apply the inpainting method illustrated in Eq. 39 to perform diffusion inpainting, and finally, we obtain the imputation result for one trial.\n\n- Since diffusion inpainting is stochastic (and for the categorical column, we sample the category randomly), we need to repeat the imputation algorithm several times (e.g., 50), and take the averaged imputation result as the final result.\n\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n\n\n## Reference\nWe appreciate your citations if you find this repository useful to your research!\n```\n@inproceedings{tabsyn,\n  title={Mixed-Type Tabular Data Synthesis with Score-based Diffusion in Latent Space},\n  author={Zhang, Hengrui and Zhang, Jiani and Srinivasan, Balasubramaniam and Shen, Zhengyuan and Qin, Xiao and Faloutsos, Christos and Rangwala, Huzefa and Karypis, George},\n  booktitle={The twelfth International Conference on Learning Representations},\n  year={2024}\n}\n```\n```\n@article{zhang2023mixed,\n  title={Mixed-Type Tabular Data Synthesis with Score-based Diffusion in Latent Space},\n  author={Zhang, Hengrui and Zhang, Jiani and Srinivasan, Balasubramaniam and Shen, Zhengyuan and Qin, Xiao and Faloutsos, Christos and Rangwala, Huzefa and Karypis, George},\n  journal={arXiv preprint arXiv:2310.09656},\n  year={2023}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Ftabsyn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famazon-science%2Ftabsyn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Ftabsyn/lists"}