bluegreencity-ki

DWSI Criterion

Overview

The DWSI criterion adds a remote-sensing proxy for canopy water stress based on UrbanGreenEye summer rasters. The rasters store a tree vitality index: the change of the DWSI ((B08 + B03) / (B11 + B04)) relative to a “healthy” expected value (LUP, UrbanGreenEye).

The “healthy” expected value is derived from Sentinel-2 imagery of the fixed reference period 2016–2018. This reference period does not change over time: all yearly products (2018–2025) are mutually comparable (confirmed by LUP, 04.09.2026). Note that the 2018 product partially overlaps the reference period, so its values are biased towards zero.

• Negative values indicate a loss of vitality (drier / more stressed vegetation) and therefore higher drought risk.
• Positive values can result from natural variation or vegetation growth.

The criterion uses this inverse relationship directly in the static score pipeline: lower vitality → higher risk score.

Raster value conventions (int32)

Value	Meaning	Handling
-2147483648	NoData	Handled via the raster’s nodata metadata (→ NaN)
5000	Cloud-masked / invalid area	Masked to NaN by cloud_mask_value (default 5000)
negative	Vitality loss (drought stress)	Valid – contributes to higher risk
positive	Healthy / growing vegetation	Valid – contributes to lower risk

The implementation is year-aware. The active raster source is selected from the criterion-level params.yearly_sources list; the reference year is resolved in this order: params.feature_reference_year → pipeline-context feature_reference_year → project.feature_reference_year / snapshot_year → run date. If no yearly_sources entry matches (or none is configured), the criterion falls back to a single raster key dwsi in inputs — which is not defined, so all trees would score neutral. The inputs.dwsi_rasters.yearly_sources block defines the actual raster files behind each raster_key.

Implementation Details

Location:

• Module: bluegreencity_ki/criteria/dwsi.py
• Tests: tests/test_dwsi.py
• Catalog entry: bluegreencity_ki/criteria/criteria_catalog.py

Processing steps:

1. Resolve the active feature reference year.
2. Select the matching DWSI raster from yearly_sources.
3. Sample raster values at tree locations.
4. Derive thresholds either from static parameters or sample percentiles.
5. Map low DWSI values to high drought-risk scores with an inverse linear transformation.

Scoring logic:

• dwsi <= dwsi_low -> score = 1.0
• dwsi >= dwsi_high -> score = 0.0
• values in between -> inverse linear interpolation
• missing data -> neutral score from project.neutral_score

Recommended default mode:

• threshold_method: sample_percentile
• low_percentile: 5
• high_percentile: 95

This keeps the criterion adaptive to the tree sample of each run while still allowing static fallback thresholds.

Data Sources

• Dataset family: UrbanGreenEye DWSI summer composites
• Storage: yearly raster files configured under inputs.dwsi_rasters.yearly_sources
• Provenance fields:
  • feature_reference_year
  • source_year
  • raster_key

Typical configuration:

inputs:
  dwsi_rasters:
    yearly_sources:
      - start_year: 2024
        end_year: 2024
        source_year: 2024
        raster_key: "dwsi_2024"
        type: "file"
        path: "UrbanGreenEye ILA/UrbanGreenEye_Hannover_ILA/Hannover/UGE_Hannover_Vitalitaet_202406_202408_raw_v3.tif"
      # …one entry per year (live config: 2018–2025)

criteria:
  - name: "dwsi"
    weight: 0.050970
    params:
      threshold_method: "sample_percentile"
      low_percentile: 5
      high_percentile: 95
      dwsi_low: -20.0     # static fallback, percentage scale
      dwsi_high: 20.0     # static fallback, percentage scale
      valid_min: -100.0   # negative values are valid (vitality loss)
      valid_max: 100.0
      cloud_mask_value: 5000  # UrbanGreenEye cloud mask → NaN
      # Required: selects the active raster per reference year
      yearly_sources:
        - start_year: 2024
          end_year: 2024
          raster_key: "dwsi_2024"
          source_year: 2024
        # …one entry per year (live config: 2018–2025)

Outputs

Per-tree outputs:

• dwsi score contribution in the standard [0, 1] range
• dwsi_summer_value in extras
• dwsi_source_year in extras

Metadata includes:

• threshold method and effective thresholds
• selected raster key and source year
• min, max, and mean of valid sampled values
• counts of valid and missing samples

Limitations:

• DWSI is a canopy-condition proxy, not a direct physiological measurement.
• Interpretation depends on raster quality and temporal representativeness of the summer composite.
• If the configured raster for the reference year is missing, the criterion returns neutral scores.