STM-Graph: A Python Framework for Spatio-Temporal Mapping and Graph Neural Network Predictions

arXiv:2509.10528 · cs.LG, cs.AI · Submitted 2025-09-04 · Read on arXiv

Listen

Transcript

Introduction to the show: ident: AI Radio. Generated commentary on the latest Artificial Intelligence papers.

Tom: Hi, I'm Tom.

Jane: And I'm Jane, here with Lu, Meng and our in-house large language model, Lalam.

Tom: We're looking at the paper: "STM-Graph: A Python Framework for Spatio-Temporal Mapping and Graph Neural Network Predictions".

Jane: Here's the gist of the paper. The gist STM-Graph is an open-source Python framework designed to transform raw spatio-temporal urban event data into graph representations suitable for Graph Neural Network (GNN) training and prediction, addressing challenges in extracting actionable insights from dynamic urban signals.

Tom: Framework Overview STM-Graph is a unified, open, and extensible Python framework for spatial partitioning, urban feature integration, temporal graph construction, GNN model training, and visualization designed to support reproducibility and enable easy integration of custom mapping methods and models STM-Graph is a unified, open, and extensible Python framework for spatial partitioning, urban feature integration, temporal graph construction, GNN model training, and visualization designed to support reproducibility and enable easy integration of custom mapping methods and models.

Jane: The framework facilitates rapid experimentation by abstracting away repetitive low-level tasks such as data engineering STM-Graph facilitates rapid experimentation by abstracting away repetitive low-level tasks such as data engineering.

Tom: Key Components and Functionality The framework integrates diverse functionalities to support an end-to-end pipeline, illustrated in Figure 1 which shows the workflow supporting a complete experimentation pipeline The workflow starts from Data Pre-processing, then Spatial Mapping, Urban Features Graph Extraction, Graph Construction, Temporal Dataset Creation, Visual Analytics, and Model Creation.

Paper summary: Tom: So we've talked about STM-Graph and what it does, from transforming raw data into graphs suitable for GNN training through its specific components like spatial mapping and visualization tools.

Jane: And we touched on how it allows researchers to test different mapping strategies against various GNN architectures on real urban datasets like the NYC three hundred eleven Service Requests.

Lu: The key thing is that this framework provides a reproducible way to compare these different approaches because it formalizes the pipeline from data pre-processing all the way through model creation.

Meng: For deployment, it seems like its value is in making sure you can quickly set up and test hypotheses on your specific urban data structure without getting bogged down in writing every piece of boilerplate code yourself.

Jane: Ultimately, STM-Graph offers a comprehensive tool that streamlines the end-to-end pipeline from raw urban event logs to spatio-temporal GNN predictions, offering flexibility through modularity and accessibility through a GUI.

Tom: The authors position this as an essential tool for reproducible research in urban intelligence because it significantly extends existing spatio-temporal prediction frameworks by explicitly supporting experimentation with diverse spatial mapping methods and seamlessly integrating urban contextual features with GNN architectures.

Lu: It’s positioned as an essential tool for reproducible research in urban intelligence because it lets researchers focus on the actual modeling decisions instead of the infrastructure setup.

Meng: It’s positioned as an essential tool for reproducible research in urban intelligence because it's about making sure that when you try to build these complex models, you have a solid, tested foundation underneath you.

Jane: So, if someone is looking to move from just reading papers to actually building something tangible in the field of urban intelligence, this framework provides the structure they need.

Conclusion: Tom: So we've talked about STM-Graph, how it takes messy urban event data and turns it into graphs that GNNs can actually train on, and we looked at how different spatial mappings like grids or Voronoi cells affect those results.

Jane: Right, so the authors are presenting this framework called STM-Graph to make that whole process much more organized, you know, less of a mess for the people trying to do research.

Lu: I think what they’re really pushing is the modularity. They want researchers to be able to swap out any part—any mapping method or even a completely different GNN model—without rewriting the whole data pipeline from scratch.

Meng: From a production standpoint, that modularity is good because it means if we find a better way to represent urban space, we can plug it in quickly instead of rebuilding the whole system.

Lalam: I see what they're saying is that this framework standardizes the tricky parts, like making sure your temporal and spatial data line up perfectly before you even start training anything.

Tom: It’s about taking something that used to be a custom, fragile setup and turning it into something open source where people can actually reproduce the exact same results.

Jane: That reproducibility is huge because in this field, if you can't show exactly how you got your answer, it doesn't really count.

