Framework Overview¶
URBADAPT is a modular, city-agnostic geospatial framework for urban climate risk assessment and adaptation cost-benefit analysis at the Functional Urban Area (FUA) scale. URBADAPT-HEAT is its heat-specific implementation.
Architecture¶
The framework integrates the CLIMADA probabilistic risk engine (v6.1.0) with purpose-built pre- and post-processing workflows. Configuration is fully externalised to city-specific YAML files so that the same analytical code operates across cities without modification.
City YAML config
│
▼
┌─────────────────────────────────────────────────────┐
│ URBADAPT-HEAT pipeline │
│ │
│ Hazard ──► Exposure ──► Vulnerability │
│ └──────────────────────────► Impact Functions │
│ │ │
│ ▼ │
│ CLIMADA risk calc │
│ │ │
│ Adaptation module │
│ (AC · Trees · EWS) │
│ │ │
│ Cost-Benefit Analysis │
│ + Uncertainty module │
└─────────────────────────────────────────────────────┘
The workflow is a sequential pipeline of modular computational notebooks, each with a well-defined input–output interface. Individual stages can be re-run in isolation without reprocessing upstream steps.
Spatial domain¶
| Item | Detail |
|---|---|
| Boundary | GHS-FUA (Global Human Settlement Layer Functional Urban Area) |
| Projection | EPSG:3035 — Lambert Azimuthal Equal-Area (all raster operations) |
| Resolution | ~100 m (UrbClim native grid) |
| CLIMADA coordinates | WGS84 / EPSG:4326 (centroid storage only) |
All raster layers are harmonised to the UrbClim reference grid in EPSG:3035. Area-preserving (conservative) resampling is used for all count-based variables (population, Census statistics).
Target years and scenarios¶
| Dimension | Values |
|---|---|
| Target years | 2020 (synthetic baseline) · 2030 · 2040 · 2050 |
| Climate scenarios | CurPol · GS · SP · SSP5-8.5 (CMIP6 ensemble via PROVIDE) |
| Climate uncertainty | Low / Central / High (25th / 50th / 75th percentile across GCMs) |
| Demographic scenarios | SSP1–5, SSP2-DM, SSP2-ZM (Wittgenstein Centre) |
| Hazard tracks | Track A (standard daily-mean) · Track B (extreme-event / heatwave) |
City-agnostic design¶
The current notebooks are city-agnostic. All city-specific behaviour is externalised to the YAML config, and a run is selected onto a city by three environment variables set at the top of NB01:
| Environment variable | Default | Role |
|---|---|---|
CITY |
Rome |
Selects the city — resolves configs/<city>.yml. This is the only per-city line in the template notebooks. |
URBAN_HEAT_OUTPUT_VARIANT |
masselot_main_agnostic |
Names the output namespace, so parallel variants never overwrite each other. |
IF_MAIN_FAMILY |
masselot_tail |
Selects the deterministic impact-function family promoted to the canonical downstream slot (see Impact Functions). |
cityheat.nbsetup.bootstrap(city) locates the repo root (via the URBAN_HEAT_ROOT env var or upward traversal), loads and validates the config, and returns resolved input/output paths. Downstream notebooks resolve every file through a config-driven P() / OUTP() helper (cityheat.paths) so there are no hard-coded local paths.
Outputs are written under urban-heat/outputs_variants/<variant>/<city>/ (with tables/, figures/, and interim .npz/HDF5 assets), keeping each variant self-contained and the legacy outputs/ tree untouched.
Pipeline modules¶
The canonical notebooks live in urban-heat/notebooks/city_agnostic/March2026_agnostic/. A single template/ holds the city-agnostic notebook set (un-suffixed filenames); ready-to-run per-city copies (Rome/, Athens/, Lisbon/, Copenhagen/) sit alongside it with the CITY selector pre-set and a _<City> filename suffix. The two are functionally identical — the template is the source of truth.
| Template notebook | Module | Output |
|---|---|---|
01_setup_0126.ipynb |
Setup | Config loaded, paths resolved, data synced from Drive; input audit (FUA, LCZ, GVI, historical UrbClim, cooling coefficients); masked LCZ raster |
02_grids_0126.ipynb |
Grids · Hazard · Exposure · Vulnerability | Daily-T2M hazard files, reference grid + FUA mask, age-structured population (conservative reprojection), WCDE future scaling, baseline SVI layer |
03_hazard_exposure_0126.ipynb |
CLIMADA objects & projected vulnerability | CLIMADA Hazard (daily T2M, frequency-corrected) + age-differentiated Exposures; time-varying projected SVI and exposure_with_vulnerability files |
04_impact_functions_sensitivity.ipynb |
Impact functions | Masselot city+age-specific ImpactFuncSet (main); Burke polynomial/power-law written as sensitivity families |
05_AC_0126.ipynb |
Adaptation – AC | Income-downscaled AC coverage, income-targeted vs uniform policies, avoided deaths, electricity demand, waste-heat feedback, EWS deaths-threshold calibration |
06_EWS_0126.ipynb |
Adaptation – EWS | Deaths-triggered warning days, ramped avoided deaths, EWS costs, 25-year horizon |
07_vegetation_0126_emulator2.ipynb |
Adaptation – Trees | ΔGVI Q3 catch-up allocation, ΔLST → ΔT2M cooling via emulator, four-scenario avoided deaths, equity sensitivity, tree costs |
08_CBA_0126.ipynb |
CBA | PV costs/benefits, BCR, Pareto frontier, equity + public/private stratification, waste-heat & electricity interactions, Track A/B selection |
09_uncertainty_0126_improved_fast.ipynb |
Uncertainty | Thin wrapper around cityheat.nb09_improved_fast: Monte Carlo distributions, PAWN sensitivity indices |
10_summary_0126.ipynb |
Summary | Thin wrapper around cityheat.nb10_summary: aggregated results tables and figures |
A thin driver notebook stub at urban-heat/notebooks/00_run_city.ipynb is reserved for orchestrating a full city run.
cityheat Python package¶
The cityheat package (installed via pip install -e .) is intentionally thin: most of the modelling logic lives inline in the notebooks, and only a focused set of helpers is factored out into real modules. The rest of the analytical stages (grids, hazard, AC downscaling, costs, trees, benefits, plotting) are implemented directly in their notebooks — the corresponding config.py, grids.py, hazards.py, impacts.py, benefits.py, costs.py, ac_downscale.py, trees.py, mix.py, plotting.py, data_io.py, and run_city.py files are currently empty placeholders reserved for future refactoring.
The populated modules are:
| Module | Purpose |
|---|---|
nbsetup.py |
Repo-root discovery and bootstrap(city): loads/validates the config, sets CITY/WP_ISO3/WP_COUNTRY, resolves input & output paths |
paths.py |
Config-driven P() (input, existence-checked) and ensure_out() / OUTP() (output, auto-mkdir) path resolvers |
income_source.py |
Income input resolution — observed sub-municipal tables or the income emulator (income: config block) used for AC downscaling |
vulnerability_layer.py |
Baseline and projected SVI construction from thermal / foreign-born / non-employment components |
dynamic_vulnerability.py |
Notebook-facing wrapper for projected vulnerability + exposure_with_vulnerability refresh; loads ref grid and city mask from cached intermediates |
vulnerability_diagnostics.py |
Diagnostic plots and summary statistics for SVI layers |
nb04_masselot_main.py |
Masselot-main impact-function construction (constant-tail / log-linear-tail) + Burke sensitivity artefacts |
nb09_improved.py / nb09_improved_fast.py |
Full and fast uncertainty quantification (Monte Carlo, PAWN) |
nb10_summary.py |
Summary statistics and final reporting |
Parallel *_masselot_main.py variants (nb04_masselot_main, nb09_improved_fast_masselot_main, nb10_summary_masselot_main, nbsetup_masselot_main) support the Masselot production track.
Design principles¶
- City-agnostic execution — one notebook set runs any configured city; a single
CITYline and its YAML config are the only things that change. - Mechanism-based adaptation — each adaptation option operates on the correct model element (hazard, impact function, or event-specific mortality) rather than on a uniform risk metric.
- Incremental against current-AC baseline — policies are evaluated against observed AC penetration, not a hypothetical no-adaptation counterfactual.
- Time-consistent hazard, exposure, and vulnerability — projected SVI (NB03) evolves alongside climate and population, so equity diagnostics use year- and scenario-matched layers (with an explicit frozen-vulnerability diagnostic as the deliberate exception).
- Distributional tracking — mortality benefits and costs are stratified by social vulnerability quintile and by public vs. private cost bearer.
- Reproducibility — inputs, parameters, and intermediate outputs are stored in documented, variant-namespaced locations; output manifests record every configuration choice.
This page is maintained in the URBADAPT-HEAT wiki and synced automatically. Edit it there, not in the website repository.