Installation & Usage¶
Requirements¶
| Requirement | Version |
|---|---|
| Python | 3.10 |
| Conda (Anaconda or Miniconda) | any recent |
| Git | any recent |
| CLIMADA | 6.1.0 (managed by conda env) |
All heavy Python dependencies are pinned in urban-heat/environment.yml and installed via conda.
1. Clone the repository¶
bash
git clone https://github.com/URBADAPT/URBADAPT-HEAT.git
cd URBADAPT-HEAT
2. Create the conda environment¶
The environment file is at urban-heat/environment.yml. All packages install from the conda-forge channel.
bash
conda env create -f urban-heat/environment.yml
conda activate urbanheat
Key packages installed:
| Package | Version |
|---|---|
| climada | 6.1.0 |
| python | 3.10 |
| numpy | 1.26.4 |
| pandas | 2.1.4 |
| xarray | 2025.6.1 |
| rasterio | 1.4.3 |
| geopandas | 1.1.1 |
| fiona | 1.10.1 |
| pyproj | 3.7.1 |
| rioxarray | latest |
| scikit-learn | latest |
| dask | latest |
| osmnx | latest |
| gdown | ≥5 |
3. Install the cityheat package¶
The cityheat Python package (located at urban-heat/cityheat/) provides helper modules used by all notebooks. Install it in editable mode so notebook imports stay in sync with any local edits:
bash
cd urban-heat
pip install -e .
4. Register the Jupyter kernel¶
Register the urbanheat environment as a named Jupyter kernel so all notebooks can find it:
bash
python -m ipykernel install --user --name urbanheat --display-name "Python (urbanheat)"
5. Launch JupyterLab¶
bash
cd urban-heat
jupyter-lab
Windows shortcut¶
A convenience batch script is provided for Windows users at urban-heat/launch_windows.bat. Edit the PROJECT_DIR variable at the top of the file to match your local path, then double-click to launch. The script will:
1. Activate the base conda installation (Miniconda or Anaconda).
2. Create the urbanheat environment from environment.yml if it does not yet exist.
3. Register the Jupyter kernel on first creation.
4. Launch JupyterLab.
6. Obtain and sync input data¶
Input data are not included in the repository (too large for git). They are stored on Google Drive and synced via city-specific JSON manifests in urban-heat/data_manifests/.
Manifests are provided for 40+ European cities (amsterdam_gdrive.json, athens_gdrive.json, barcelona_gdrive.json, … warsaw_gdrive.json, zagreb_gdrive.json), matching the config files in urban-heat/configs/. Rome, Athens, Lisbon, and Copenhagen are the four cities demonstrated end-to-end; the others are configured and data-linked. The manifest each notebook uses is resolved from the drive_manifest: key of the selected city's YAML.
The framework uses gdown (≥5) to fetch files from Drive. The first notebook in the pipeline (01_setup_0126.ipynb) performs the sync automatically when given a valid manifest path and Drive permissions.
In addition, the DRMKC Risk Data Hub vulnerability data requires a personal JWT token obtained manually:
1. Register at https://drmkc.jrc.ec.europa.eu/risk-data-hub
2. Copy your JWT token.
3. Pass it to scripts/download_drmkc_vulnerability.py:
bash
python scripts/download_drmkc_vulnerability.py --token YOUR_JWT_TOKEN --country IT
UrbClim climate data are fetched from the PROVIDE/VITO API; the API endpoint and city-specific identifiers are configured in each city YAML file.
7. Configure a city¶
Each city is controlled by a YAML file in urban-heat/configs/. Over 40 European cities are already configured. To add a new one, copy an existing config (e.g. rome.yml) and adjust the parameters for your target city. See City Configuration for the full parameter reference.
```bash cp urban-heat/configs/rome.yml urban-heat/configs/mycity.yml
edit mycity.yml¶
```
8. Run the pipeline¶
The pipeline is a numbered series of city-agnostic Jupyter notebooks in urban-heat/notebooks/city_agnostic/March2026_agnostic/template/. Open them in order and run each from top to bottom.
The notebooks are the same for every city — you select the city with one line near the top of NB01:
python
import os
os.environ["CITY"] = "Rome" # rome / athens / lisbon / copenhagen / any configured city
Two further environment variables (already set at the top of NB01) control the output namespace and the impact-function family, and normally need no change:
python
os.environ["URBAN_HEAT_OUTPUT_VARIANT"] = "masselot_main_agnostic" # output folder namespace
os.environ["IF_MAIN_FAMILY"] = "masselot_tail" # main impact-function family
Ready-made per-city copies with CITY pre-set are also provided (Rome/, Athens/, Lisbon/, Copenhagen/) as *_<City>.ipynb, if you prefer not to edit the template.
| Template notebook | Purpose |
|---|---|
01_setup_0126.ipynb |
Select CITY, load config, resolve paths, sync data from Drive, audit inputs |
02_grids_0126.ipynb |
Build daily-T2M hazard files, reference grid + FUA mask, age-stratified exposure, baseline SVI layer |
03_hazard_exposure_0126.ipynb |
Build CLIMADA Hazard + Exposures; construct the projected (time-varying) SVI and exposure_with_vulnerability files |
04_impact_functions_sensitivity.ipynb |
Promote the Masselot city+age-specific impact functions (main); write Burke curves as sensitivity |
05_AC_0126.ipynb |
Downscale AC penetration; model policy scenarios; compute electricity demand and waste-heat feedback |
06_EWS_0126.ipynb |
Model early warning system; compute warning days, avoided deaths, and costs |
07_vegetation_0126_emulator2.ipynb |
Compute GVI → LST → T2M cooling via city emulator; allocate tree-planting policy; compute costs |
08_CBA_0126.ipynb |
25-year discounted CBA; budget-constrained portfolio optimisation; equity stratification |
For uncertainty quantification and summary reporting (thin wrappers around cityheat modules):
| Template notebook | Purpose |
|---|---|
09_uncertainty_0126_improved_fast.ipynb |
Monte Carlo uncertainty propagation; PAWN global sensitivity indices (cityheat.nb09_improved_fast) |
10_summary_0126.ipynb |
Aggregate results, reporting tables, and figures (cityheat.nb10_summary) |
9. Outputs¶
All outputs are written to urban-heat/outputs_variants/<variant>/<city>/ (excluded from git via .gitignore), where <variant> is URBAN_HEAT_OUTPUT_VARIANT (default masselot_main_agnostic). This keeps parallel variants isolated and leaves the legacy outputs/ tree untouched. Typical subfolders are tables/, figures/, and interim .npz/HDF5 assets. Key outputs per stage:
| Stage | Key output files |
|---|---|
| Hazard | Daily-T2M NetCDF fields + CLIMADA Hazard HDF5 |
| Exposure | Age-differentiated CLIMADA Exposures HDF5 (baseline + scenario/year) |
| Vulnerability | vulnerability_<slug>_<year>.npz, vulnerability_<slug>_<scenario>_<year>.npz, exposure_with_vulnerability HDF5 |
| Impact functions | Masselot main IF JSONs (canonical) + Burke sensitivity IF JSONs |
| Adaptation modules | Per-policy avoided-deaths, coverage, electricity, waste-heat, and cost tables |
| CBA | Cost-effectiveness tables, Pareto frontier and figure outputs |
| Uncertainty | Monte Carlo distributions and PAWN sensitivity-index tables under tables/uncertainty_improved_fast/ |
Output manifests (JSON) record every configuration choice alongside each run for full reproducibility.
Troubleshooting¶
Conda env creation fails on Windows: ensure you are running from an Anaconda/Miniconda Prompt with conda in PATH, or use the provided launch_windows.bat.
climada not found: CLIMADA 6.1.0 is on conda-forge; make sure you are not mixing pip and conda installs for this package.
Data sync fails: check that your Google Drive is shared with your account and that gdown can authenticate. For large files, Drive may throttle downloads — retry after a short wait.
cityheat import errors in notebooks: ensure you ran pip install -e . from inside the urban-heat/ directory with the urbanheat kernel active.
This page is maintained in the URBADAPT-HEAT wiki and synced automatically. Edit it there, not in the website repository.