Lu: This framework is positioned as an essential tool for reproducible research in urban intelligence because it’s giving everyone a solid foundation to build on instead of starting from zero every time.

Meng: I wonder what the actual overhead is for folks moving from a prototype to actually deploying one of these models at scale, but the structure they provide helps with that kind of long-term maintenance.

Lalam: The paper shows that by using this structure, you can test multiple different spatial mapping strategies against several different GNN models all in one organized pipeline.

Tom: So it’s basically a toolkit for anyone who wants to take raw urban event logs and get them into the hands of a sophisticated prediction model.

Jane: It really simplifies the whole journey from that first raw data point to having an actual spatio-temporal prediction ready to go.

Lu: And it suggests that the choice of spatial representation matters as much as the GNN architecture itself when you're dealing with urban patterns.

Meng: It’s a good step for researchers because it removes a lot of the tedious, low-level data engineering tasks that usually slow things down.

Lalam: The authors are basically saying this framework is a way to make complex spatio-temporal modeling accessible to more people in the urban tech community.

Tom: It’s all about making sure the infrastructure supports the innovation, not getting stuck fighting with basic data plumbing.

Jane: So, it’s less about finding one magic model and more about building a flexible system that lets you test many ideas quickly.

Lu: And they do show how this structure helps in understanding exactly where a prediction might be coming from spatially and temporally.

Meng: I'm interested in seeing what happens when people start plugging in real-time streaming data instead of just static datasets like those NYC examples.

Amirhossein Ghaffari, Huong Nguyen, Lauri Lovén, Ekaterina Gilman

Center for Ubiquitous Computing, University of Oulu

cs.LG, cs.AI

Submitted: 2025-09-04

Updated: 2025-09-04

Comments: Accepted manuscript (CC BY 4.0). To appear in ACM CIKM 2025, Seoul, Nov 10-14, 2025. DOI: 10.1145/3746252.3761645. The Version of Record will be uploaded when available

