{"id":19932141,"url":"https://github.com/amazon-science/unconditional-time-series-diffusion","last_synced_at":"2025-07-08T22:05:16.075Z","repository":{"id":206459182,"uuid":"716622158","full_name":"amazon-science/unconditional-time-series-diffusion","owner":"amazon-science","description":"Official PyTorch implementation of TSDiff models presented in the NeurIPS 2023 paper \"Predict, Refine, Synthesize: Self-Guiding Diffusion Models for Probabilistic Time Series Forecasting\"","archived":false,"fork":false,"pushed_at":"2024-01-30T18:58:36.000Z","size":764,"stargazers_count":189,"open_issues_count":7,"forks_count":32,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-03T11:35:39.953Z","etag":null,"topics":["diffusion-models","neurips","neurips-2023","pytorch","time-series","time-series-forecasting"],"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,"zenodo":null}},"created_at":"2023-11-09T14:20:48.000Z","updated_at":"2025-04-28T05:26:56.000Z","dependencies_parsed_at":"2023-11-10T09:45:10.815Z","dependency_job_id":"c85d61e5-ca6f-4cc0-98e1-c6fe14aca7da","html_url":"https://github.com/amazon-science/unconditional-time-series-diffusion","commit_stats":null,"previous_names":["amazon-science/unconditional-time-series-diffusion"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/amazon-science/unconditional-time-series-diffusion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Funconditional-time-series-diffusion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Funconditional-time-series-diffusion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Funconditional-time-series-diffusion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Funconditional-time-series-diffusion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amazon-science","download_url":"https://codeload.github.com/amazon-science/unconditional-time-series-diffusion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Funconditional-time-series-diffusion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264357296,"owners_count":23595576,"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":["diffusion-models","neurips","neurips-2023","pytorch","time-series","time-series-forecasting"],"created_at":"2024-11-12T23:09:12.702Z","updated_at":"2025-07-08T22:05:16.052Z","avatar_url":"https://github.com/amazon-science.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TSDiff: An Unconditional Diffusion Model for Time Series\n\n[![preprint](https://img.shields.io/static/v1?label=arXiv\u0026message=2307.11494\u0026color=B31B1B)](https://arxiv.org/abs/2307.11494)\n[![License: MIT](https://img.shields.io/badge/License-Apache--2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Venue:ICML 2023](https://img.shields.io/badge/Venue-NeurIPS%202023-007CFF)](https://neurips.cc/)\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/overview.png\" width=\"100%\"\u003e\n  \u003cbr /\u003e\n  \u003cspan\u003eFig. 1: An overview of TSDiff’s use cases. \u003cb\u003ePredict:\u003c/b\u003e By utilizing observation self-guidance, TSDiff can be\nconditioned during inference to perform predictive tasks such as forecasting. \u003cb\u003eRefine:\u003c/b\u003e Predictions\nof base forecasters can be improved by leveraging the implicit probability density of TSDiff.\n\u003cb\u003eSynthesize:\u003c/b\u003e Realistic samples generated by TSDiff can be used to train downstream forecasters achieving good\nperformance on real test data.\u003c/span\u003e\n\u003c/p\u003e\n\n---\n\nThis repository contains the official implementation of the NeurIPS 2023 paper [*Predict, Refine, Synthesize: Self-Guiding Diffusion Models for Probabilistic Time Series Forecasting*](https://arxiv.org/abs/2307.11494). In this paper, we propose *TSDiff*, an unconditional diffusion model for time series. Our proposed self-guidance mechanism enables conditioning TSDiff for downstream tasks during inference, without requiring auxiliary networks or altering the training procedure. Furthermore, our refinement scheme leverages the implicit density learned by the diffusion model to iteratively refine the predictions of base forecasters. Finally, we demonstrate the high quality of the synthetic time series by training downstrain models solely on generated data and introducing the *Linear Predictive Score (LPS)*.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/forecasts.png\" width=\"60%\"\u003e\n  \u003cbr /\u003e\n  \u003cspan\u003eFig. 2: Example forecasts generated by TSDiff-Q for\ntime series in Electricity, KDDCup, and Exchange — three datasets with different frequencies and/or prediction lengths.\u003c/span\u003e\n\u003c/p\u003e\n\n## Installation\n\nTSDiff requires Python 3.8 or higher.\n\n* Create a conda environment (optional, but recommended).\n```sh\nconda create --name tsdiff --yes python=3.8 \u0026\u0026 conda activate tsdiff\n```\n* Install this package.\n```sh\npip install --editable \".\"\n```\n\n\u003e [!TIP]  \n\u003e We have some updates in the `update` branch. If you're interested in testing out TSDiff or [training it on a custom dataset](https://github.com/amazon-science/unconditional-time-series-diffusion/issues/7), using the `update` branch maybe faster for training.\n\n## Usage\n\n### Training Models\n\nTrain models using the `train_model.py` and `train_cond_model.py` scripts for `TSDiff` and `TSDiff-Cond`, respectively. Sample configurations can be found in `configs/train_tsdiff.yaml` and `configs/train_tsdiff-cond.yaml`. Specific configurations used in the paper can be found in `configs/train_tsdiff` and `configs/train_tsdiff-cond`.\n\nExample commands for regular (i.e., no missing values) forecasting:\n```sh\n# Train TSDiff on the Uber dataset for regular forecasting\npython bin/train_model.py -c configs/train_tsdiff/train_uber_tlc.yaml\n\n# Train TSDiff on the M4 dataset for regular forecasting\npython bin/train_model.py -c configs/train_tsdiff/train_m4.yaml\n\n# Train TSDiff-Cond on the Uber dataset for regular forecasting\npython bin/train_cond_model.py -c configs/train_tsdiff-cond/uber_tlc_hourly.yaml\n\n# Train TSDiff-Cond on the M4 dataset for regular forecasting\npython bin/train_cond_model.py -c configs/train_tsdiff-cond/m4_hourly.yaml\n```\n\nExample commands for forecasting with missing values:\n```sh\n# Train TSDiff on the Uber dataset for the missing values experiment\npython bin/train_model.py -c configs/train_tsdiff/train_missing_uber_tlc.yaml\n\n# Train TSDiff on the KDDCup dataset for the missing values experiment\npython bin/train_model.py -c configs/train_tsdiff/train_missing_kdd_cup.yaml\n\n# Train TSDiff-Cond on the Uber dataset for the RM missing values experiment\npython bin/train_cond_model.py -c configs/train_tsdiff-cond/missing_RM_uber_tlc_hourly.yaml\n\n# Train TSDiff-Cond on the KDDCup dataset for the BM-B missing values experiment\npython bin/train_cond_model.py -c configs/train_tsdiff-cond/missing_BM-B_kdd_cup_2018_without_missing.yaml\n\n# Train TSDiff-Cond on the KDDCup dataset for the BM-E missing values experiment\npython bin/train_cond_model.py -c configs/train_tsdiff-cond/missing_BM-E_kdd_cup_2018_without_missing.yaml\n```\nNote that for TSDiff we train only one model and all the missing value scenarios are evaluated using the same unconditional model. However, for TSDiff-Cond, one model is trained per missingness scenario.\n\n### Evaluating Models\nThe unconditional models trained above can be used for the following tasks.\n\n#### Predict using Observation Self-Guidance\nUse the `guidance_experiment.py` script and `configs/guidance.yaml` config to run the forecasting experiments. Specific configurations used in the paper can be found in `configs/guidance/`.\n\nExample commands:\n```sh\n# Run observation self-guidance on the Solar dataset\npython bin/guidance_experiment.py -c configs/guidance/guidance_solar.yaml --ckpt /path/to/ckpt\n\n# Run observation self-guidance on the KDDCup dataset\npython bin/guidance_experiment.py -c configs/guidance/guidance_kdd_cup.yaml --ckpt /path/to/ckpt\n```\n\n#### Refine Predictions of Base Forecasters\nUse `refinement_experiment.py` script and `configs/refinement.yaml` config to run the refinement experiments. Specific configurations used in the paper can be found in `configs/refinement/`.\n\nExample commands:\n```sh\n# Refine predictions from the Linear model on the Solar dataset\npython bin/refinement_experiment.py -c configs/refinement/solar_nips-linear.yaml --ckpt /path/to/ckpt\n\n# Refine predictions from the DeepAR model on the M4 dataset\npython bin/refinement_experiment.py -c configs/refinement/m4_hourly-deepar.yaml --ckpt /path/to/ckpt\n```\n#### Train Downstream Models using Synthetic Data\nUse `tstr_experiment.py` script and `configs/tstr.yaml` config to run the _train on synthetic-test on real_ experiments. Specific configurations used in the paper can be found in `configs/tstr/`.\n\nExample commands:\n```sh\n# TSTR on the Solar Dataset\npython bin/tstr_experiment.py -c configs/tstr/solar_nips.yaml --ckpt /path/to/ckpt\n\n# TSTR on the KDDCup Dataset\npython bin/tstr_experiment.py -c configs/tstr/kdd_cup_2018_without_missing.yaml --ckpt /path/to/ckpt\n```\n\n## BibTeX\n\nIf you find this repository or the ideas presented in our paper useful, please consider citing.\n\n```\n@inproceedings{kollovieh2023predict,\n author    = {Kollovieh, Marcel and Ansari, Abdul Fatir and Bohlke-Schneider, Michael and Zschiegner, Jasper and Wang, Hao and Wang, Yuyang},\n title     = {Predict, Refine, Synthesize: Self-Guiding Diffusion Models for Probabilistic Time Series Forecasting},\n booktitle = {Advances in Neural Information Processing Systems},\n year      = {2023}\n}\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Funconditional-time-series-diffusion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famazon-science%2Funconditional-time-series-diffusion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Funconditional-time-series-diffusion/lists"}