{"id":13788803,"url":"https://github.com/VeritasYin/STGCN_IJCAI-18","last_synced_at":"2025-05-12T03:30:48.554Z","repository":{"id":44470614,"uuid":"129604710","full_name":"VeritasYin/STGCN_IJCAI-18","owner":"VeritasYin","description":"[IJCAI'18] Spatio-Temporal Graph Convolutional Networks","archived":false,"fork":false,"pushed_at":"2024-04-29T19:29:48.000Z","size":35771,"stargazers_count":1063,"open_issues_count":17,"forks_count":310,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-12T04:49:29.116Z","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":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VeritasYin.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":"2018-04-15T11:45:00.000Z","updated_at":"2025-04-11T15:42:05.000Z","dependencies_parsed_at":"2022-08-12T11:11:22.708Z","dependency_job_id":"7550235a-c749-4bf2-8f0e-8a3feb6e38d1","html_url":"https://github.com/VeritasYin/STGCN_IJCAI-18","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeritasYin%2FSTGCN_IJCAI-18","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeritasYin%2FSTGCN_IJCAI-18/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeritasYin%2FSTGCN_IJCAI-18/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeritasYin%2FSTGCN_IJCAI-18/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VeritasYin","download_url":"https://codeload.github.com/VeritasYin/STGCN_IJCAI-18/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253667942,"owners_count":21944943,"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-08-03T21:00:53.819Z","updated_at":"2025-05-12T03:30:43.539Z","avatar_url":"https://github.com/VeritasYin.png","language":"Python","funding_links":[],"categories":["TensorFlow Implementations"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003cins\u003eS\u003c/ins\u003epatio-\u003cins\u003eT\u003c/ins\u003eemporal \u003cins\u003eG\u003c/ins\u003eraph \u003cins\u003eC\u003c/ins\u003eonvolutional \u003cins\u003eN\u003c/ins\u003eetworks: \u003cbr\u003e A Deep Learning Framework for Traffic Forecasting\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.ijcai.org/proceedings/2018/0505.pdf\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Paper-grey?logo=read%20the%20docs\u0026logoColor=green\" alt=\"Paper\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/VeritasYin/STGCN_IJCAI-18\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Github-grey?logo=github\" alt=\"Github\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/VeritasYin/STGCN_IJCAI-18/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-BSD%202--Clause-red.svg\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pytorch-geometric-temporal.readthedocs.io/en/latest/modules/root.html#torch_geometric_temporal.nn.attention.stgcn.STConv\"\u003e\u003cimg src=\"https://img.shields.io/badge/PyG_Temporal-STConv-blue\" alt=PyG_Temporal\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://hits.seeyoufarm.com\"\u003e\u003cimg src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FVeritasYin%2FSTGCN_IJCAI-18\u0026count_bg=%2379C83D\u0026title_bg=%23555555\u0026icon=\u0026icon_color=%23E7E7E7\u0026title=Hits\u0026edge_flat=false\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Introduction \nWe propose a novel deep learning framework, **STGCN**, to tackle time series prediction problem in traffic domain. Instead of applying regular convolutional and recurrent units, we formulate the problem on graphs and build the model with complete convolutional structures. To the best of our knowledge, it is the first time that to apply purely convolutional structures to extract spatio-temporal features simultaneously from graph-structured time series in a traffic study. \n\n## Problem Formulation\nTraffic forecast is a typical time-series prediction problem, i.e. predicting the most likely traffic measurements (e.g. speed or traffic flow) in the next $H$ time steps given the previous $M$ observations from traffic network $G$ as, \n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://latex.codecogs.com/svg.image?\\large\u0026space;\\hat{v}_{t\u0026plus;1},\u0026space;...,\u0026space;\\hat{v}_{t\u0026plus;H}=\\mathop{\\arg\\max}_{v_{t\u0026plus;1},\u0026space;...,\u0026space;v_{t\u0026plus;H}}\u0026space;\\log\u0026space;P(v_{t\u0026plus;1},\u0026space;...,v_{t\u0026plus;H}|v_{t-M\u0026plus;1},\u0026space;...,v_t;G)\"/\u003e\n\u003c/p\u003e\n  \n\u003cp align=\"center\"\u003e\u003cimg width=\"30%\" height=\"30%\" src=\"figures/Graph_Structured_Traffic_Data.png\"\u003e\u003c/p\u003e \n  \n**Fig.1 Graph-structured traffic data.**  \nEach $v_t$ indicates a frame of current traffic status at time step $t$, which is recorded in a graph-structured data matrix.\n\n## Network Structure\n\u003cp align=\"center\"\u003e\u003cimg src=\"figures/STGCN.png\" width=\"50%\" height=\"50%\"\u003e\u003c/p\u003e\n  \n**Fig. 2 Architecture of spatio-temporal graph convolutional networks.**  \nThe framework STGCN consists of two spatio-temporal convolutional blocks (ST-Conv blocks) and a fully-connected output layer in the end. Each ST-Conv block contains two temporal gated convolution layers and one spatial graph convolution layer in the middle. The residual connection and bottleneck strategy are applied inside each block. The input $v_{t-M+1}, ..., v_t$ is uniformly processed by ST-Conv blocks to explore spatial and temporal dependencies coherently. Comprehensive features are integrated by an output layer to generate the final prediction $\\hat{v}$. \n\n## Results  \n|      Model      |                    | PeMSD7(M) (15/30/45 min) |                    |                    | PeMSD7(L) (15/30/45 min) |                    |\n|:---------------:|:------------------:|:------------------------:|:------------------:|:------------------:|:------------------------:|:------------------:|\n|        /        |         MAE        |          MAPE(%)         |        RMSE        |         MAE        |          MAPE(%)         |        RMSE        |\n|        HA       |        4.01        |           10.61          |        7.20        |        4.60        |           12.50          |        8.05        |\n|       LSVR      |   2.50/3.63/4.54   |      5.81/8.88/11.50     |   4.55/6.67/8.28   |   2.69/3.85/4.79   |      6.27/9.48/12.42     |   4.88/7.10/8.72   |\n|      ARIMA      |   5.55/5.86/6.27   |     12.92/13.94/15.20    |   9.00/9.13/9.38   |   5.50/5.87/6.30   |     12.30/13.54/14.85    |   8.63/8.96/9.39   |\n|       FNN       |   2.74/4.02/5.04   |      6.38/9.72/12.38     |   4.75/6.98/8.58   |   2.74/3.92/4.78   |     7.11/10.89/13.56     |   4.87/7.02/8.46   |\n|     FC-LSTM     |   3.57/3.94/4.16   |      8.60/9.55/10.10     |   6.20/7.03/7.51   |   4.38/4.51/4.66   |     11.10/11.41/11.69    |   7.68/7.94/8.20   |\n|      GCGRU      |   2.37/3.31/4.01   |      5.54/8.06/9.99      |   4.21/5.96/7.13   |  2.48/3.43/4.12∗  |     5.76/8.45/10.51∗    |  4.40/6.25/7.49∗  |\n| **STGCN(Cheb)** | **2.25/3.03/3.57** |    5.26/**7.33/8.69**    | **4.04/5.70/6.77** | **2.37/3.27/3.97** |    **5.56/7.98/9.73**    | **4.32/6.21/7.45** |\n|  **STGCN(1st)** |   2.26/3.09/3.79   |    **5.24**/7.39/9.12    |   4.07/5.77/7.03   |   2.40/3.31/4.01   |      5.63/8.21/10.12     |   4.38/6.43/7.81   |\n  \n**Table 1: Performance comparison of different approaches on the dataset PeMSD7.**\n  \n\u003cp align=\"center\"\u003e\u003cimg src=\"figures/PeMS_R39.png\" width=\"40%\" height=\"30%\"\u003e\u003cimg src=\"figures/PeMS_R141.png\" width=\"40%\" height=\"30%\"\u003e\u003c/p\u003e\n  \n**Fig. 3: Speed prediction in the morning peak and evening rush hours of the dataset PeMSD7.**\n  \n\u003cp align=\"center\"\u003e\u003cimg src=\"figures/PeMS_Train_Time.png\" width=\"40%\" height=\"30%\"\u003e\u003cimg src=\"figures/PeMS_Train_Time_L.png\" width=\"40%\" height=\"30%\"\u003e\u003c/p\u003e\n  \n**Fig. 4: Time consumptions of training on the dataset PeMSD7 (M, left) and (L, right)**\n\n## Requirements\nOur code is based on Python3 (\u003e= 3.6). There are a few dependencies to run the code. The major libraries are listed as follows:\n* TensorFlow (\u003e= 1.9.0)\n* NumPy (\u003e= 1.15)\n* SciPy (\u003e= 1.1.0)\n* Pandas (\u003e= 0.23)\n\nThe implementation of Spatio-Temporal Graph Convolutional Layer with PyTorch is available in [PyG Temporal](https://github.com/benedekrozemberczki/pytorch_geometric_temporal/blob/master/torch_geometric_temporal/nn/attention/stgcn.py). You might refer to [STConv](https://pytorch-geometric-temporal.readthedocs.io/en/latest/modules/root.html#temporal-graph-attention-layers) that supports ChebConv Graph Convolutions.\n\n## Dataset\n### Data Source\n**[PeMSD7](http://pems.dot.ca.gov/)** was collected from Caltrans Performance Measurement System (PeMS) in real-time by over 39, 000 sensor stations, deployed across the major metropolitan areas of California state highway system. The dataset is also aggregated into 5-minute interval from 30-second data samples. We randomly select a medium and a large scale among the District 7 of California containing **228** and **1, 026** stations, labeled as PeMSD7(M) and PeMSD7(L), respectively, as data sources. The time range of PeMSD7 dataset is in the weekdays of **May and June of 2012**. We select the first month of historical speed records as training set, and the rest serves as validation and test set respectively. \n\nDataset PeMSD7(M/L) is now available under `dataset` folder (station list included). Please refer [issue #6](https://github.com/VeritasYin/STGCN_IJCAI-18/issues/6) for how to download metadata from PeMS.\n\n### Data Format\nYou can make your customized dataset by the following format:  \n- PeMSD7_V_{`$num_route`}.csv : Historical Speed Records with shape of [len_seq * num_road] (len_seq = day_slot * num_dates).\n- PeMSD7_W_{`$num_route`}.csv : Weighted Adjacency Matrix with shape of [num_road * num_road].\n\nNote: please replace the `$num_route` with the number of routes in your dataset. '*.csv' should not contain any index or header in the file.\n\n### Data Preprocessing\nThe standard time interval is set to 5 minutes. Thus, every node of the road graph contains **288** data points per day (day_slot = 288). The linear interpolation method is used to fill missing values after data cleaning. In addition, data input are normalized by Z-Score method.  \nIn PeMSD7, the adjacency matrix of the road graph is computed based on the distances among stations in the traffic network. The weighted adjacency matrix W can be formed as,  \n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://latex.codecogs.com/svg.image?\\large\u0026space;w_{ij}=\\left\\{\u0026space;\\begin{aligned}\u0026space;\u0026\\exp(-\\frac{{d_{ij}^2}}{{\\sigma^2}}),~i\u0026space;\\neq\u0026space;j~\\text{and}~\\exp(-\\frac{{d_{ij}^2}}{{\\sigma^2}})\u0026space;\\geq\u0026space;\\epsilon\\\\\u0026space;\u00260\\qquad\\qquad,~\\text{otherwise}.\u0026space;\\end{aligned}\u0026space;\\right.\"/\u003e\n\u003c/p\u003e\n  \nAll of our experiments use 60 minutes as the historical time window, a.k.a. 12 observed data points (M = 12) are used to forecast traffic conditions in the next 15, 30, and 45 minutes (H = 3, 6, 9).\n\n## Model Details\n### Training\npython main.py --n_route {`$num_route`} --graph {`$weight_matrix_file`} \n\n**Default settings**:  \n* Training configs: argparse is used for passing parameters. \n    * n_route=228, graph='default', ks=3, kt=3, n_his=12, n_pred=9 \n    * batch_size=50, epoch=50, lr=0.001, opt='RMSProp', inf_mode='merge', save=10\n* Data source will be searched in dataset_dir = './dataset', including speed records and the weight matrix.\n* Trained models will be saved in save_path = './output/models' every `args.save=10` epochs.\n* Training logs will be saved in sum_path = './output/tensorboard'.  \n\nNote: it normally takes around 6s on a NVIDIA TITAN Xp for one epoch with the batch size of 50 and n_route of 228.\n\n### Folder structure\n```\n├── data_loader\n│   ├── data_utils.py\n│   └── __init__.py\n├── dataset\n│   ├── PeMSD7_V_228.csv\n│   ├── PeMSD7_W_228.csv\n│   ├── PeMSD7_V_1026.csv\n│   └── PeMSD7_W_1026.csv\n├── main.py\n├── models\n│   ├── base_model.py\n│   ├── __init__.py\n│   ├── layers.py\n│   ├── tester.py\n│   └── trainer.py\n├── output\n│   ├── models\n│   └── tensorboard\n├── README.md\n└── utils\n    ├── __init__.py\n    ├── math_graph.py\n    └── math_utils.py\n```\n\n## Updates\n**Feb. 22, 2022**:\n* Sensor Station List of PeMSD7-M released.\n\n**Feb. 11, 2022**:\n* Dataset PeMSD7-L (1,026 nodes) released. \n* Fix the issue in size calculation of temporal channel. Thanks to @KingWang93 and @cheershuaizhao.\n\n**Apr. 18, 2019**: \n* Dataset PeMSD7-M (228 nodes) released.  \n  \n**Jan. 14, 2019**: \n* Code refactoring based on the [Tensorflow-Project-Template](https://github.com/MrGemy95/Tensorflow-Project-Template), following the PEP 8 code style; \n* Function model_save(), model_test() and tensorboard support are added; \n* The process of model training and inference is optimized;\n* Corresponding code comments are updated.\n\n## Citation\nPlease refer to our paper. Bing Yu*, Haoteng Yin*, Zhanxing Zhu. [Spatio-temporal Graph Convolutional Networks: A Deep Learning Framework for Traffic Forecasting](https://www.ijcai.org/proceedings/2018/0505). In *Proceedings of the 27th International Joint Conference on Artificial Intelligence (IJCAI)*, 2018\n\n    @inproceedings{yu2018spatio,\n        title={Spatio-temporal Graph Convolutional Networks: A Deep Learning Framework for Traffic Forecasting},\n        author={Yu, Bing and Yin, Haoteng and Zhu, Zhanxing},\n        booktitle={Proceedings of the 27th International Joint Conference on Artificial Intelligence (IJCAI)},\n        year={2018}\n    }\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVeritasYin%2FSTGCN_IJCAI-18","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVeritasYin%2FSTGCN_IJCAI-18","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVeritasYin%2FSTGCN_IJCAI-18/lists"}