brushline.vegetation.state_space
The functional-group profiles, state variables, class and continuous distribution, observation projection, and state-space validator.
Low-vegetation state space and discretization.
The state space is the shared vocabulary for the 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 from one observation to a valid
brushline.state.v1 state. It does not run growth or a treatment transition.
- class brushline.vegetation.state_space.StateVariable(*, name: str, unit: str, minimum: float, maximum: float | None, unknown_rule: str)[source]
Bases:
BaseModelOne continuous state variable.
- Parameters:
name (str) – Variable name.
unit (str) – Unit label.
minimum (float) – Lower bound.
maximum (float or None) – Upper bound, when finite.
unknown_rule (str) – Rule applied when the value is unavailable.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.FunctionalGroupProfile(*, group: str, label: str, height_max_m: Annotated[float, Gt(gt=0)], cover_min_pct: Annotated[float, Ge(ge=0), Le(le=100)], resprouts: bool = False, notes: str = '')[source]
Bases:
BaseModelThe expected state envelope for one functional group.
- Parameters:
group (str) – Functional group.
label (str) – Human label.
height_max_m (float) – Typical maximum height.
cover_min_pct (float) – Minimum woody cover.
resprouts (bool) – Whether the group commonly resprouts after cutting.
notes (str) – Short notes or caveats.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.StateSpaceConfig(*, grass_max_height_m: Annotated[float, Gt(gt=0)] = 0.5, shrub_max_height_m: Annotated[float, Gt(gt=0)] = 4.0, young_tree_max_height_m: Annotated[float, Gt(gt=0)] = 10.0, mature_height_m: Annotated[float, Gt(gt=0)] = 15.0, cover_min_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 20.0, mixed_min_strata: Annotated[int, Ge(ge=2)] = 2, unknown_below_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 10.0, observed_min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 50.0)[source]
Bases:
BaseModelDiscretization and coverage rules.
- Parameters:
grass_max_height_m (float, optional) – Grass/herb height maximum. Defaults to
0.5.shrub_max_height_m (float, optional) – Shrub height maximum. Defaults to
4.young_tree_max_height_m (float, optional) – Young-tree height maximum. Defaults to
10.mature_height_m (float, optional) – Mature-edge height minimum. Defaults to
15.cover_min_pct (float, optional) – Woody cover minimum. Defaults to
20.mixed_min_strata (int, optional) – Number of cover-bearing strata for a mixed class. Defaults to
2.unknown_below_coverage_pct (float, optional) – Coverage below which a state is unknown. Defaults to
10.observed_min_coverage_pct (float, optional) – Coverage needed for an observed state. Defaults to
50.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.StateStratum(*, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], height_m: Annotated[float, Ge(ge=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)])[source]
Bases:
BaseModelOne vegetation stratum in an observation.
- Parameters:
functional_group (str) – Functional group.
height_m (float) – Stratum height.
cover_pct (float) – Stratum cover.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.StateObservation(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], state_year: ~typing.Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], height_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, cover_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, density_per_ha: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, biomass_kg_per_ha: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, age_years: ~typing.Annotated[int | None, ~annotated_types.Ge(ge=0)] = None, coverage_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], height_sd: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, cover_sd: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, density_sd: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, strata: list[~brushline.vegetation.state_space.StateStratum] = <factory>, in_domain: bool = True, domain_reason: str = '', observation_id: str | None = None, source: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], source_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], model_card_id: str | None = None)[source]
Bases:
BaseModelOne segment observation used to project the state space.
- Parameters:
segment_id (str) – Segment id.
state_year (int) – Observation year.
functional_group (str) – Dominant functional group.
height_m (float or None) – Observed height.
cover_pct (float or None) – Observed cover.
density_per_ha (float or None) – Observed density.
biomass_kg_per_ha (float or None) – Observed biomass.
age_years (int or None) – Age since disturbance.
coverage_pct (float) – Observation coverage.
height_sd (float, optional) – Height standard deviation.
cover_sd (float, optional) – Cover standard deviation.
density_sd (float, optional) – Density standard deviation.
strata (list of StateStratum, optional) – Vertical strata.
in_domain (bool, optional) – Whether the observation is in the model domain. Defaults to
True.domain_reason (str, optional) – Reason when out of domain.
observation_id (str or None, optional) – Observation id.
source (str) – Observation source.
source_version (str) – Source version.
model_card_id (str or None, optional) – Optional model card.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.StateDistribution(*, class_probabilities: dict[str, float], height_m: Annotated[float, Ge(ge=0)], height_sd: Annotated[float, Ge(ge=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], cover_sd: Annotated[float, Ge(ge=0)], density_per_ha: Annotated[float | None, Ge(ge=0)] = None, density_sd: Annotated[float, Ge(ge=0)] = 0.0, age_years: Annotated[int | None, Ge(ge=0)] = None, confidence: Annotated[float, Ge(ge=0), Le(le=1)])[source]
Bases:
BaseModelThe class and continuous distribution for one projected state.
- Parameters:
class_probabilities (dict of str to float) – State-class probabilities.
height_m (float) – Mean height.
height_sd (float) – Height standard deviation.
cover_pct (float) – Mean cover.
cover_sd (float) – Cover standard deviation.
density_per_ha (float or None) – Mean density.
density_sd (float) – Density standard deviation.
age_years (int or None) – Mean age.
confidence (float) – Overall confidence.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.state_space.StateProjection(*, schema_version: Literal['brushline.state-space.v1'] = 'brushline.state-space.v1', segment_id: str, state_year: int, state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'], functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], coverage_state: str, distribution: StateDistribution, observation: StateObservation, reason: str)[source]
Bases:
BaseModelOne segment’s projection into the shared state space.
- Parameters:
schema_version ({"brushline.state-space.v1"}) – Projection schema version.
segment_id (str) – Segment id.
state_year (int) – State year.
state_class (str) – Selected state class.
functional_group (str) – Selected functional group.
coverage_state (str) – Observed, partial, missing, or out of domain.
distribution (StateDistribution) – Class and continuous distribution.
observation (StateObservation) – Observation that produced the projection.
reason (str) – Projection reason.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- to_vegetation_state() VegetationState[source]
Project the distribution to the shared state contract.
- Returns:
VegetationState – A valid state for the segment and year.
- brushline.vegetation.state_space.project_state(observation: StateObservation, config: StateSpaceConfig | None = None) StateProjection[source]
Project one observation into the shared state space.
The projection is deterministic. Coverage below the unknown threshold becomes an unknown state; coverage below the observed threshold becomes partial. An out-of-domain observation becomes partial and is flagged. Otherwise the class follows the height/cover/strata rules.
- Parameters:
observation (StateObservation) – Observation to project.
config (StateSpaceConfig, optional) – Discretization rules.
- Returns:
StateProjection – The selected class, group, coverage state, distribution, and reason.
- brushline.vegetation.state_space.validate_state_projection(projection: StateProjection) ContractValidation[source]
Validate a projection and its state-contract conversion.
- Parameters:
projection (StateProjection) – Projection to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.
- brushline.vegetation.state_space.classify_state(height_m: float | None, cover_pct: float | None, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], config: StateSpaceConfig | None = None, strata: list[StateStratum] | None = None) Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'][source]
Classify one height/cover observation deterministically.
- Parameters:
height_m (float or None) – Observed height.
cover_pct (float or None) – Observed cover.
functional_group (str) – Functional group.
config (StateSpaceConfig, optional) – Discretization rules.
strata (list of StateStratum, optional) – Vertical strata for a mixed class.
- Returns:
str – The selected state class, or
unknownwhen the input is incomplete.