2026-10-11T21:12:52Zhttps://www.radar-service.eu/oai/OAIHandler

10.35097/90bz7h2avfuxb8nb2026-10-09T11:03:33Zradar4kit

https://dx.doi.org/10.35097/90bz7h2avfuxb8nb Krikau, Svea Software pipeline for the high-resolution estimation of air temperatures and probabilistic heat hazards in urban regions Karlsruhe Institute of Technology 2026 Geological Science dataset Software info:eu-repo/semantics/openAccess https://creativecommons.org/licenses/by/4.0/legalcode Accurately assessing localized heat hazards requires capturing complex spatial and temporal environmental dynamics. To address this, the proposed architecture employs a two-branch fusion approach: a temporal branch that encodes lagged meteorological sequences (such as ERA5 data) and a spatial convolutional branch that processes local geospatial embedding patches. Rather than outputting single deterministic values, the model utilizes quantile regression to estimate conditional predictive distributions for daily minimum and maximum air temperatures. This probabilistic approach enables the generation of uncertainty-aware temperature maps and allows for the direct derivation of critical heat hazard event probabilities, specifically tropical nights and hot days. The accompanying open-source codebase includes the complete machine learning pipeline and trained models. # 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}^{(q_1)}, \ldots, T_{min}^{(q_Q)}, T_{max}^{(q_1)}, \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: ```bash 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: ```bash 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: ```bash python src/example_application.py \ --device cpu \ --checkpoint output/path/to/model.ckpt \ --target-date 2024-07-15 ``` Use a CUDA device when available: ```bash 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: ```text 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: ```bash python src/example_application.py \ --meteo-file data/example/era5_example_72h.csv \ --device cpu ``` ```bash 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. ```bash 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`. | File | Contents | | --- | --- | | `tmin_quantiles_<date>.tif` | $T_{min}$ quantiles in degrees Celsius; one band per trained quantile level. | | `tmax_quantiles_<date>.tif` | $T_{max}$ quantiles in degrees Celsius; one band per trained quantile level. | | `prob_tropical_night_<date>.tif` | Estimated probability that $T_{min} > 20\,^{\circ}\mathrm{C}$. | | `prob_hot_day_<date>.tif` | Estimated probability that $T_{max} > 30\,^{\circ}\mathrm{C}$. | 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. urban heat hazard deep learning air temperature tropical nights hot day probabilistic mapping https://publikationen.bibliothek.kit.edu/1000196784 application/x-tar