bluegreencity-ki

Seasonal Weather Criterion

Overview

The seasonal_weather criterion attaches per-tree annual DWD-derived weather context to every tree without contributing to the rule-based drought-risk score. It is a neutral feature carrier for the AutoML workflow and provides six seasonal variables for the active feature_reference_year:

• precip_may_oct_mm
• precip_nov_apr_mm
• temp_mean_may_oct_c
• et0_may_oct_mm
• p_et0_ratio_may_oct
• p_et0_ratio_anomaly_may_oct

Since issue #213 (plan block F, 2026-08-30), the values are spatially resolved per tree (nearest 1 km DWD grid cell) instead of a single city-wide value. Because the criterion is configured with weight 0.0, it does not change the static drought-risk result. Its purpose is to make the weather context available per tree in pipeline outputs and downstream ML datasets.

Implementation Details

Location:

• Module: bluegreencity_ki/criteria/seasonal_weather.py
• Tests: tests/test_seasonal_weather.py
• Upstream data preparation: scripts/ml/build_tree_seasonal_weather.py

Processing steps:

1. Resolve the active feature reference year (automatic “last complete year” policy, plan F.3 / decision D16).
2. Load the per-tree seasonal weather CSV.
3. Select the rows for the active year.
4. Look up each tree’s own row by tree_id; trees missing from the CSV keep NaN (no city-wide fallback).
5. Return a neutral criterion score using project.neutral_score.

If the CSV is missing or the target year does not exist in the file, the criterion returns neutral scores and NaN extras.

Data Sources

• Source family: daily DWD HYRAS 1 km (precipitation, mean temperature) and daily DWD FAO-ET0 1 km (reference evapotranspiration, Penman-Monteith)
• Derived file: data/derived/ml/tree_seasonal_weather.csv
• Build script: scripts/ml/build_tree_seasonal_weather.py

The build script resolves the nearest 1 km grid cell for every tree (cKDTree in UTM 32N) and aggregates per tree and year:

• May to October precipitation sum (HYRAS pr)
• Previous November to current April precipitation sum (HYRAS pr)
• May to October mean temperature (HYRAS tas)
• May to October FAO reference evapotranspiration sum (et0, kg m-2 == mm)
• Aridity index P/ET0 for May to October: precip_may_oct_mm / et0_may_oct_mm (decision D15; replaces the older P / (T + 10) formulation). This is the standard aridity index (AI = P/PET, UNCCD), not the De Martonne index.
• P/ET0 anomaly for May to October: p_et0_ratio_may_oct minus the 1991-2020 per-cell climatology (data/derived/ml/p_et0_climatology_1991_2020.parquet, built by scripts/ml/build_p_et0_climatology.py). Negative values mark a drier/hotter season than the long-term mean. NaN when the climatology file is absent.

Only years with a complete May–October season (184 days) are written, so the maximum year in the CSV is the last complete weather year. The script is incremental: re-running it only adds years that are not in the output yet.

Typical configuration:

inputs:
  seasonal_weather:
    path: "data/derived/ml/tree_seasonal_weather.csv"

criteria:
  - name: "seasonal_weather"
    weight: 0.0
    params:
      path: "data/derived/ml/tree_seasonal_weather.csv"

Outputs

Per-tree outputs in extras:

• precip_may_oct_mm
• precip_nov_apr_mm
• temp_mean_may_oct_c
• et0_may_oct_mm
• p_et0_ratio_may_oct
• p_et0_ratio_anomaly_may_oct

Metadata includes:

• feature_reference_year
• CSV path used
• status (ok or no_data)
• mean values across matched trees when available

Important interpretation notes:

• This criterion is intentionally neutral in the static model.
• It exists to expose consistent year-specific weather context for ML training, prediction, diagnostics, and exported datasets.
• The ML feature et0_may_oct_mm (unshaded reference ET0, season sum) is a different quantity from the daily, SVF/shade-corrected ET0 computed in the SWBM. There is no leakage: ML features are past season aggregates, the SWBM state is current and separated in the cascade (stage 2 vs. stage 3).
• The 1 km resolution breaks comparability with the previous 5 km HOFRAS-based city-wide values (this is the point of issue #213).