{"id":13869824,"url":"https://github.com/kimmo1019/Roundtrip","last_synced_at":"2025-07-15T18:32:04.652Z","repository":{"id":50363218,"uuid":"228743708","full_name":"kimmo1019/Roundtrip","owner":"kimmo1019","description":"Roundtrip: density estimation with deep generative neural networks","archived":false,"fork":false,"pushed_at":"2024-04-27T05:36:46.000Z","size":2381,"stargazers_count":62,"open_issues_count":3,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-01T04:40:53.495Z","etag":null,"topics":["deep-generative-model","deep-learning","density-estimation","gan","likelihood-free-inference"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pyroundtrip/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kimmo1019.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2019-12-18T02:45:32.000Z","updated_at":"2025-06-27T06:50:35.000Z","dependencies_parsed_at":"2024-01-16T07:23:22.975Z","dependency_job_id":"79317999-1a57-418e-91c5-4407ecfc029a","html_url":"https://github.com/kimmo1019/Roundtrip","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kimmo1019/Roundtrip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimmo1019%2FRoundtrip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimmo1019%2FRoundtrip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimmo1019%2FRoundtrip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimmo1019%2FRoundtrip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kimmo1019","download_url":"https://codeload.github.com/kimmo1019/Roundtrip/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimmo1019%2FRoundtrip/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265451451,"owners_count":23767768,"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":["deep-generative-model","deep-learning","density-estimation","gan","likelihood-free-inference"],"created_at":"2024-08-05T20:01:18.693Z","updated_at":"2025-07-15T18:32:04.227Z","avatar_url":"https://github.com/kimmo1019.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Roundtrip\n\n[![PyPI](https://img.shields.io/pypi/v/pyroundtrip)](https://pypi.org/project/pyroundtrip/)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4560982.svg)](https://doi.org/10.5281/zenodo.3747161)\n\n![model](https://github.com/kimmo1019/Roundtrip/blob/master/model.jpg)\n\n\nRoundtrip is a deep generative neural density estimator which exploits the advantage of GANs for generating samples and estimates density by either importance sampling or Laplace approximation. This repository provides source code and instructions for using Roundtrip on both simulation data and real data.\n\n## News\n\n- Apr/2023: A detailed Ipython notebook tutorial for using new version of Roundtrip is provide [here](https://github.com/kimmo1019/Roundtrip/blob/master/src/tutorial.ipynb).\n\n- Apr/2023: Roundtrip is available from [PyPI](https://pypi.org/project/pyroundtrip/).\n\n- Mar/2023: Roundtrip supports Python3 and Tensorflow 2. See [instructions](https://github.com/kimmo1019/Roundtrip/tree/master/src).\n\n## Table of Contents\n\n- [Requirements](#Requirements)\n- [Install](#install)\n- [Reproduction](#reproduction)\n\t- [Simulation Data](#simulation-data)\n    - [Real Data](#real-data)\n        - [UCI Datasets](#uci-datasets)\n        - [Image Datasets](#image-datasets)\n    - [Outlier Detection](#outlier-detection)\n    - [Pretrain Models](#pretrain-models)\n- [Further Application](#further-application)\n- [Contact](#contact)\n- [Citation](#citation)\n- [License](#license)\n\n## Requirements\n\nNew version (recommended)\n- TensorFlow\u003e=2.8.0\n- Python\u003e=3.7\n  \nOld version\n- TensorFlow==1.13.1\n- Python==2.7.1\n\n\n## Docker \n\n### Building the image form the docker file : \n```shell\ndocker build -t roundtrip:train .\n```\n\n### Run the image with GPU :\n```shell \ndocker run --rm -i -t --gpus all -v [path you want to mount]:/app roundtrip:train /bin/bash\n```\nPS: you can also run without gpu by removing : `--gpus all `\n\n### pulling the image directly \nA ready-to-pull docker image is provided as well :\n```shell \ndocker pull codgas/ubuntu18.04_cuda10.0_cudnn7_tf1.13.1_py2.7\n```\n\n## Install\n\nRoundtrip can be downloaded by\n```shell\ngit clone https://github.com/kimmo1019/Roundtrip\n```\nSoftware has been tested on a Linux (Centos 7) and Python2.7 environment. A GPU card is recommended for accelerating the training process.\n\n## Reproduction\n\nThis section provides instructions on how to reproduce results in the original paper.\n\n### Simulation data\n\nWe tested Roundtrip on three types of simulation datasets. (1) Indepedent Gaussian mixture. (2) 8-octagon Gaussian mixture. (3) Involute.\n\nThe main python script `main_density_est.py` is used for implementing Roundtrip. Model architecture for Roundtrip can be find in `model.py`. Data loader or data sampler can be find in `util.py`.\n\nTaking the (1) for an example, one can run the following commond to train a Roundtrip model with indepedent Gaussian mixture data.\n\n```shell\nCUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 2 --dy 2 --train True --data indep_gmm --epochs 100 --cv_epoch 30 --patience 5\n[dx]  --  dimension of latent space\n[dy]  --  dimension of observation space\n[train]  --  whethre use train mode\n[data]  --  dataset name\n[epochs] -- maximum training epoches\n[cv_epoch] -- epoch where (cross) validation begins\n[patience] -- patience for early stopping\n```\nAfter training the model, you will have three part of outputs, which are marked by a unique timestamp `YYYYMMDD_HHMMSS`. This timestamp records the exact time when you run the script.\n\n 1) `log` files and estimated density can be found at folder `data/density_est_YYYYMMDD_HHMMSS_indep_gmm_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`.\n \n 2) Model weights will be saved at folder `checkpoint/density_est_YYYYMMDD_HHMMSS_indep_gmm_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`. \n \n 3) The training loss curves were recorded at folder `graph/density_est_YYYYMMDD_HHMMSS_indep_gmm_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`, which can be visualized using TensorBoard.\n\n Next, we want to visulize the estimated density on a 2D region. One can then run the following script. \n\n ```shell\n CUDA_VISIBLE_DEVICES=0 python evaluate.py --data indep_gmm --epoch epoch --path path\n [YYYYMMDD_HHMMSS] --  timestamp in the last training step\n [epoch] -- epoch for loading model weights\n [path] --path to data folder, e.g., `data/density_est_YYYYMMDD_HHMMSS_indep_gmm_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`\n ```\n\n we suggest to use the epoch recorded in the last line of the `log_test.txt` file in the output part 1). Then the estimated density (.png) on a 2D grid region will be saved in the same data folder `data/density_est_YYYYMMDD_HHMMSS_indep_gmm_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`. \n\n It also easy to implement Roundtrip with other two simulation datasets by changing the `data`.\n\n- 8-octagon Gaussian mixture\n    Model training:\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 2 --dy 2 --train True --data eight_octagon_gmm --epochs 300 --cv_epoch 200 --patience 5\n    ```\n    Density esitmation on a 2D grid region:\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python evaluate.py --data eight_octagon_gmm --epoch epoch --path path\n    ```\n- involute\n    Model training:\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 2 --dy 2 --train True --data involute --epochs 300 --cv_epoch 200 --patience 5\n    ```\n    Density esitmation on a 2D grid region:\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python evaluate.py  --data involute --epoch epoch --path path\n    ```\n\n### Real Data\n\nNext, we tested Roundtrip on different types of real data including five datasets from UCI machine learning repository and two image datasets. We provided freely public access to all related datasets (UCI datasets, image datasets, and OODS datasets), which can be download from a [zenodo repository](https://doi.org/10.5281/zenodo.3747144). All you need is to download the corresponding dataset (e.g., `AreM.tar.gz`), uncompress the data under `datasets` folder. Please also note that we provided various of pretrain models for a quick implementation of Roundtrip without training (see pretrain models section).\n\n\n#### UCI Datasets\n\nThe original UCI datasets were from [UCI machine learning repository](http://archive.ics.uci.edu/ml/datasets.php). As the real data has no groud truth for density, we evaluate Roundtrip by calculating the average log likelihood on the test data. Similar to the simulation data, we take `AreM` dataset for an example, one can directly run\n\n```shell\nCUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 3 --dy 6 --train True --data uci_AReM --epochs 300 --cv_epoch 20 --patience 10 --use_cv True\n```\nNote that all the dataset from UCI machine learning repository will be added a prefix `uci_` to the data name. The average log likelihood and stantard deviation can be found in `log_test.txt` under data folder `data/density_est_YYYYMMDD_HHMMSS_uci_AreM_x_dim=2_y_dim=2_alpha=10.0_beta=10.0`.\n\nWe also provide scripts for implementing Roundtrip with other UCI dataset.\n\n- CASP\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 5 --dy 9 --train True --data uci_CASP --epochs 300 --cv_epoch 20 --patience 10 --use_cv True\n    ```\n- HEPMASS\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 8 --dy 21 --train True --data uci_HEPMASS --epochs 300 --cv_epoch 20 --patience 10 --use_cv True\n    ```\n- BANK\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 8 --dy 17 --train True --data uci_BANK --epochs 300 --cv_epoch 20 --patience 10 --use_cv True\n    ```\n- YPMSD\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 20 --dy 90 --train True --data uci_YPMSD --epochs 300 --cv_epoch 20 --patience 10 --use_cv True\n    ```\n\n#### Image Datasets\n\nMNIST and CIFAR-10 were used in our study. Unlike previous experiments, we focus on conditional density estimation where a ont-hot encoded class label will be introduced to the networks as an additional input.\n\nDownload data from [zenodo repository](https://zenodo.org/record/3748270#.XpFvgdNKhTY) and uncompress the two datasets under `data` folder.\n\nOne can run the conditional image generation and conditional denstiy estimation simultaneously through the following script.\n\n- MNIST\n\n    Model training\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est_img.py  --dx 100 --dy 784 --train True --data mnist --epochs 100 --cv_epoch 50 --patience 5\n    ```\n    Model test\n    ```shell\n    python evaluate.py --data mnist --path path\n    [path] -- path to data folder (e.g., data/density_est_YYYYMMDD_HHMMSS_mnist_x_dim=100_y_dim=784_alpha=10.0_beta=10.0)\n    ```\n\n- CIFAR-10\n\n    Model training\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est_img.py  --dx 100 --dy 3072 --train True --data cifar10 --epochs 1000 --cv_epoch 500 --patience 5\n    ```\n    Model test\n    ```shell\n    python evaluate.py --data cifar10 --path path\n    ```\nAfter model test, the generated images can be found in the first part of outputs.\n\n### Outlier Detection\n\nWe introduced three outlier detection datasets (Shuttle, Mammography, and ForestCover) from [ODDS library](http://odds.cs.stonybrook.edu/). Download the three datasets (`ODDS.tar.gz`) from the [zenodo repository](https://doi.org/10.5281/zenodo.3747144). Uncompress it under the `datasets` folder.\n\nOne can run the following commonds to train a Roundtrip model and evaluate by precision at K.\n\n- Shuttle\n\n    Model training\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py  --dx 3 --dy 9 --train True --data odds_Shuttle --epochs 300 --cv_epoch 30 --patience 10\n    ```\n    Model evaluation\n    ```shell\n    python evaluate.py --data odds_Shuttle --epoch epoch --path path\n    [epoch] -- epoch for loading model weights (e.g., epoch recorded in the last line in log_test.txt)\n    [path] -- path to the frist part of outputs (e.g., data/density_est_YYYYMMDD_HHMMSS_odds_Shuttle_x_dim=3_y_dim=9_alpha=10.0_beta=10.0)\n    ```\n- Mammography\n\n    Model training\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py --dx 3 --dy 6 --train True --data odds_Mammography --epochs 300 --cv_epoch 30 --patience 10\n    ```\n    Model evaluation\n    ```shell\n    python evaluate.py --data odds_Mammography --epoch epoch --path path\n    ```\n- ForestCover\n\n    Model training\n    ```shell\n    CUDA_VISIBLE_DEVICES=0 python main_density_est.py --dx 4 --dy 10 --train True --data odds_ForestCover --epochs 300 --cv_epoch 30 --patience 10\n    ```\n    Model evaluation\n    ```shell\n    python evaluate.py --data odds_ForestCover --epoch epoch  --path path\n    ```\nThe precision at K of Roundtrip, One-class SVM and Isolation Forest will be calculated and printed.\n\n### Pretrain Models\n\nWe provide various of pretrain models for a quick implementation of Roundtrip. First, one needs to download the pretrain models `pre_trained_models.tar.gz` from [zenodo repository](https://doi.org/10.5281/zenodo.3747144). Then uncompress it under `Roundtrip` folder. For the above models that use `evaluate.py` for model evaluation. One can simply add `--pretrain True` to the end of each evaluation command. For an example, one can run \n\n```python\npython evaluate.py --data mnist --path path --pretrain True\n```\n\nThis can implement the Beyes posterior probability estimation, which will result in around 98.3% classification accuracy. Note that in pretrain evaluation, the `path` parameter can be any fold path like `density_est_YYYYMMDD_HHMMSS_mnist_x_dim=100_y_dim=784_alpha=10.0_beta=10.0`. `path` name is necessary as it is used for parsing parameters in `evaluate.py`. \n\n## Further Application\n\nRoundtrip can be used for a general-purpose density estimation. Besides that, Roundtrip has various downstream applications including but not limited to\n\n- Supervised learning (already covered in this paper)\n- Unsupervised learning (refer to our another [work](https://www.nature.com/articles/s42256-021-00333-y) published by *Nature Machine Intelligence*)\n- Causal inference (refer to our another [work](https://arxiv.org/abs/2212.05925) on arXiv)\n- Likelihood-free Bayesian inference\n- Sequential Markov chain Monte Carlo (MCMC)\n\n\n## Contact\n\nPlease feel free to open an issue in Github or directly contact `liuqiao@stanford.edu` if you have any problem in Roundtrip.\n\n\n## Citation\n\nIf you find Roundtrip useful for your work, please consider citing our paper:\n\n**Qiao Liu**, Jiaze Xu, Rui Jiang, Wing Hung Wong. Density estimation using deep generative neural networks[J]. Proceedings of the National Academy of Sciences. 2021, 118 (15) e2101344118; DOI: 10.1073/pnas.2101344118.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE.md file for details\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimmo1019%2FRoundtrip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkimmo1019%2FRoundtrip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimmo1019%2FRoundtrip/lists"}