# STGCN: a purely convolutional model for traffic forecasting

> STGCN_IJCAI-18 is the reference code for the IJCAI 2018 paper on spatio-temporal graph convolutional networks, replacing recurrent units with stacked graph and temporal convolutions over a road network. It ships the PeMSD7 dataset, TensorFlow code and a configurable training script, and it is now mostly a historical artifact.

**VeritasYin/STGCN_IJCAI-18** — [IJCAI'18] Spatio-Temporal Graph Convolutional Networks

- Repository: https://github.com/VeritasYin/STGCN_IJCAI-18
- Stars: 1,244 · Forks: 327
- Language: Python
- License: BSD-2-Clause
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/veritasyin-stgcn-ijcai-18

## Replacing recurrence with convolution over a graph

STGCN is the reference code for the IJCAI 2018 paper Spatio-Temporal Graph Convolutional Networks: A Deep Learning Framework for Traffic Forecasting, and the paper PDF is linked from the README badge.

The contribution is stated plainly in the introduction. Instead of applying regular convolutional and recurrent units, the problem is formulated on graphs and the model is built with complete convolutional structures. The claim is that this is the first time purely convolutional structures are applied to extract spatio-temporal features simultaneously from graph-structured time series in a traffic study.

The distinction matters. The dominant approach to sequence forecasting at the time, and still for many problems, was the recurrent network, which processes a series step by step and carries state forward. A convolutional formulation removes the recurrence, which means the whole input window can be processed in parallel, which is exactly the kind of property that maps well onto a GPU.

The task itself is stated as a standard time series prediction problem: predicting the most likely traffic measurements, speed or flow, in the next H time steps given the previous M observations from a traffic network G. The README gives the formal statement and the accompanying figure showing each v_t as a frame of traffic status at time step t recorded in a graph-structured data matrix.

The licence is BSD-2-Clause, the default branch is master, and the last push was on 2026-06-14.

## ST-Conv blocks and the residual bottleneck

The architecture description in the README is the part to read if you want to understand the model.

The framework consists of two spatio-temporal convolutional blocks, the ST-Conv blocks, and a fully-connected output layer at the end. Each ST-Conv block contains two temporal gated convolution layers with one spatial graph convolution layer in the middle. The residual connection and the bottleneck strategy are applied inside each block. The input is uniformly processed by the ST-Conv blocks to explore spatial and temporal dependencies coherently, and comprehensive features are integrated by the output layer to generate the final prediction.

So the temporal-spatial-temporal ordering inside a block is the design. Gated temporal convolutions handle the sequence dimension, the graph convolution in the middle handles the road network topology, and the residual and bottleneck arrangement keeps the stack trainable and narrow.

The graph structure itself is a weighted adjacency matrix computed from distances between stations, with the standard Gaussian form, w_ij = exp(-d_ij squared over sigma squared) when the exponent is at or above epsilon and zero otherwise. The epsilon threshold matters in practice, because without it every station would be connected to every other and the graph convolution would degenerate into a dense one.

The repository layout matches the model. There is a `models/` directory, a `data_loader/` directory, a `utils/` directory, a `dataset/` folder holding the data, a `figures/` directory with the two diagrams the README embeds, and `main.py` at the root as the training entry point.

## Installing and running on PeMSD7

The code is Python 3 with a floor of 3.6, and the README recommends virtualenv or conda to manage the dependencies. Installation is three commands:

```bash
git clone https://github.com/VeritasYin/STGCN_IJCAI-18.git
cd STGCN_IJCAI-18
pip install -r requirements.txt
```

The requirements file is short and gives you the immediate picture of the stack: tensorflow 1.9.0 or later, numpy 1.15.0 or later, scipy 1.1.0 or later and pandas 0.23.0 or later. TensorFlow 1.x is the constraint that decides whether this installs cleanly on a current machine, and it is worth checking before you spend an afternoon on it.

The dataset is PeMSD7, collected in real time by more than 39,000 sensor stations across the major metropolitan areas of the California state highway system, with the time range covering weekdays in May and June 2012. The first month of historical speed records is the training set and the rest serves as validation and test respectively. The PeMSD7 M and L variants are available under the `dataset` folder with the station list included, and the README points at issue 6 for how to download the metadata from PeMS.

You can build your own dataset in the same format. The historical speed records go in `PeMSD7_V_{num_route}.csv` with a shape of len_seq by num_road, and the weighted adjacency matrix goes in `PeMSD7_W_{num_route}.csv` with a shape of num_road by num_road, where num_route is the number of routes in your dataset and the CSV files should not contain any index or header.

The preprocessing is also described. The standard time interval is 5 minutes, so every node of the road graph contains 288 data points per day. Missing values are filled with linear interpolation after data cleaning, and the inputs are normalized by the Z-Score method.

## The training script and its defaults

Training is started with one command:

```bash
python main.py --n_route {$num_route} --graph {$weight_matrix_file}
```

The default settings are listed in the README and they are a useful summary of the model as configured in the paper. `n_route` is 228, `graph` is `default`, the kernel sizes `ks` and `kt` are both 3, `n_his` is 12 and `n_pred` is 9, batch size is 50, epochs 50, learning rate 0.001, the optimizer is RMSProp, the inference mode is `merge` and `save` is 10.

The history and prediction windows in those numbers match the experimental description. All the experiments use 60 minutes as the historical time window, which is 12 observed data points, to forecast traffic conditions in the next 15, 30 and 45 minutes, which is H equal to 3, 6 and 9.

The paths are conventional and worth knowing before you run anything. Data is searched in `dataset_dir = './dataset'`, trained models are saved to `save_path = './output/models'` every 10 epochs, and training logs go to `sum_path = './output/tensorboard'`. The last one tells you the logs are TensorBoard format, which is a small hint about the framework the code was written against.

The README also lists an alternative implementation. The Spatio-Temporal Graph Convolutional Layer with PyTorch is available in PyG Temporal, and the STConv module there supports ChebConv graph convolutions. That is the route to take if you want the same architecture in PyTorch, and it is also the route that avoids the TensorFlow 1.x problem entirely.

## What this repository is now

The honest assessment is that STGCN_IJCAI-18 is a historical artifact with an unusually complete paper attached, and the PyG Temporal STConv entry in the README says so without saying so.

The repository has no GitHub releases, and the last push was on 2026-06-14. The requirements file is the clearest signal of the vintage, since it lists TensorFlow 1.9 or later alongside old numpy and scipy floors.

That does not make it useless. For understanding traffic forecasting architectures, a fully documented reference implementation with the dataset included, the formal problem statement, the adjacency matrix formula and the results table in one place is genuinely better than a paper alone. The PeMSD7 data is small enough to run on a laptop, the code is a single `main.py` plus a `models/` and a `data_loader/` directory, and the default configuration reproduces the published setup without hunting through a modern framework's API changes.

The results table in the README reports MAE, MAPE and RMSE for the PeMSD7 M and L variants at 15, 30 and 45 minute horizons, which is the number most papers in this area compare against.

So the sensible use is reproduction and study. If you are building a forecasting system now, the framework choice is the real decision, and the PyG Temporal implementation of the same layer is the more current starting point than this TensorFlow 1.x code.

## Conclusion

STGCN_IJCAI-18 fits a student or researcher who wants to read the original 2018 traffic forecasting architecture, run it on the PeMSD7 dataset and see the results table for themselves. It does not fit a new production forecasting system, since it depends on TensorFlow 1.9. Before running it, check the requirements file against your environment, since the pinned TensorFlow floor is the constraint that decides whether the code will install, and consider the PyG Temporal STConv implementation for anything beyond reproducing the paper.

## FAQ

### What is STGCN_IJCAI-18?

It is the reference implementation for the IJCAI 2018 paper Spatio-Temporal Graph Convolutional Networks: A Deep Learning Framework for Traffic Forecasting. The model is built with purely convolutional structures over graph-structured time series rather than regular convolution and recurrent units, and the paper PDF is linked from the README.

### How do I install and train STGCN?

Clone the repository, run `pip install -r requirements.txt`, then start training with `python main.py --n_route {$num_route} --graph {$weight_matrix_file}`. The code is Python 3 with a floor of 3.6, and the README recommends virtualenv or conda.

### What are the default training settings for STGCN?

n_route 228, graph default, kernel sizes ks and kt of 3, n_his 12, n_pred 9, batch size 50, 50 epochs, learning rate 0.001, RMSProp as the optimizer, merge inference mode and saving every 10. Models go to ./output/models and TensorBoard logs to ./output/tensorboard.

### What dataset does STGCN use?

PeMSD7, collected from more than 39,000 Caltrans sensor stations across California's major metropolitan areas for the weekdays of May and June 2012, with the first month as training and the rest as validation and test. The M and L variants are included under the dataset folder with the station list.

### Is there a PyTorch version of the STGCN layer?

Yes. The README points to the PyG Temporal implementation of the spatio-temporal graph convolutional layer, whose STConv module supports ChebConv graph convolutions, and links the project documentation for it.

## Sources

- [Issues](https://github.com/VeritasYin/STGCN_IJCAI-18/issues)
- [License: BSD-2-Clause](https://github.com/VeritasYin/STGCN_IJCAI-18/blob/master/LICENSE)
- [README](https://github.com/VeritasYin/STGCN_IJCAI-18/blob/master/README.md)
- [VeritasYin/STGCN_IJCAI-18 on GitHub](https://github.com/VeritasYin/STGCN_IJCAI-18)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/veritasyin-stgcn-ijcai-18