WalkGeoAI: Open-source software for estimating street-level relative pedestrian activity using global geospatial data

WalkGeoAI is an inference-only software release for estimating relative street-level pedestrian activity from GIS data. It calculates 204 road-segment features, constructs a road-segment graph with 10 random-walk structural encodings (RWSE), applies a pretrained four-layer GatedGCN, and writes road-level predictions with an inference quality-control report. The release does not include model training, cross-validation, ablation analysis, or manuscript figure generation. Release archives The Zenodo release is distributed as two archives: WalkGeoAI_v1.0.0_software.zip: source code, pretrained model, environment files, feature dictionary, documentation, and a complete Singapore usage example. WalkGeoAI_20city_data_v1.0.0.zip: GIS inputs, calculated feature files, and completed outputs for 20 cities. The software archive is self-contained for the Singapore tutorial. The separate data archive is required only when the remaining city datasets or all 20 completed city outputs are needed. Additional city directories from that archive can be placed beside the included Singapore directory. What the pipeline does No manual intermediate GIS processing is required after the input files have been prepared with the required names and schemas. For a selected city, the complete pipeline: Validates the required GIS inputs. Calculates seven groups of road-segment features. Checks the resulting 204 feature columns against the checkpoint schema. Constructs the exact road-segment graph from shared junction identifiers. Appends a 10-dimensional RWSE representation. Applies checkpoint-based median imputation and feature scaling. Runs full-city GatedGCN inference and 100 Monte Carlo Dropout passes. Writes road_predictions.geojson and inference_qc.json. No manual intermediate GIS processing is required after the input files have been prepared with the required names and schemas. Model and interpretation The included checkpoint is: model/best_Pooled_Model_active_density.pt Its SHA256 checksum is: cfbfeb628cfe84c11f572c58018987a1f924903b6727cb62de6c6a8738797855 The model was trained using the corrected New York and Beijing pipeline. It uses 204 GIS-derived features, 10 RWSE dimensions, four GatedGCN layers, and four-hop neighbour sampling [6, 4, 3, 2]. pred_density is a percentile ranking from 0 to 1 within the processed city. It is not an observed pedestrian count, a physical density, or an absolute value that can be compared directly between cities. Results outside the training cities should be treated as transferred model estimates unless separately validated against local observations. Directory structure After combining the software and data archives, the expected structure is: WalkGeoAI_v1.0.0/|-- run_pipeline.py|-- verify_release.py|-- walkgeoai/ # Feature extraction and inference code|-- model/| `-- best_Pooled_Model_active_density.pt|-- Singapore/ # Complete usage example| |-- shp file/ # Eight GIS input files| |-- data file/ # Seven calculated feature tables| `-- outputs/ # Example predictions and inference QC|-- Feature dictionary.csv|-- MODEL_SHA256.txt|-- README.md|-- README_DATA.md|-- TUTORIAL.md|-- VERSION|-- requirements.txt`-- environment.yml All operational paths are resolved relative to WalkGeoAI_v1.0.0. Additional city folders should be placed at the same level as Singapore. The extracted directory can be moved without editing hard-coded project paths. Verify the model and any extracted city outputs with: python verify_release.py Required GIS inputs Despite the historical directory name shp file, the current release expects specifically named GeoJSON, GeoTIFF, and CSV files rather than arbitrary ESRI Shapefiles. Create <City>/shp file/ and provide: Required filename Required content road_all.geojson Road segments with unique id, from, to, highway, and geometry fields Administrative_buildup.geojson City analysis boundary population_source.tif Population raster NASADEM.tif Elevation raster *WorldCover*.tif One or more matching WorldCover raster tiles NDVI.tif NDVI raster 3DGloBFP.geojson Building footprints with available height information POI.csv Point-of-interest records All geospatial layers must contain valid coordinate reference information and cover the same city extent. The supplied city directories demonstrate the expected schemas. Feature dictionary.csv defines the 204 model features. Environment Python 3.10 is recommended. A tested Windows environment used: Python 3.10.19 PyTorch 2.5.1 with CUDA 12.4 PyTorch Geometric 2.7.0 pyg-lib 0.4.0 for PyTorch 2.5 and CUDA 12.4 NumPy 1.26.4 pandas 2.3.3 SciPy 1.15.2 GeoPandas 1.1.2 Shapely 2.0.7 Rasterio 1.4.3 Create the supplied environment: conda env create -f environment.ymlconda activate walkgeoai-inference PyTorch Geometric neighbour sampling requires a compatible pyg-lib or torch-sparse installation. For the tested PyTorch 2.5 and CUDA 12.4 build, run: python -m pip install pyg_lib -f https://data.pyg.org/whl/torch-2.5.0+cu124.html For a CPU-only PyTorch 2.5 build, replace cu124 with cpu. Confirm that the wheel matches the installed PyTorch build before inference. The tested environment used pyg-lib 0.4.0+pt25cu124. A CUDA-capable GPU is strongly recommended for full-city inference. CPU execution is supported by the code but may be impractical for the largest cities. Quick start The included Singapore directory makes the software archive immediately runnable. From WalkGeoAI_v1.0.0, check its GIS inputs and calculated features: python run_pipeline.py --city "Singapore" --steps check Recalculate all seven feature groups from the GIS inputs and run inference: python run_pipeline.py --city "Singapore" --steps all --force-features Run inference using feature CSV files already present in data file: python run_pipeline.py --city "Singapore" --steps inference The default settings are a batch size of 4096, 100 Monte Carlo Dropout passes, seed 42, and the checkpoint neighbour sizes [6, 4, 3, 2]. For a shorter guided example, including expected files and outputs, see TUTORIAL.md. Useful alternatives are: # Calculate features onlypython run_pipeline.py --city "Singapore" --steps features --force-features # Disable uncertainty estimation for a quick deterministic runpython run_pipeline.py --city "Singapore" --steps inference --mc-samples 0 # Reduce GPU memory usepython run_pipeline.py --city "Singapore" --steps inference --batch-size 1024 Calculated features Feature group Output file Model features Network topology net_topology_features.csv 29 Population demand pop_demand_features.csv 4 Terrain and topography terrain_topography_features.csv 7 Urban context urban_context_features.csv 6 Building morphology bldg_morphology_features.csv 32 Land cover and greenness landcover_greenness_features.csv 61 POI activity poi_density_buf200.csv 65 Total 204 The feature tables are written to <City>/data file/. Missing numeric cells are imputed with training-set medians stored in the checkpoint; they are never silently filled with zero by the current model. Every imputation is recorded in inference_qc.json. Outputs The pipeline writes the following files to <City>/outputs/. road_predictions.geojson The source road geometry and identifiers are preserved, with two added fields: Field Description pred_density Relative within-city pedestrian-activity percentile from 0 to 1 pred_uncertainty Standard deviation of the raw prediction across Monte Carlo Dropout passes inference_qc.json The QC report records the model checksum, device, road and graph sizes, feature schema, missing-value handling, sampling depth, seed, Monte Carlo count, runtime, warnings, and output file. Included city data The software archive includes one complete Singapore example with GIS inputs, seven calculated feature tables, and completed outputs. These files support both a full feature recalculation and direct inference from the supplied features. The separate data archive contains Abuja, Amsterdam, Beijing, Cape Town, Chicago, Dubai, Hong Kong, London, Los Angeles, Melbourne, New Delhi, New York, Paris, Philadelphia, Prague, San Francisco, Santiago, São Paulo, Seoul, and Singapore. Together, the archived outputs cover 5,711,398 road segments. All 20 supplied outputs use the checkpoint checksum shown above, neighbour sizes [6, 4, 3, 2], seed 42, and 100 Monte Carlo Dropout passes. Some deployment cities required checkpoint-median imputation for an unavailable urban subcentre feature; affected cells and warnings are recorded city by city in the QC files. Using another city Create a city directory with the required shp file inputs, then run: python run_pipeline.py --city "YourCity" --steps all --force-features The pipeline creates the data file and outputs directories automatically. Scope and limitations WalkGeoAI estimates relative road rankings, not absolute pedestrian counts. Transfer performance can vary with local data quality and urban form. Monte Carlo Dropout dispersion is not a calibrated confidence interval. A successful software run does not constitute local empirical validation. GIS inputs and derived data remain subject to their original source licenses and attribution requirements.