{"id":29248826,"url":"https://github.com/hkuds/opencity","last_synced_at":"2025-07-04T00:09:14.589Z","repository":{"id":253650081,"uuid":"841246286","full_name":"HKUDS/OpenCity","owner":"HKUDS","description":"\"OpenCity: Open Spatio-Temporal Foundation Models for Traffic Prediction\"","archived":false,"fork":false,"pushed_at":"2024-08-23T11:15:13.000Z","size":4914,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-23T12:26:47.361Z","etag":null,"topics":["fundation-models","large-models","smart-cities","spatio-temporal-prediction","urban-computing"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2408.10269","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUDS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-08-12T02:41:52.000Z","updated_at":"2024-08-23T12:26:50.720Z","dependencies_parsed_at":"2024-08-23T12:26:47.581Z","dependency_job_id":null,"html_url":"https://github.com/HKUDS/OpenCity","commit_stats":null,"previous_names":["hkuds/opencity"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HKUDS/OpenCity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FOpenCity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FOpenCity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FOpenCity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FOpenCity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUDS","download_url":"https://codeload.github.com/HKUDS/OpenCity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FOpenCity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263421915,"owners_count":23464052,"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":["fundation-models","large-models","smart-cities","spatio-temporal-prediction","urban-computing"],"created_at":"2025-07-04T00:09:12.496Z","updated_at":"2025-07-04T00:09:14.510Z","avatar_url":"https://github.com/HKUDS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCity: Open Spatio-Temporal Foundation Models for Traffic Prediction\n\n\u003cimg src='opencity.png' /\u003e\n\nA pytorch implementation for the paper: [OpenCity: Open Spatio-Temporal Foundation Models for Traffic Prediction](https://arxiv.org/abs/2408.10269)\u003cbr /\u003e  \n\n[Zhonghang Li](https://scholar.google.com/citations?user=__9uvQkAAAAJ), [Long Xia](https://scholar.google.com/citations?user=NRwerBAAAAAJ), [Lei Shi](https://harryshil.github.io/), [Yong Xu](https://scholar.google.com/citations?user=1hx5iwEAAAAJ), [Dawei Yin](https://www.yindawei.com/), [Chao Huang](https://sites.google.com/view/chaoh)* (*Correspondence)\u003cbr /\u003e  \n\n**[Data Intelligence Lab](https://sites.google.com/view/chaoh/home)@[University of Hong Kong](https://www.hku.hk/)**, [South China University of Technology](https://www.scut.edu.cn/en/), Baidu Inc  \n\u003c!--\n-----\n\n\u003ca href='https://OpenCity-ST.github.io/'\u003e\u003cimg src='https://img.shields.io/badge/Project-Page-Green'\u003e\u003c/a\u003e\n\u003ca href='https://github.com/HKUDS/OpenCity'\u003e\u003cimg src='https://img.shields.io/badge/Demo-Page-purple'\u003e\u003c/a\u003e \n\u003c#\u003e\u003cimg src='https://img.shields.io/badge/Paper-PDF-orange'\u003e\u003c/a\u003e \n[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://www.youtube.com/watch?v=4BIbQt-EIAM)\n • 🌐 \u003ca href=\"https://zhuanlan.zhihu.com/p/684785925\" target=\"_blank\"\u003e中文博客\u003c/a\u003e\n--\u003e\nThis repository hosts the code, data, and model weights of **OpenCity**.\n\n-----\n## 🎉 News \n- [x] [2024.08.21] Release the full paper.\n- [x] [2024.08.20] Add video.\n- [x] [2024.08.15] 🚀🚀 Release the code, model weights and datasets of OpenCity.\n- [x] [2024.08.15] Release baselines codes.\n\n\n🎯🎯📢📢 We upload the **models** and **data** used in our OpenCity on 🤗 **Huggingface**. We highly recommend referring to the table below for further details: \n\n| 🤗 Huggingface Address                                        | 🎯 Description                                                |\n| ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [https://huggingface.co/hkuds/OpenCity-Plus](https://huggingface.co/hkuds/OpenCity-Plus/tree/main) | It's the model weights of our OpenCity-Plus. |\n| [https://huggingface.co/datasets/hkuds/OpenCity-dataset/tree/main](https://huggingface.co/datasets/hkuds/OpenCity-dataset/tree/main) | We released the datasets used in OpenCity. |\n\n## 👉 TODO \n...\n\n\n-----------\n\n## Introduction\n\n\u003cp style=\"text-align: justify\"\u003e\nIn this work, we aim to unlock new possibilities for building versatile, resilient and adaptive spatio-temporal foundation models for traffic prediction. \nTo achieve this goal, we introduce a novel foundation model, named OpenCity, that can effectively capture and normalize the underlying spatio-temporal patterns from diverse data characteristics, facilitating zero-shot generalization across diverse urban environments. \nOpenCity integrates the Transformer architecture with graph neural networks to model the complex spatio-temporal dependencies in traffic data. \nBy pre-training OpenCity on large-scale, heterogeneous traffic datasets, we enable the model to learn rich, generalizable representations that can be seamlessly applied to a wide range of traffic forecasting scenarios. \nExperimental results demonstrate that OpenCity exhibits exceptional zero-shot predictive performance in various traffic prediction tasks.\n\u003c/p\u003e\n\n![The detailed framework of the proposed OpenCity.](https://github.com/OpenCity-ST/OpenCity-ST.github.io/blob/main/images/framework.png)\n\n## Main Results\n**Outstanding Zero-shot Prediction Performance.** OpenCity achieves significant zero-shot learning breakthroughs, outperforming most baselines even without fine-tuning. This highlights the approach's robustness and effectiveness at learning complex spatio-temporal patterns in large-scale traffic data, extracting universal insights applicable across downstream tasks.\n \n![Zero-shot vs. Full-shot.](https://github.com/OpenCity-ST/OpenCity-ST.github.io/blob/main/images/zero-shot.png)\n\n\n\n### Demo Video\nhttps://github.com/user-attachments/assets/39265dc5-0126-483b-951e-518c6cb210e0\n\n-----------\n\u003cspan id='Usage'/\u003e\n\n## Getting Started\n\n\u003cspan id='all_catelogue'/\u003e\n\n### Table of Contents:\n* \u003ca href='#Code Structure'\u003e1. Code Structure\u003c/a\u003e\n* \u003ca href='#Environment'\u003e2. Environment \u003c/a\u003e\n* \u003ca href='#Training OpenCity'\u003e3. Training OpenCity \u003c/a\u003e\n  * \u003ca href='#Preparing Pre-trained Data'\u003e3.1. Preparing Pre-trained Data \u003c/a\u003e\n  * \u003ca href='#Pre-training'\u003e3.2. Pre-training \u003c/a\u003e\n* \u003ca href='#Evaluating'\u003e4. Evaluating \u003c/a\u003e\n****\n\n\n\u003cspan id='Code Structure'/\u003e\n\n### 1. Code Structure \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\n\n```\n├── conf/\n│   ├── AGCRN/\n│   │   └── AGCRN.conf\n│   ├── ASTGCN/\n│   │   └── ASTGCN.conf\n│   ├── general_conf/\n│   │   ├── global_baselines.conf\n│   │   └── pretrain.conf\n│   ├── GWN/\n│   │   └── GWN.conf\n│   ├── MSDR/\n│   │   └── MSDR.conf\n│   ├── MTGNN/\n│   │   └── MTGNN.conf\n│   ├── OpenCity/\n│   │   └── OpenCity.conf\n│   ├── PDFormer/\n│   │   └── PDFormer.conf\n│   ├── STGCN/\n│   │   └── STGCN.conf\n│   ├── STSGCN/\n│   │   └── STSGCN.conf\n│   ├── STWA/\n│   │   └── STWA.conf\n│   └── TGCN/\n│       └── TGCN.conf\n├── data/\n│   ├── generate_ca_data.py\n│   └── README.md\n├── lib/\n│   ├── data_process.py\n│   ├── logger.py\n│   ├── metrics.py\n│   ├── Params_predictor.py\n│   ├── Params_pretrain.py\n│   ├── predifineGraph.py\n│   └── TrainInits.py\n├── model/\n│   ├── AGCRN/\n│   │   ├── AGCN.py\n│   │   ├── AGCRN.py\n│   │   ├── AGCRNCell.py\n│   │   └── args.py\n│   ├── ASTGCN/\n│   │   ├── args.py\n│   │   └── ASTGCN.py\n│   ├── GWN/\n│   │   ├── args.py\n│   │   └── GWN.py\n│   ├── MSDR/\n│   │   ├── args.py\n│   │   ├── gmsdr_cell.py\n│   │   └── gmsdr_model.py\n│   ├── MTGNN/\n│   │   ├── args.py\n│   │   └── MTGNN.py\n│   ├── OpenCity/\n│   │   ├── args.py\n│   │   └── OpenCity.py\n│   ├── PDFormer/\n│   │   ├── args.py\n│   │   └── PDFormer.py\n│   ├── ST_WA/\n│   │   ├── args.py\n│   │   ├── attention.py\n│   │   └── ST_WA.py\n│   ├── STGCN/\n│   │   ├── args.py\n│   │   └── stgcn.py\n│   ├── STSGCN/\n│   │   ├── args.py\n│   │   └── STSGCN.py\n│   └── TGCN/\n│       ├── args.py\n│       └── TGCN.py\n│   ├── Model.py\n│   ├── BasicTrainer.py\n│   ├── Run.py\n└── model_weights/\n    ├── OpenCity/\n    └── README.md\n```\n\n\n\u003cspan id='Environment'/\u003e\n\n### 2.Environment \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\nPlease first clone the repo and install the required environment, which can be done by running the following commands:\n```shell\nconda create -n opencity python=3.9.13\n\nconda activate opencity\n\n# Torch (other versions are also ok)\npip install torch==1.9.0+cu111 torchvision==0.10.0+cu111 torchaudio==0.9.0 -f https://download.pytorch.org/whl/torch_stable.html\n\n# Clone our OpenCity or download it\ngit clone https://github.com/HKUDS/OpenCity.git\ncd OpenCity-main\n\n# Install required libraries\npip install -r requirements.txt\n```\n\n\u003cspan id='Training OpenCity'/\u003e\n\n### 3. Training OpenCity \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\n\n\u003cspan id='Preparing Pre-trained Data'/\u003e\n\n#### 3.1. Preparing Pre-trained Data \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\n\n* The model's generalization capabilities and predictive performance were extensively evaluated using a diverse set of large-scale, real-world public datasets covering various traffic-related data categories, including **Traffic Flow**, **Taxi Demand**, **Bicycle Trajectories**, **Traffic Speed Statistics**, and **Traffic Index Statistics**, from regions across the United States and China, such as New York City, Chicago, Los Angeles, the Bay Area, Shanghai, Shenzhen, and Chengdu. \u003cbr /\u003e\n* These data are organized in [OpenCity-dataset](https://huggingface.co/datasets/hkuds/OpenCity-dataset/tree/main). Please download it and put it at ./data. Subsequently, unzip all files and run [generate_ca_data.py](https://github.com/HKUDS/OpenCity/blob/main/data/generate_ca_data.py).\n\n\u003cspan id='Pre-training'/\u003e\n\n#### 3.2. Pre-training \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\n\n* To pretrain the OpenCity model with different configurations, you can execute the Run.py code. There are some examples:\n```\n# OpenCity-plus\npython Run.py -mode pretrain -model OpenCity -save_pretrain_path OpenCity-plus2.0.pth -batch_size 4 --embed_dim 512 --skip_dim 512 --enc_depth 6\n\n# OpenCity-base\npython Run.py -mode pretrain -model OpenCity -save_pretrain_path OpenCity-base2.0.pth -batch_size 8 --embed_dim 256 --skip_dim 256 --enc_depth 3\n\n# OpenCity-mini\npython Run.py -mode pretrain -model OpenCity -save_pretrain_path OpenCity-mini2.0.pth -batch_size 16 --embed_dim 128 --skip_dim 128 --enc_depth 3\n\n```\n\n* Parameter setting instructions. The parameter settings consist of two parts: the pretrain config and other configs. To avoid any confusion arising from potential overlapping parameter names, we employ a hyphen (-) to specify the parameters of pretrain config and use a double hyphen (--) to specify the parameters of other configs. Please note that if two parameters have the same name, **the settings of the latter can override those of the former.**\n\n\u003cspan id='Evaluating'/\u003e\n\n### 4. Evaluating \u003ca href='#all_catelogue'\u003e[Back to Top]\u003c/a\u003e\n\n* **Preparing Checkpoints of OpenCity**. You can download our model using the following link: [OpenCity-Plus](https://huggingface.co/hkuds/OpenCity-Plus/tree/main), [OpenCity-Base](https://huggingface.co/hkuds/OpenCity-Base/tree/main), [OpenCity-Mini](https://huggingface.co/hkuds/OpenCity-Mini/tree/main)\n\n* **Running Evaluation of OpenCity**. You can use our release model weights to evaluate, There is an example as below: \n```\n# Use OpenCity-plus to evaluate, please use only one dataset to test (e.g. dataset_use = ['PEMS07M'] in pretrain.config).\npython Run.py -mode test -model OpenCity -load_pretrain_path OpenCity-plus.pth -batch_size 2 --embed_dim 512 --skip_dim 512 --enc_depth 6\n```\n\n* **Running Evaluation of other baselines**. You can Replace the model name or use ori mode to train and test. For example: \n\n```\n# Run STGCN in ori mode\npython Run.py -mode ori -model STGCN -batch_size 64 --real_value False\n```\n\n\u003c!--\n## Contact\nFor any questions or feedback, feel free to contact [Zhonghang Li](mailto:bjdwh.zzh@gmail.com).\n--\u003e\n\n## Citation\n\nIf you find OpenCity useful in your research or applications, please kindly cite:\n\n```\n@misc{li2024opencity,\n      title={OpenCity: Open Spatio-Temporal Foundation Models for Traffic Prediction}, \n      author={Zhonghang Li and Long Xia and Lei Shi and Yong Xu and Dawei Yin and Chao Huang},\n      year={2024},\n      eprint={2408.10269},\n      archivePrefix={arXiv}\n}\n```\n\n\n\u003c!--\n## Acknowledgements\nYou may refer to related work that serves as foundations for our framework and code repository, \n[Vicuna](https://github.com/lm-sys/FastChat). We also partially draw inspirations from [GraphGPT](https://github.com/HKUDS/GraphGPT). The design of our website and README.md was inspired by [NExT-GPT](https://next-gpt.github.io/), and the design of our system deployment was inspired by [gradio](https://www.gradio.app) and [Baize](https://huggingface.co/spaces/project-baize/chat-with-baize). Thanks for their wonderful works.\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fopencity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhkuds%2Fopencity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fopencity/lists"}