Low-vegetation state space
The state space is the shared vocabulary for P4 growth, treatment, calibration, hazard, and model-card
work. It defines the functional groups, continuous state variables, state classes, class probabilities,
uncertainty, and the deterministic projection to brushline.state.v1.
It does not run growth or a treatment transition.
Variables and units
Variable |
Unit |
Range |
Unknown rule |
|---|---|---|---|
|
m |
0 to 100 |
unavailable height becomes unknown or partial |
|
% |
0 to 100 |
unavailable cover becomes unknown or partial |
|
stems/ha |
0 or more |
unavailable density stays null |
|
kg/ha |
0 or more |
unavailable biomass stays null |
|
years |
0 to 300 |
unavailable age stays null |
Functional groups
shrub, deciduous_sprout, conifer, grass_herb, and unknown have profiles with a
typical height maximum, a minimum cover, a resprouting flag, and notes. The profiles are priors and
documentation; P4.6 calibrates the parameters.
Discretization
The default StateSpaceConfig uses:
grass/herb at or below 0.5 m and woody cover below 20 percent;
shrub at or below 4 m with cover at least 20 percent;
young tree at or below 10 m with cover at least 20 percent;
mature edge at or above 15 m with cover at least 20 percent;
mixed when at least two observed strata have cover at least 20 percent.
The thresholds must increase. Coverage below 10 percent is unknown; coverage below 50 percent is partial; an out-of-domain observation is partial and flagged.
The projection is deterministic. It does not invent a missing value. An observation that does not match a rule is an observed unknown class with a reason, not a known class.
from brushline.vegetation.state_space import (
StateObservation,
StateSpaceConfig,
project_state,
validate_state_projection,
)
observation = StateObservation(
segment_id="s1",
state_year=2026,
functional_group="shrub",
height_m=2.4,
cover_pct=45,
density_per_ha=1200,
age_years=3,
coverage_pct=92,
height_sd=0.3,
cover_sd=6,
source="field",
source_version="2026",
)
projection = project_state(observation, StateSpaceConfig())
assert validate_state_projection(projection).is_valid
state = projection.to_vegetation_state()
Distribution
StateDistribution carries:
class probabilities that sum to one;
mean and standard deviation for height and cover;
optional density and age;
an overall confidence.
The selected class must have a positive probability. The distribution is the input to the P4 growth and treatment models; the state contract is the summary that a plan reads.
Output states
Observed, partial, and unknown projections all convert to a valid brushline.state.v1 state.
A partial or out-of-domain projection keeps the measured height and cover but marks the state partial.
An unknown projection has zero height and cover, an unknown functional group, and confidence zero.
Named errors
Prefix |
Meaning |
|---|---|
|
An unknown class has a known group, or a known class has an unknown group. |
|
An unknown class has non-zero height or cover. |
|
The selected class has no probability. |
|
The projection cannot convert to a valid state contract. |
|
A partial or out-of-domain projection has no reason. |
Limits
The thresholds are prototype rules, not a calibrated model.
The state space does not include a growth, treatment, hazard, or model-card calculation.
A class probability is a summary of the rules and observation uncertainty, not a fitted posterior.