{"id":18949902,"url":"https://github.com/salesforce/cost","last_synced_at":"2025-04-09T23:20:02.140Z","repository":{"id":41081648,"uuid":"459573881","full_name":"salesforce/CoST","owner":"salesforce","description":"PyTorch code for CoST: Contrastive Learning of Disentangled Seasonal-Trend Representations for Time Series Forecasting (ICLR 2022)","archived":false,"fork":false,"pushed_at":"2023-03-22T05:59:55.000Z","size":377,"stargazers_count":223,"open_issues_count":6,"forks_count":43,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-09T23:04:42.719Z","etag":null,"topics":["contrastive-learning","deep-learning","forecasting-model","machine-learning","self-supervised-learning","time-series","time-series-decomposition","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":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/salesforce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null}},"created_at":"2022-02-15T12:42:42.000Z","updated_at":"2025-03-27T15:40:47.000Z","dependencies_parsed_at":"2023-09-24T16:59:52.030Z","dependency_job_id":null,"html_url":"https://github.com/salesforce/CoST","commit_stats":{"total_commits":12,"total_committers":3,"mean_commits":4.0,"dds":0.25,"last_synced_commit":"afc26aa0239470f522135f470861a1c375507e84"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2FCoST","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2FCoST/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2FCoST/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2FCoST/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/salesforce","download_url":"https://codeload.github.com/salesforce/CoST/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248126049,"owners_count":21051860,"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":["contrastive-learning","deep-learning","forecasting-model","machine-learning","self-supervised-learning","time-series","time-series-decomposition","time-series-forecasting"],"created_at":"2024-11-08T13:19:30.560Z","updated_at":"2025-04-09T23:20:02.116Z","avatar_url":"https://github.com/salesforce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CoST: Contrastive Learning of Disentangled Seasonal-Trend Representations for Time Series Forecasting (ICLR 2022)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\".\\pics\\CoST.png\" width = \"700\" alt=\"\" align=center /\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003cb\u003eFigure 1.\u003c/b\u003e Overall CoST Architecture.\n\u003c/p\u003e\n\nOfficial PyTorch code repository for the [CoST paper](https://openreview.net/forum?id=PilZY3omXV2).\n\n* CoST is a contrastive learning method for learning disentangled seasonal-trend representations for time series forecasting.\n* CoST consistently outperforms state-of-the-art methods by a considerable margin, achieveing a 21.3% improvement in MSE on multivariate benchmarks.\n  \n## Requirements\n1. Install Python 3.8, and the required dependencies.\n2. Required dependencies can be installed by: ```pip install -r requirements.txt```\n\n## Data\n\nThe datasets can be obtained and put into `datasets/` folder in the following way:\n\n* [3 ETT datasets](https://github.com/zhouhaoyi/ETDataset) should be placed at `datasets/ETTh1.csv`, `datasets/ETTh2.csv` and `datasets/ETTm1.csv`.\n* [Electricity dataset](https://archive.ics.uci.edu/ml/datasets/ElectricityLoadDiagrams20112014) placed at `datasets/LD2011_2014.txt` and run `electricity.py`.\n* [Weather dataset](https://drive.google.com/drive/folders/1ohGYWWohJlOlb2gsGTeEq3Wii2egnEPR) (link from [Informer repository](https://github.com/zhouhaoyi/Informer2020)) placed at `datasets/WTH.csv`\n* [M5 dataset](https://drive.google.com/drive/folders/1D6EWdVSaOtrP1LEFh1REjI3vej6iUS_4) place `calendar.csv`, `sales_train_validation.csv`, `sales_train_evaluation.csv`, `sales_test_validation.csv` and `sales_test_evaluation.csv` at `datasets/` and run m5.py.\n\n## Usage\nTo train and evaluate CoST on a dataset, run the script from the scripts folder: ```./scripts/ETT_CoST.sh``` (edit file permissions via ```chmod u+x scripts/*```).\n\nAfter training and evaluation, the trained encoder, output and evaluation metrics can be found in `training/\u003cDatasetName\u003e/\u003cRunName\u003e_\u003cDate\u003e_\u003cTime\u003e/`.\n\nAlternatively, you can directly run the python scripts:\n```train \u0026 evaluate\npython train.py \u003cdataset_name\u003e \u003crun_name\u003e --archive \u003carchive\u003e --batch-size \u003cbatch_size\u003e --repr-dims \u003crepr_dims\u003e --gpu \u003cgpu\u003e --eval\n```\nThe detailed descriptions about the arguments are as following:\n| Parameter name | Description of parameter |\n| --- | --- |\n| dataset_name | The dataset name |\n| run_name | The folder name used to save model, output and evaluation metrics. This can be set to any word |\n| archive | The archive name that the dataset belongs to. This can be set to `forecast_csv` or `forecast_csv_univar` |\n| batch_size | The batch size (defaults to 8) |\n| repr_dims | The representation dimensions (defaults to 320) |\n| gpu | The gpu no. used for training and inference (defaults to 0) |\n| eval | Whether to perform evaluation after training |\n| kernels | Kernel sizes for mixture of AR experts module |\n| alpha | Weight for loss function |\n\n(For descriptions of more arguments, run `python train.py -h`.)\n\n## Main Results\nWe perform experiments on five real-world public benchmark datasets, comparing against both state-of-the-art representation learning and end-to-end forecasting approaches. \nCoST achieves state-of-the-art performance, beating the best performing end-to-end forecasting approach by 39.3% and 18.22% (MSE) in the multivariate and univariate settings\nrespectively. CoST also beats next best performing feature-based approach by 21.3% and 4.71% (MSE) in the multivariate and univariate settings respectively (refer to main paper for full results).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\".\\pics\\results.png\" width = \"700\" alt=\"\" align=center /\u003e\n\u003c/p\u003e\n\n## FAQs\n**Q**: ValueError: Found array with dim 4. StandardScaler expected \u003c= 2.\n\n**A**: Please install the appropriate package requirements as found in ```requirements.txt```, in particular, ```scikit_learn==0.24.1```.\n\n**Q**: How to set the ``--kernels`` parameter?\n\n**A**: It should be list of space separated integers, e.g. ```--kernels 1 2 4```. See the `scripts` folder for further examples.\n\n## Acknowledgements\nThe implementation of CoST relies on resources from the following codebases and repositories, we thank the original authors for open-sourcing their work.\n* https://github.com/yuezhihan/ts2vec\n* https://github.com/zhouhaoyi/Informer2020\n\n## Citation\nPlease consider citing if you find this code useful to your research.\n\u003cpre\u003e@inproceedings{\n    woo2022cost,\n    title={Co{ST}: Contrastive Learning of Disentangled Seasonal-Trend Representations for Time Series Forecasting},\n    author={Gerald Woo and Chenghao Liu and Doyen Sahoo and Akshat Kumar and Steven Hoi},\n    booktitle={International Conference on Learning Representations},\n    year={2022},\n    url={https://openreview.net/forum?id=PilZY3omXV2}\n}\u003c/pre\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforce%2Fcost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsalesforce%2Fcost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforce%2Fcost/lists"}