Official repository for the paper: A Simulation Study on Equitable Mobility During City Emergencies, Focusing on Vulnerable Groups Youssef M. Abdelhameid¹ · Dr. Noha Gamal Eldin² ¹ School of Computational Sciences & AI, Zewail City of Science and Technology ² Computer Science Program, Nile University
Traditional urban evacuation models treat populations as homogeneous flows routed through a network — an approach that is dangerously incomplete. The capacity to respond to a crisis is not uniform: a person's age, physical ability, household structure, and socioeconomic status fundamentally determine their ability to evacuate before those around them are already safe.
This repository implements a two-stage computational framework to quantify the Evacuation Equity Gap — the measurable difference in evacuation outcomes between the most and least socially vulnerable individuals — during a large-scale crisis simulation in the Greater Paris (Île-de-France) region.
- Can a robust, multi-dimensional Social Vulnerability Index (SVI) be constructed from individual-level mobility and sociodemographic data, moving beyond broad "special needs" categories?
- Is there a quantifiable Evacuation Equity Gap between vulnerability groups in terms of success rate and evacuation time?
- How do vulnerability-driven behaviors interact with urban mobility modes (walking, cycling, motorized vehicles, public transit) to produce emergent system-level outcomes such as gridlock and widespread evacuation failure?
| Finding | Detail |
|---|---|
| Overall success rate | 18.3% evacuated within 3 hours — extreme difficulty of urban mass evacuation |
| Equity Gap is non-monotonic | U-shaped relationship between SVI and outcomes, driven by mode × congestion interaction |
| Failure by gridlock | MPV-heavy groups trapped in congestion despite vehicle access |
| Failure by isolation | Pedestrian groups unable to cover sufficient distance on foot |
| Paradox of private vehicles | Car access — a peacetime resilience asset — becomes a systemic liability during mass evacuations |
| Dominant observed mode | Walking + public transit (57.6% of agents) |
The framework operates in two sequential stages:
Individual-level SVI scores are derived from 14 sociodemographic variables in the NetMob25 dataset:
- Demographic:
SEX,AGE,DIPLOMA,PMR(reduced mobility status) - Household:
NBPERS_HOUSE,NB_CAR - Mobility assets:
TWO_WHEELER,BIKE,ELECT_SCOOTER - Transit access:
SUB(Navigo),IMAGINER_SUB,OTHER_SUB_PT,BIKE_SUB,NSM_SUB
The pipeline applies vulnerability-aligned feature engineering (ensuring higher values consistently indicate higher vulnerability), nonlinear transformations (inverse-log and log(1+x) to model diminishing returns of resources), and Principal Component Analysis (PCA) for data-driven, objective weighting of components.
The SVI directly parameterizes each agent's behavioral rules:
- Activation delay: higher SVI → longer reaction time before beginning evacuation
- Speed multiplier: higher SVI → reduced effective travel speed
- Patience threshold: higher SVI → lower tolerance for congestion before failing to reroute
Agents navigate a multi-modal network (OpenStreetMap road/walk/bike graphs + IDFM GTFS public transit timetables) across a 50 km evacuation radius centered on Paris over a 3-hour simulation horizon. The simulation was run across 48 parameterized configurations.
For full methodological details, see simulation/README.md.
NetMob25 Book of Abstracts:
Y. M. Abdelhameid and N. Gamal Eldin, "A Simulation Study on Equitable Mobility During City Emergencies, Focusing on Vulnerable Groups," NetMob25 Data Challenge, Paris, 2025. Book of Abstracts — NetMob25
ArXiv: [ArXiv version coming soon]
SEEM/
│
├── README.md This file
├── pyproject.toml Project and dependency configuration
├── uv.lock Locked dependency versions (reproducibility)
│
├── simulation/ Stage 2: ABM simulation package
│ ├── README.md Simulation quick-start and module guide
│ ├── __init__.py
│ ├── preparing_resources.py Network loading and caching
│ ├── configs/ Simulation scenario configurations
│ │ ├── evacuation_simulation.json
│ │ └── simulation_summary.json
│ ├── model/ ABM core: agent class, initializer, analytics
│ │ ├── evacuation_model.py Agent step logic, SVI-driven behavior
│ │ ├── agents_model_initializer.py Population instantiation
│ │ ├── simulation_analytics.py Metrics collection and export
│ │ └── setup.py
│ └── space/ Spatial environment
│ ├── evacuation_area_initializer.py
│ ├── pre_process_amenities.py
│ └── cache/ Pre-computed route geometries (21 files)
│
├── data/
│ └── maps/ Geospatial data (OSM, GTFS, road networks)
│ ├── IDFM-gtfs/ IDF public transit timetables (GTFS format)
│ ├── osmnx_layers/ Pre-built walk/bike/drive GraphML networks
│ └── osm_chunks_pyrosm/ Raw OSM extracts for Île-de-France
│
├── analysis/ Post-simulation analysis code
│ ├── notebooks/
│ │ ├── evacuation_results_analysis.ipynb Equity gap analysis
│ │ ├── public_transport_network.ipynb GTFS network investigation
│ │ └── social_vulnerability_analysis.ipynb SVI construction walkthrough
│ └── scripts/ Python script equivalents of notebooks
│ ├── evacuation_results_analysis.py
│ └── public_transport_network.py
│
├── outputs/ All generated research artifacts
│ ├── simulation_runs/ Per-run JSON metadata (48 runs)
│ ├── agent_states/ Agent-level CSV outputs and journey logs
│ └── figures/ All generated plots, maps, and visualizations
│ ├── svi_analysis/ SVI distribution and statistical analysis
│ ├── evacuation_analytics/ Equity gap figures, mode/vulnerability plots
│ ├── evacuation_maps/ Interactive HTML + static evacuation maps
│ ├── behavioral_modeling/ SVI → behavioral parameter mappings
│ ├── dimensionality_reduction/ PCA / t-SNE validation plots
│ ├── relationships_with_svi/ Feature × SVI correlation plots
│ └── relationships_with_transformations/ Nonlinear transform visualizations
│
├── scripts/
│ └── main.py Simulation entry point
│
└── archive/ Preserved exploratory and intermediate files
├── scratch/ Temporary scripts (t.py, t2.py)
├── root_level_figures/ Earlier-stage duplicate figures
└── profiling_reports/ ydata-profiling HTML reports
This repository is designed for full research reproducibility.
The simulation was executed across 48 parameterized runs. Per-run metadata
is stored in outputs/simulation_runs/evacuation_simulation_{1..48}/, with
info.json and parameters_constants.json documenting the exact configuration
for each run.
The aggregate results used in the paper are in
outputs/agent_states/simulation_outcomes/. All analysis notebooks in
analysis/ reproduce the paper's figures from these CSVs and can be re-run
independently.
Interactive choropleth and evacuation trace maps are available locally at
outputs/figures/evacuation_maps/
Note on raw data: The NetMob25 dataset is not redistributed here in accordance with its data-use agreement. Researchers may request access at https://netmob.org. The SVI scores derived from the dataset are embedded in the simulation configuration and output files. The IDFM GTFS timetables are sourced from IDFM Open Data.
This project uses uv for fast, reproducible dependency management.
# 1. Clone the repository
git clone https://github.com/DEVOLOPER-1/SEEM
cd SEEM
# 2. Install with uv (recommended — uses uv.lock for exact versions)
uv sync
# 3. Alternatively, install with pip
pip install -e .| Package | Role |
|---|---|
agentpy |
Agent-Based Modeling (ABM) framework |
r5py |
Multi-modal routing engine (transit, bike, walk) |
osmnx |
OpenStreetMap network download and analysis |
geopandas / pyrosm |
Geospatial data processing and OSM parsing |
scikit-learn |
PCA and t-SNE for SVI and reduction analysis |
pandas / polars |
High-performance tabular data processing |
matplotlib / seaborn |
Static data visualization and plotting |
folium |
Interactive map and agent trace generation |
python -c "from simulation.preparing_resources import prepare_all; prepare_all()"This validates and caches the OSM network layers (walk, bike, drive) and GTFS
transit data. Skip this step if data/maps/osmnx_layers/ already contains
the pre-built .graphml files (included in the repository).
Open and run analysis/notebooks/social_vulnerability_analysis.ipynb in Jupyter:
jupyter notebook analysis/notebooks/social_vulnerability_analysis.ipynbThis notebook loads the NetMob25 individual-level data, applies feature
engineering and nonlinear transforms, runs PCA, and writes per-agent SVI scores.
It also produces the SVI distribution figures in outputs/figures/svi_analysis/.
python scripts/main.py --config simulation/configs/evacuation_simulation.jsonResults are written to outputs/simulation_runs/ and outputs/agent_states/.
Estimated runtime: 10–60 minutes per run depending on hardware (48 total runs).
# Script
python analysis/scripts/evacuation_results_analysis.py
# Or interactively
jupyter notebook analysis/notebooks/evacuation_results_analysis.ipynbAll outputs are pre-generated and included in this repository. You do not need to re-run the simulation to inspect results.
| Output | Path |
|---|---|
| Agent final states | outputs/agent_states/final_agent_states.csv |
| Journey segment detail | outputs/agent_states/simulation_outcomes/Journey_Segments_Detail.csv |
| Enhanced agent summary | outputs/agent_states/simulation_outcomes/Enhanced_Agent_Summary.csv |
| Per-run metadata (×48) | outputs/simulation_runs/evacuation_simulation_{1..48}/ |
| Figure | Path |
|---|---|
| SVI distribution and choropleth | outputs/figures/svi_analysis/ |
| Equity gap and success rates | outputs/figures/evacuation_analytics/success_rate_by_vulnerability.png |
| Mode × vulnerability heatmap | outputs/figures/evacuation_analytics/transportation_mode_by_vulnerability.png |
| Evacuation time distributions | outputs/figures/evacuation_analytics/evacuation_time_by_vulnerability.png |
| Interactive agent traces (driving) | outputs/figures/evacuation_maps/evacuation_map_vehicle.html |
| Interactive agent traces (walking) | outputs/figures/evacuation_maps/evacuation_map_walking.html |
| Interactive agent traces (cycling) | outputs/figures/evacuation_maps/evacuation_map_bike.html |
If you use this code, methodology, or results, please cite:
@inproceedings{abdelhameid2025simequity,
title = {A Simulation Study on Equitable Mobility During City Emergencies,
Focusing on Vulnerable Groups},
author = {Abdelhameid, Youssef M. and Gamal Eldin, Noha},
booktitle = {NetMob25 Data Challenge},
year = {2025},
address = {Paris, France},
url = {https://zenodo.org/records/17074045}
}This repository is released under the MIT License. See LICENSE for full terms.
The NetMob25 dataset is subject to its own data-use agreement and is not redistributed here. The IDFM GTFS timetables are sourced from the IDFM Open Data platform under their open license. OpenStreetMap data © OpenStreetMap contributors (ODbL).
| Youssef M. Abdelhameid | s-youssef.hameid@zewailcity.edu.eg |
| Noha Gamal Eldin | ngamal@nu.edu.eg |