bluegreencity-ki

Heat Tolerance Criterion

Description

This criterion evaluates the heat tolerance of tree species from the Citree enrichment already attached to the tree layer during input loading. The risk assessment is performed on a scale from 0 to 1, where higher values indicate higher risk.

The current implementation reads citree_hitzevertraeglichkeit by default and requires the tolerance mapping to be configured explicitly in config.yaml. Unknown or unmatched species fall back to the project’s neutral score (default 0.5).

Risk Mapping

Heat tolerance is converted into risk values as follows:

Tolerance Level	Risk Value
gut	0.1
mittel	0.4
schwach	0.7
unbekannt	0.5

unbekannt is a fallback outcome for unmatched species names or labels that are not covered by the configured mapping. It is not required as an explicit mapping key.

Configuration

The criterion is configured in the config.yaml file as follows:

- name: "heat_tolerance"
  weight: 0.5  # example; current calibrated weight in config/config.yaml
  params:
    source_column: "citree_hitzevertraeglichkeit"
    mapping:
      gut: 0.1
      mittel: 0.4
      schwach: 0.7

mapping is mandatory. If it is missing, the criterion raises a RuntimeError instead of silently using defaults.

If needed, source_column can be pointed at a different enrichment field. In the normal pipeline this should stay on the Citree enrichment column.

Data Sources

The criterion reads the value from the tree layer after enrichment:

• citree_hitzevertraeglichkeit: Citree heat tolerance attached by the species-profile enrichment in docs/data_maintenance/enrichment.md

This avoids maintaining a second manual species table for the same information.

Example

A tree with the species “Acer platanoides” has a heat tolerance of “mittel”, which corresponds to a risk value of 0.4.

Implementation

The implementation is located in bluegreencity_ki/criteria/heat_tolerance.py.

Main Methods

• load_data(): Legacy helper for direct CSV-based lookups outside the runtime pipeline.
• calculate_risk_score(species_name): Legacy helper for direct species lookups.
• __call__(tree_data): Legacy helper for direct single-tree evaluation.
• compute(ctx): Reads the enriched Citree field from the tree layer and returns raw tolerance labels in the extra output field heat_tolerance_value.

Tests

Tests for this criterion are located in tests/test_heat_tolerance.py.

Test Cases

1. Risk Mapping: Verifies that heat tolerance values are correctly converted into risk values.
2. Call Method: Tests the __call__ method of the heat tolerance criterion.

Integration

This criterion is integrated into the risk assessment process and contributes with its calibrated weight (current: 0.004641, see config/config.yaml) to the overall evaluation.

Notes On Current Behavior

• Tree species are only used for diagnostics and unmatched examples; the actual tolerance value comes from the enriched Citree column.
• If the Citree enrichment is missing or a species remained unmatched during enrichment, the score falls back to the neutral score and the raw value is reported as unknown.
• The result metadata includes match diagnostics such as matched and unmatched species counts.