bluegreencity-ki

Cold Air Criterion

Overview

The cold_air criterion evaluates drought risk based on cold air dynamics from the FITNAH 3D climate model (Klimaanalyse Hannover 2022, geo-net). The criterion provides two independent sub-criteria:

• cold_air_kpr: Kaltluftproduktionsrate (cold air production rate, m³/m²/h)
• cold_air_kvs: Kaltluftvolumenstrom (cold air volume flow, m³/m/s)

Higher cold air values indicate better microclimate cooling, meaning lower drought risk for trees (inverse relationship). The main criterion score is a configurable weighted combination of both sub-scores.

Data Source

• Provider: geo-net Umweltconsulting GmbH
• Model: FITNAH 3D climate model
• Study: Klimaanalyse Hannover 2022
• Resolution: 10 m × 10 m
• CRS: EPSG:25832 (UTM zone 32N) — note: CRS is not embedded in the GeoTIFF metadata but coordinates match EPSG:25832
• NoData: -9999

KPR (Kaltluftproduktionsrate)

• File: 2_21_059_ist_kpr_rev00.tif
• Unit: m³/m²/h
• Range: 1.63 – 41.18 (observed in dataset)
• Mean: 19.0
• Description: Rate of cold air production per unit area per hour. Open green spaces and agricultural areas produce the most cold air.

KVS (Kaltluftvolumenstrom)

• File: 2_21_059_ist_kvs_rev00.tif
• Unit: m³/m/s
• Range: 0.0 – 34.15 (observed in dataset)
• Mean: 4.65
• Description: Volume of cold air flowing through a cross-section per second. Ventilation corridors and open terrain channels show the highest flow rates.

Implementation

Location

• Module: bluegreencity_ki/criteria/cold_air.py
• Test: tests/test_cold_air.py

How It Works

1. Raster Sampling (KPR): Samples the KPR raster at each tree location
2. Risk Scoring (KPR): Maps KPR value to risk score using inverse thresholds
3. Raster Sampling (KVS): Samples the KVS raster at each tree location
4. Risk Scoring (KVS): Maps KVS value to risk score using inverse thresholds
5. Combination: Weighted average of KPR and KVS risk scores

Scoring Logic (Inverse)

Value < low_threshold  → Risk Score = 1.0 (high risk - poor cold air supply)
Value = low_threshold  → Risk Score = 1.0
Value in range         → Risk Score = 1.0 - (value - low) / (high - low)
Value = high_threshold → Risk Score = 0.0
Value > high_threshold → Risk Score = 0.0 (low risk - excellent cold air supply, clipped)
Missing data (NoData)  → Risk Score = 0.5 (neutral)

Configuration

Threshold Methods

The criterion supports three threshold methods:

1. Sample Percentile (Recommended)

Calculates thresholds from the distribution of values at actual tree locations. This gives the best differentiation because trees tend to stand on sealed surfaces where cold air values differ significantly from the city-wide raster distribution.

criteria:
  - name: "cold_air"
    weight: 0.028361            # calibrated value; see config/config.yaml
    params:
      threshold_method: "sample_percentile"
      low_percentile: 5          # live config (code default: 25)
      high_percentile: 95        # live config (code default: 75)
      kpr_weight: 0.5
      kvs_weight: 0.5

2. Spatial Percentile

Calculates thresholds from the city-wide raster distribution. Can lead to saturation effects when tree-level values cluster in a narrow range of the raster distribution.

criteria:
  - name: "cold_air"
    weight: 0.5  # example; current calibrated weight in config/config.yaml
    params:
      threshold_method: "spatial_percentile"
      low_percentile: 25
      high_percentile: 75
      kpr_weight: 0.5
      kvs_weight: 0.5

3. Static

Fixed thresholds from domain knowledge:

criteria:
  - name: "cold_air"
    weight: 0.5  # example; current calibrated weight in config/config.yaml
    params:
      threshold_method: "static"
      kpr_low: 5.0
      kpr_high: 30.0
      kvs_low: 1.0
      kvs_high: 10.0
      kpr_weight: 0.5
      kvs_weight: 0.5

Input Configuration

inputs:
  cold_air_kpr_raster:
    type: "file"
    path: "Klimaanalyse Hannover/Grid-Dateien_Klimaanalyse2022/2_21_059_ist_kpr_rev00.tif"

  cold_air_kvs_raster:
    type: "file"
    path: "Klimaanalyse Hannover/Grid-Dateien_Klimaanalyse2022/2_21_059_ist_kvs_rev00.tif"

Paths are relative to project.raster_base_dir.

Outputs

Risk Score

• Column: cold_air_risk (weighted combination of KPR and KVS)
• Range: 0.0 (low risk) to 1.0 (high risk)

Extras (auxiliary output fields)

| Field | Description | |—|—| | m_cold_air_kpr_value | Raw KPR value sampled at tree location (m³/m²/h) | | m_cold_air_kpr_risk | KPR-only risk score (0–1) | | m_cold_air_kvs_value | Raw KVS value sampled at tree location (m³/m/s) | | m_cold_air_kvs_risk | KVS-only risk score (0–1) |

Metadata

• Threshold method, computed thresholds, min/max/mean sampled values, valid/missing sample counts

Relationship to Other Criteria

The cold air criterion complements the existing air_temperature_day / air_temperature_night and land_use criteria, which also originate from the Klimaanalyse Hannover 2022 (FITNAH model):

• air_temperature_day / _night: Direct thermal stress at tree locations (14h/04h)
• land_use: Land use categories affecting drought risk
• cold_air: Cold air dynamics affecting microclimate cooling capacity

Changelog

• 2026-02-25: Initial implementation (GitHub issue #91)
• 2026-02-25: Switched default threshold method from spatial_percentile to sample_percentile for better differentiation at tree locations (mean risk 0.746 → 0.500)