bluegreencity-ki

Tree Inventory Status Matrix

Purpose

This document defines the domain-level status taxonomy derived from the historical Hannover tree inventory CSV during runtime import. The goal is to separate true current-tree records from planning placeholders, removed trees, administrative placeholders, and obvious data artefacts.

The matrix is applied in the CSV loader before geometry-based filtering so the project can distinguish between:

• true coordinate problems,
• records that are expected to have no coordinates yet,
• records that are no longer active trees,
• and records that should never enter the current risk analysis.

This document reflects the final filter logic per LHH feedback (issue #208), implemented in bluegreencity_ki/adapters/osgeo_backend/vector.py.

Governing Assumptions

1. The written DBG note is the leading rule for identity handling.
2. A replanting at the same physical location keeps the site continuity, but it creates a new tree identity with a new Blattnummer.
3. The CSV currently exposes Baumnummer, not a dedicated field named Blattnummer. Until the upstream data model is clarified further, the project treats Baumnummer as the best available candidate for a future domain key, while objectid remains the technical pipeline key.
4. Missing coordinates alone are not a sufficient domain status. They must be interpreted together with type, planting, and removal fields.
5. The felling / deletion date is the single source of truth for removal (LHH). The “Bei Fällung …” fields are cumulative and also persist for replacement trees, so they are NOT used as felling signals.

Source Fields Used

The runtime classification derives its status from the following raw columns or their mapped pipeline aliases:

• Baumnummer (prefix “B” / “F” and future domain key candidate)
• Weitere Hauptdaten Baumnummer (Typ)
• Pflanzplanung Pflanzstatus
• Gefällt am (and its forward-filled variant Gefällt am_ff)
• Gelöscht am
• Hochwert / Rechtswert (valid-coordinate check)

Note: Historisch seit and Weitere Hauptdaten Ersatzbaum are no longer used for status derivation (issue #208).

Primary Statuses

Primary status	Detection rule	Keep in trees_raw	Use in trees analysis layer	Notes
active_tree	Default fallback after all exclusion checks	yes	yes	Current tree candidate with valid geometry and no exclusion status
removed_tree	Gefällt am (forward-filled) or Gelöscht am is filled	yes	no	Felling / deletion date is the source of truth (LHH); the site may still be reused later
tree_group_b	Baumnummer starts with “B”	yes	no	Tree-group entries; not evaluable for training or inference (LHH)
planned_tree_f	Baumnummer starts with “F”	yes	no	Planned tree; the F prefix is the authoritative marker, “freier Standort” can be stale
planned_not_planted	Pflanzplanung Pflanzstatus is “b Pflanzung geplant”, “c Baum bestellt” or “d Bestellung in Bearbeitung”	yes	no	Tree ordered but not yet planted; no crown/vitality measurements
erroneous_record	Weitere Hauptdaten Baumnummer (Typ) = “irrtümlich angelegtes datenblatt”	yes	no	Obvious administrative artefact

Supporting Flags

The loader also writes supporting boolean fields that make the reasoning more transparent than a single status string:

• has_valid_coordinates
• is_removed_tree
• is_tree_group_b
• is_planned_tree_f
• is_planned_not_planted
• is_erroneous_record
• inventory_status (the resolved primary status)
• exclude_from_analysis

Status Precedence

Some rows match more than one indicator. The primary status therefore follows a fixed precedence order:

1. removed_tree
2. tree_group_b
3. planned_tree_f
4. planned_not_planted
5. erroneous_record
6. active_tree

The supporting flags remain available even when the primary status is decided by the higher-precedence rule.

Analysis Rule

The runtime import keeps the full CSV snapshot as ctx.vector["trees_raw"]. The actual criteria evaluation works on ctx.vector["trees"], which excludes:

• rows without valid geometry,
• every row whose inventory_status is not active_tree.

Concretely, exclude_from_analysis is true when the row has no valid coordinates or its status is one of the five exclusion statuses. The exclusion list is configured in config/config.yaml under exclude_from_analysis_statuses and must stay in sync with this matrix.

This preserves raw records for QA and reporting while keeping the current risk analysis focused on actual analysable trees.

Examples From The 2025 Snapshot

Example pattern	Expected interpretation
Non-empty Gefällt am (or forward-filled felling date)	removed_tree
Baumnummer starting with “B”	tree_group_b
Baumnummer starting with “F”	planned_tree_f
Pflanzplanung Pflanzstatus = “c Baum bestellt”	planned_not_planted
Weitere Hauptdaten Baumnummer (Typ) = “irrtümlich angelegtes datenblatt”	erroneous_record
freier Standort alone, without F prefix or planning status	active_tree (the type field alone is not a status)

Out Of Scope

This matrix governs the current inventory import and the current-tree risk pipeline. It does not yet change the historical ML joins globally. The future identity transition from technical objectid to a domain key derived from Baumnummer remains a separate design step.