Initial vegetation state

The initializer links validated terrain, canopy, field, inventory, and site-index evidence to the brushline.state.v1 contract. It uses field evidence first, a conservative CHM rule second, and an explicit unknown or partial state when the evidence is missing or out of domain.

It does not run the P4 growth or treatment model, fit a site-index model, or claim that a CHM resolves shrub from young-tree species. The first release uses the prototype model card brushline.low-vegetation.prototype.v0; P4 calibration is required before operational use.

Evidence

SegmentEvidence carries:

  • P3.3 CanopySupport and its CHM LidarProductProvenance;

  • optional P3.2 TerrainSupport;

  • field observations with height, cover, density, errors, coverage, confidence, date, source, and optional model card;

  • optional inventory height, cover, vintage, source, and model card;

  • optional reconciled site index and species;

  • climate, disturbance, treatment history, and an optional functional-group hint.

A field observation is used when it meets the configured minimum coverage and confidence. Otherwise the CHM path is used and the report records an open question. A field observation is attached to the state contract as an observation row.

Rules

The first release uses these explicit prototype thresholds:

  • grass_herb: mean height at most 0.5 m and 2 m cover below 20 percent;

  • shrub: mean height at most 4 m and 5 m cover at least 20 percent;

  • young_tree: mean height at most 10 m, 10 m cover at least 20 percent, and species evidence from the tree product or a functional-group hint;

  • mixed: 2 m and 10 m cover both at least 20 percent;

  • mature_edge: maximum height at least 15 m, 10 m cover at least 20 percent, and a non-empty tree product;

  • partial: a CHM or canopy candidate that does not match a rule, lacks species evidence for a young tree, or has partial/out-of-domain coverage;

  • unknown: no usable canopy or field evidence.

A young-tree or mature-edge state without a species hint uses the conifer fallback and raises an open question. A CHM top remains an observation, not a species determination.

Output

initialize_state returns a StateInitializationReport with:

  • the validated StateContract;

  • one StateDecision per segment with source, coverage, class probabilities, model card, observation id, reason, inventory vintage, site index, climate, and disturbance;

  • open questions for unknown/partial states, fallback species, low-quality field evidence, and the prototype model card.

class_probabilities records the selected class and the residual unknown probability. The state contract carries the summary class, continuous height and cover, uncertainty, treatment history, source, source version, model card, and observation id.

from datetime import UTC, datetime
from brushline.state_init import (
    SegmentEvidence,
    StateInitializationConfig,
    initialize_state,
    validate_state_initialization,
)

report = initialize_state(
    [SegmentEvidence(segment_id="s1", canopy=canopy, canopy_source=chm_source)],
    StateInitializationConfig(state_year=2026),
    created_utc=datetime(2026, 11, 14, tzinfo=UTC),
)
assert validate_state_initialization(report).is_valid
contract = report.contract

Named errors

Prefix

Meaning

STATE-TIME

The report time is not timezone-aware.

STATE-ID

Duplicate decision or contract id.

STATE-DECISION

A decision does not match its state, confidence, or group.

STATE-MISSING

A required segment has no state.

STATE-REASON

A decision has no reason (warning).

STATE-OBSERVATION

The contract has no observations (warning).

STATE-PARTIAL, STATE-UNCERTAIN

Existing state-contract warnings for partial or low-confidence states.

Limits

  • The rules are prototype thresholds, not a calibrated P4 model.

  • A CHM cannot separate shrub from young-tree species; species evidence or a partial state is required.

  • Inventory and site index are context only; they do not determine the low-vegetation class.

  • The initializer does not create a treatment plan, a monitoring plan, or an operational recommendation.