Journal ref: Proceedings of the 34th ACM International Conference on Information and Knowledge Management (CIKM '25), 2025, pp. 6377-6381

DOI: 10.1145/3746252.3761645

Code: https://github.com/Ahghaffari/stm_graph

License: http://creativecommons.org/licenses/by/4.0/

Importance score: 83/100

The gist: The gist STM-Graph is an open-source Python framework designed to transform raw spatio-temporal urban event data into graph representations suitable for Graph Neural Network (GNN) training and

Key concepts

Spatial Mapping: This refers to the process of dividing a geographic area into discrete units like grids or administrative boundaries. STM-Graph supports various methods, such as grid-based or Voronoi mapping, allowing users to choose the spatial structure that best represents urban data for graph creation.
Urban Feature Integration: This involves combining raw event data with external contextual information about the city. The framework allows seamless integration of features sourced from sources like OpenStreetMap, enriching the graph nodes with meaningful real-world urban context.
Graph Neural Networks (GNNs): These are machine learning models specifically designed to analyze data structured as graphs. STM-Graph provides the necessary tools to train custom spatio-temporal GNN models, enabling predictions based on both the spatial relationships and the time evolution of urban events.
Modularity and Extensibility: The framework is designed with a modular structure, meaning different components like mapping methods or GNN models can be easily plugged in. This allows for rapid experimentation and customization without needing to rewrite the entire system for new research needs.

Terminology

Graph Neural Network — 2× in this paper
Benchmarking — 1× in this paper · explained in 4 episodes
Graph Neural Network (GNN) — 1× in this paper · explained in 5 episodes

Summary

The gist

STM-Graph is an open-source Python framework designed to transform raw spatio-temporal urban event data into graph representations suitable for Graph Neural Network (GNN) training and prediction, addressing challenges in extracting actionable insights from dynamic urban signals.

Framework Overview

STM-Graph is a unified, open, and extensible Python framework for spatial partitioning, urban feature integration, temporal graph construction, GNN model training, and visualization designed to support reproducibility and enable easy integration of custom mapping methods and models STM-Graph is a unified, open, and extensible Python framework for spatial partitioning, urban feature integration, temporal graph construction, GNN model training, and visualization designed to support reproducibility and enable easy integration of custom mapping methods and models. The framework facilitates rapid experimentation by abstracting away repetitive low-level tasks such as data engineering STM-Graph facilitates rapid experimentation by abstracting away repetitive low-level tasks such as data engineering.

Key Components and Functionality

The framework integrates diverse functionalities to support an end-to-end pipeline, illustrated in Figure 1 which shows the workflow supporting a complete experimentation pipeline The workflow starts from Data Pre-processing, then Spatial Mapping, Urban Features Graph Extraction, Graph Construction, Temporal Dataset Creation, Visual Analytics, and Model Creation. Key components include:

Spatial Mapping: STM-Graph explicitly supports experimentation with diverse spatial mapping methods including grid-based, administrative boundarybased, and degree-based Voronoi mapping STM-Graph explicitly supports experimentation with diverse spatial mapping methods including grid-based, administrative boundarybased, and degree-based Voronoi mapping.
Urban Feature Integration: It allows for the seamless integration of urban contextual features sourced externally, such as those from OpenStreetMap via OSMnx It allows for the seamless integration of urban contextual features sourced externally, such as those from OpenStreetMap via OSMnx.
GNN Model Training and Evaluation: Users can design custom spatio-temporal graph neural network models, specify hyperparameters, and perform training and evaluation Users can design custom spatio-temporal graph neural network models, specify hyperparameters, and perform training and evaluation.
Visualization Tools: The framework provides comprehensive visualization tools enabling users to explore urban datasets through dynamic plots and spatial maps with zoom and navigation The framework provides comprehensive visualization tools enabling users to explore urban datasets through dynamic plots and spatial maps with zoom and navigation.

Implementation Details

STM-Graph is implemented in Python (version 3.8) and leverages widely adopted open-source libraries for performance, including PyTorch, PyTorch Geometric, and PyTorch Geometric Temporal for GNN models STM-Graph is implemented in Python (version 3.8) and leverages widely adopted open-source libraries for performance, including PyTorch, PyTorch Geometric, and PyTorch Geometric Temporal for GNN models. The core dependencies also include NetworkX [10] for general graph processing STM-Graph is implemented in Python (version 3.8) and leverages widely adopted open-source libraries for performance, including PyTorch, PyTorch Geometric, and PyTorch Geometric Temporal for GNN models. The modular design allows users to plug in custom models, datasets, and experimental settings STM-Graph is implemented in Python (version 3.8) and leverages widely adopted open-source libraries for performance, including PyTorch, PyTorch Geometric, and PyTorch Geometric Temporal for GNN models.

Experimental Validation

The framework was evaluated using two publicly available urban datasets from New York City: the NYC 311 Service Requests dataset and the Motor Vehicle Collisions dataset The experimental setup involved comparing different spatial mapping strategies—Grid-based, Administrative, and Degree-based Voronoi—across three custom GNN models: STGCN [31], T-GCN [32], and GCN [14]. The comparison highlighted that increasing the cell size in grid-based mapping yields smaller graphs, but adopting a coarser grid cell consistently improves accuracy and overall prediction metrics for every model tested The results demonstrated how different spatial mapping methods impact predictive performance across multiple GNN models.

Usability and Accessibility

To improve usability, STM-Graph provides a user-friendly Graphical User Interface (GUI) built with PyQt6, which is available in two formats: source code and a portable executable packaged with PyInstaller The GUI offers several key features, including Visualization tools for exploring datasets through dynamic plots and spatial maps, Complete Data Generation Pipeline guiding users through the transformation process, Model Training capabilities allowing direct training of GNN models with hyperparameter configuration, and Logging and Monitoring supporting both local logging and integration with Weights & Biases (W&B). This GUI is designed to facilitate interactive data processing, visualization, and model training for diverse user groups The GUI is designed to facilitate interactive data processing, visualization, and model training for diverse user groups.

Conclusion

STM-Graph provides a comprehensive tool that streamlines the end-to-end pipeline from raw urban event logs to spatio-temporal GNN predictions, offering flexibility through modularity and accessibility through a GUI STM-Graph provides a comprehensive tool that streamlines the end-to-end pipeline from raw urban event logs to spatio-temporal GNN predictions, offering flexibility through modularity and accessibility through a GUI. The framework significantly extends existing spatio-temporal prediction frameworks by explicitly supporting experimentation with diverse spatial mapping methods and seamlessly integrating urban contextual features with GNN architectures STM-Graph significantly extends existing spatio-temporal prediction frameworks by explicitly supporting experimentation with diverse spatial mapping methods and seamlessly integrating urban contextual features with GNN architectures. The framework is positioned as an essential tool for reproducible research in urban intelligence STM-Graph is positioned as an essential tool for reproducible research in urban intelligence. The work was supported by the Emerging Projects program, Infotech Oulu; European Commission (101137711); European Regional Development Fund (A81373); Research Council of Finland (323630); and Business Finland (8754/31/2022). The paper is licensed under a Creative Commons Attribution 4.0 International License.

References

[1] Geoff Boeing. 2025. Modeling and analyzing urban networks and amenities with OSMnx. Geographical Analysis (2025).

[3] Mao Chen, Liangzhe Han, Yi Xu, Tongyu Zhu, Jibin Wang, and Leilei Sun. 2024. Temporal-aware structure-semantic-coupled graph network for traffic forecasting. Information Fusion 107 (2024), 102339.

[4] Davide Chicco and Giuseppe Jurman. 2020. The advantages of the Matthews correlation coefficient (MCC) over F1 score and accuracy in binary classification evaluation. BMC genomics 21 (2020), 1–13.

[5] Pengfei Cui, Xiaobao Yang, Mohamed Abdel-Aty, Jinlei Zhang, and Xuedong Yan. 2024. Advancing urban traffic accident forecasting through sparse spatiotemporal dynamic learning. Accident Analysis & Prevention 200 (2024), 107564.

[6] Rodrigo de Medrano and Jose L Aznarte. 2020. A spatio-temporal attention-based spot-forecasting framework for urban traffic prediction. Applied Soft Computing 96 (2020), 106615.

[7] Jing Gan, Qiao Yang, Dapeng Zhang, Linheng Li, Xu Qu, and Bin Ran. 2024. A Novel Voronoi-Based Spatio-Temporal Graph Convolutional Network for Traffic Crash Prediction Considering Geographical Spatial Distributions. IEEE Transactions on Intelligent Transportation Systems (2024).

[8] Amirhossein Ghaffari, Susanna Pirttikangas, and Ekaterina Gilman. 2025. Understanding Well-Being in Urban Context, a Survey. IEEE Access (2025).

[9] Ekaterina Gilman, Francesca Bugiotti, Ahmed Khalid, Hassan Mehmood, Panos Kostakos, Lauri Tuovinen, Johanna Ylipulli, Xiang Su, and Denzil Ferreira. 2024. Addressing Data Challenges to Drive the Transformation of Smart Cities. ACM Trans. Intell. Syst. Technol. 15 (Nov).

[10] Aric Hagberg, Pieter J Swart, and Daniel A Schult. 2008. Exploring network structure, dynamics, and function using NetworkX. Technical Report.

[11] Junjie Hu, Jun Bai, Jiayu Yang, and Jaeyoung Jay Lee. 2025. Crash risk prediction using sparse collision data: Granger causal inference and graph convolutional network approaches. Expert Systems with Applications 259 (2025), 125315.

Improvements for AI systems

Spatio-temporal GNN prediction on irregular urban data: The system can model spatial dependencies in irregular urban data by encoding entities as nodes and their relationships as edges, which is explicitly supported by STM-Graph’s ability to transform raw spatio-temporal urban event data into graph representations.
Flexible spatial mapping experimentation: The framework allows researchers to explicitly support experimentation with diverse spatial mapping methods, including grid-based, administrative boundarybased, and degree-based Voronoi mapping, enabling the comparison of how different mappings significantly affect model accuracy.
Enhanced interpretability through visualization: The system provides comprehensive visualization tools such as spatial heatmaps and time-series plots of highly active nodes, allowing users to explore data dynamically to understand patterns before or after training.
Accessibility for diverse users: The inclusion of a GUI designed for both professional researchers and non-expert users allows city stakeholders and practitioners to perform tasks like interactive data processing, visualization, and model training without needing deep knowledge of low-level infrastructure.
Accelerated innovation through modularity: By abstracting away repetitive low-level tasks, STM-Graph facilitates rapid experimentation and benchmarking, allowing researchers to focus on domain questions rather than infrastructure.

Abstract

Urban spatio-temporal data present unique challenges for predictive analytics due to their dynamic and complex nature. We introduce STM-Graph, an open-source Python framework that transforms raw spatio-temporal urban event data into graph representations suitable for Graph Neural Network (GNN) training and prediction. STM-Graph integrates diverse spatial mapping methods, urban features from OpenStreetMap, multiple GNN models, comprehensive visualization tools, and a graphical user interface (GUI) suitable for professional and non-professional users. This modular and extensible framework facilitates rapid experimentation and benchmarking. It allows integration of new mapping methods and custom models, making it a valuable resource for researchers and practitioners in urban computing. The source code of the framework and GUI are available at: https://github.com/Ahghaffari/stm graph and https://github.com/tuminguyen/stm graph gui.