Software pipeline for the high-resolution estimation of air temperatures and probabilistic heat hazards in urban regions

This is a deep-learning framework for spatially resolved air-temperature prediction. It combines a temporal meteorological sequence with local geospatial embedding patches to estimate daily minimum ($T{min}$) and maximum ($T{max}$) air temperature. The quantile-regression models produce a conditional predictive distribution rather than a single deterministic value, enabling uncertainty-aware maps and heat-event probabilities.

The framework contains data preparation, spatial and temporal model components, training and fine-tuning scripts, evaluation utilities, and practical spatial inference. Model settings are managed with Hydra, and experiment artefacts can be tracked with MLflow.

This repository contains the accompanying codebase for the paper 'Multi-modal deep learning for generating high-resolution probabilistic maps of urban heat risk
based on daily extreme air temperatures' by Svea Krikau, Susanne A. Benz and Sina Keller.

Model Framework

The two-branch architecture consists of:

• A temporal branch that encodes a lagged meteorological sequence.
• A spatial convolutional branch that encodes a local patch of geospatial embeddings.
• A fusion head that estimates quantiles for $T{min}$ and $T{max}$; cross-attention fusion is supported for compatible checkpoints.

For a set of quantile levels $q$, the model output is ordered as

$$
[T_{min}^{(q1)}, \ldots, T{min}^{(qQ)},
T{max}^{(q1)}, \ldots, T{max}^{(q_Q)}].
$$

The application workflow estimates tropical-night and hot-day probabilities from the interpolated quantile CDF:

$$
P(T > \tau) = 1 - F_T(\tau),
$$

where $\tau=20\,^{\circ}\mathrm{C}$ for tropical nights ($T{min}$) and $\tau=30\,^{\circ}\mathrm{C}$ for hot days ($T{max}$) by default.

Installation

Create the project environment from the supplied Conda specification:

conda env create -f environment_horeka.yaml
conda activate heat-r

The inference application requires Python, PyTorch, PyTorch Lightning, Hydra/OmegaConf, NumPy, GeoPandas, Rasterio, Rioxarray, and TQDM. The supplied environment file includes these dependencies.

Applying A Trained Model

src/example_application.py is a standalone spatial inference example. It does not create or load a datamodule. Instead, it loads the model architecture from the Hydra configuration adjacent to the checkpoint, uses saved min-max scaling statistics, and generates a synthetic meteorological sequence unless real meteorological data are supplied.

The repository includes a Karlsruhe embedding raster and Innenstadt region of interest:

• data/example/embeddings_Karlsruhe_2024_3035_32.tif
• data/example/Karlsruhe_Innenstadt.gpkg
• data/scaling_karlsruhe.json

Run the bundled application on CPU:

python src/example_application.py --device cpu

By default, the script selects the first checkpoint found under output/model_B/, uses the bundled raster and ROI, and writes outputs to output/example_application/. For reproducible model selection, pass a checkpoint explicitly:

python src/example_application.py \
  --device cpu \
  --checkpoint output/path/to/model.ckpt \
  --target-date 2024-07-15

Use a CUDA device when available:

python src/example_application.py --device cuda --checkpoint output/path/to/model.ckpt

Real Meteorological Input

Pass --meteo-file to use real ERA5-style data instead of the synthetic demonstration sequence. The input must be a .npy or comma-separated text file with shape [time, features], containing raw, unscaled values in the same feature order used to train the checkpoint. Its feature count must match hostrada_min and hostrada_max in the selected scaling JSON. The script keeps the final lag_size rows and pads shorter input sequences with the first available row.

The expected feature-column order is:

t2m, pev, slhf, sshf, ssrd, tp, skt, swvl1, u10, v10

data/example/era5_example_72h.csv is a headerless, 72-hour ERA5-style demonstration file in this order. It represents three repeated warm, dry summer diurnal cycles: 2-m air temperature ranges from approximately $17.6$ to $29.9\,^{\circ}\mathrm{C}$, daytime radiation peaks at 157, precipitation is zero, soil water is approximately 0.30, and winds are light. It is synthetic data for verifying the inference pipeline, not an observed ERA5 extraction.

Run the application with the bundled file:

python src/example_application.py \
  --meteo-file data/example/era5_example_72h.csv \
  --device cpu

python src/example_application.py \
  --checkpoint output/path/to/model.ckpt \
  --meteo-file era5_sequence.npy \
  --scaling-stats data/scaling_karlsruhe.json \
  --target-date 2024-07-15 \
  --device cpu

Another Region

Provide a georeferenced embedding raster, ROI vector layer, and scaling statistics compatible with the trained model. The raster must have the channel count expected by the checkpoint and the same embedding semantics used during training.

python src/example_application.py \
  --checkpoint output/path/to/model.ckpt \
  --raster data/example/embeddings_other_region.tif \
  --roi data/example/other_region.gpkg \
  --scaling-stats data/scaling_european.json \
  --meteo-file era5_sequence.npy \
  --output-dir output/other_region \
  --device cpu

Output Products

All outputs are GeoTIFFs in the specified output directory. Pixels outside the ROI and pixels without a complete spatial input patch are encoded as NaN.

Use --tmin-threshold and --tmax-threshold to change the event thresholds.

Citation

If you use this framework in academic work, cite the associated publication 'Multi-modal deep learning for generating high-resolution probabilistic maps of urban heat risk
based on daily extreme air temperatures' by Svea Krikau, Susanne A. Benz and Sina Keller.