brushline.model.state
The vegetation state, treatment action, treatment transition, and observation contract, and the state validator.
Vegetation state, treatment, transition, and observation contract.
The state is a distribution over interpretable classes with continuous summaries, not a point estimate. A treatment is a transition with method-specific efficacy and regrowth, not a reset to zero. An observation is evidence with coverage, error, and provenance. The validator checks the state keys, the ranges, the year windows, the references, and the treatment transitions.
- class brushline.model.state.StateValidation(errors: tuple[str, ...], warnings: tuple[str, ...], counts: dict[str, int])[source]
Bases:
objectThe outcome of validating a state contract.
- Parameters:
errors (tuple of str) – Named errors. An empty tuple means the contract is valid.
warnings (tuple of str) – Non-fatal findings.
counts (dict of str to int) – Object counts.
- property is_valid: bool
Return whether the contract passed every check.
- Returns:
bool –
Truewhen there are no errors.
- class brushline.model.state.Uncertainty(*, height_m_sd: Annotated[float, Ge(ge=0)] = 0.0, cover_pct_sd: Annotated[float, Ge(ge=0)] = 0.0, density_sd: Annotated[float, Ge(ge=0)] = 0.0, confidence: Annotated[float, Ge(ge=0), Le(le=1)] = 1.0)[source]
Bases:
BaseModelThe uncertainty around a vegetation state.
- Parameters:
height_m_sd (float, optional) – Standard deviation of height in metres. Defaults to
0.cover_pct_sd (float, optional) – Standard deviation of cover in percentage points. Defaults to
0.density_sd (float, optional) – Standard deviation of density in stems per hectare. Defaults to
0.confidence (float, optional) – Confidence in the state, from 0 to 1. Defaults to
1.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.state.VegetationState(*, 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'], state_class: ~typing.Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'], height_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], cover_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], 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, uncertainty: ~brushline.model.state.Uncertainty = <factory>, treatment_history: list[str] = <factory>, 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, observation_id: str | None = None)[source]
Bases:
BaseModelOne functional group’s state on one segment in one year.
- Parameters:
segment_id (str) – Segment identifier.
state_year (int) – Year the state describes.
functional_group ({"unknown", "shrub", "deciduous_sprout", "conifer", "grass_herb"}) – Functional group.
unknownis only valid for an unknown state.state_class ({"unknown", "partial", "grass_herb", "shrub", "young_tree", "mixed",) – “mature_edge”} Interpretable summary class.
height_m (float) – Height in metres. Must be non-negative.
cover_pct (float) – Cover in percent, from 0 to 100.
density_per_ha (float or None, optional) – Density in stems per hectare.
biomass_kg_per_ha (float or None, optional) – Biomass in kilograms per hectare.
age_years (int or None, optional) – Age since disturbance in years.
uncertainty (Uncertainty, optional) – Uncertainty around the state.
treatment_history (list of str, optional) – Treatment action ids applied to the segment.
source (str) – Source of the state.
source_version (str) – Source version or vintage.
model_card_id (str or None, optional) – Model card used to derive the state.
observation_id (str or None, optional) – Observation that produced or updated the state.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.state.TreatmentAction(*, action_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], year: Annotated[int, Ge(ge=1900), Le(le=2200)], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], intensity: Annotated[float, Ge(ge=0), Le(le=1)], efficacy: Annotated[float, Ge(ge=0), Le(le=1)], efficacy_sd: Annotated[float, Ge(ge=0)] = 0.0, cost_per_ha: Annotated[float, Ge(ge=0)] = 0.0, fixed_cost: Annotated[float, Ge(ge=0)] = 0.0, currency: Annotated[str, MinLen(min_length=1)] = 'CAD', status: Literal['planned', 'applied', 'cancelled'] = 'planned', treatment_unit_id: str | None = None, notes: str = '')[source]
Bases:
BaseModelA planned, applied, or cancelled treatment on one segment.
- Parameters:
action_id (str) – Stable action identifier.
segment_id (str) – Segment identifier.
year (int) – Treatment year.
season ({"spring", "summer", "fall", "winter", "any"}) – Treatment season.
method ({"manual", "mechanical", "chemical", "mowing", "grazing", "prescribed_fire", "other"}) – Treatment method.
intensity (float) – Intensity from 0 to 1.
efficacy (float) – Expected efficacy from 0 to 1.
efficacy_sd (float, optional) – Standard deviation of efficacy. Defaults to
0.cost_per_ha (float, optional) – Variable cost per hectare. Defaults to
0.fixed_cost (float, optional) – Fixed cost per action. Defaults to
0.currency (str, optional) – Currency code. Defaults to
CAD.status ({"planned", "applied", "cancelled"}, optional) – Action status. Defaults to
planned.treatment_unit_id (str or None, optional) – Owning treatment unit.
notes (str, optional) – Free notes.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.state.TreatmentTransition(*, transition_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], year: Annotated[int, Ge(ge=1900), Le(le=2200)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], before_height_m: Annotated[float, Ge(ge=0)], after_height_m: Annotated[float, Ge(ge=0)], before_cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], after_cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], efficacy: Annotated[float, Ge(ge=0), Le(le=1)], regrowth_delay_years: Annotated[int, Ge(ge=0)], source: Annotated[str, MinLen(min_length=1)], observation_id: str | None = None)[source]
Bases:
BaseModelThe before-and-after state of one treatment transition.
- Parameters:
transition_id (str) – Stable transition identifier.
segment_id (str) – Segment identifier.
year (int) – Transition year.
method ({"manual", "mechanical", "chemical", "mowing", "grazing", "prescribed_fire", "other"}) – Treatment method.
before_height_m (float) – Height before the treatment.
after_height_m (float) – Height after the treatment.
before_cover_pct (float) – Cover before the treatment.
after_cover_pct (float) – Cover after the treatment.
efficacy (float) – Observed or modelled efficacy from 0 to 1.
regrowth_delay_years (int) – Delay before regrowth resumes.
source (str) – Source of the transition evidence.
observation_id (str or None, optional) – Observation that recorded the transition.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.state.Observation(*, observation_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], observed_date: date, sensor: Literal['lidar', 'uav_lidar', 'imagery', 'field', 'inspection', 'other'], product: Annotated[str, MinLen(min_length=1)], coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)], height_m: Annotated[float | None, Ge(ge=0)] = None, cover_pct: Annotated[float | None, Ge(ge=0), Le(le=100)] = None, density_per_ha: Annotated[float | None, Ge(ge=0)] = None, height_error_m: Annotated[float, Ge(ge=0)] = 0.0, cover_error_pct: Annotated[float, Ge(ge=0)] = 0.0, model_card_id: str | None = None, source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)])[source]
Bases:
BaseModelOne remote or field observation of a segment.
- Parameters:
observation_id (str) – Stable observation identifier.
segment_id (str) – Segment identifier.
observed_date (datetime.date) – Observation date.
sensor ({"lidar", "uav_lidar", "imagery", "field", "inspection", "other"}) – Sensor or method.
product (str) – Product name, such as CHM, cover, or field plot.
coverage_pct (float) – Fraction of the segment covered, from 0 to 100.
height_m (float or None, optional) – Observed height in metres.
cover_pct (float or None, optional) – Observed cover in percent.
density_per_ha (float or None, optional) – Observed density in stems per hectare.
height_error_m (float, optional) – Height measurement error in metres. Defaults to
0.cover_error_pct (float, optional) – Cover measurement error in percentage points. Defaults to
0.model_card_id (str or None, optional) – Model card used to derive the observation.
source (str) – Source name.
source_version (str) – Source version or vintage.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.state.StateContract(*, schema_version: ~typing.Literal['brushline.state.v1'] = 'brushline.state.v1', states: ~typing.Annotated[list[~brushline.model.state.VegetationState], ~annotated_types.MinLen(min_length=1)], treatments: list[~brushline.model.state.TreatmentAction] = <factory>, transitions: list[~brushline.model.state.TreatmentTransition] = <factory>, observations: list[~brushline.model.state.Observation] = <factory>)[source]
Bases:
BaseModelThe root state, treatment, transition, and observation contract.
- Parameters:
states (list of VegetationState) – Vegetation states.
treatments (list of TreatmentAction) – Treatment actions.
transitions (list of TreatmentTransition) – Treatment transitions.
observations (list of Observation) – Observations.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.state.validate_state_contract(contract: StateContract, *, required_segment_ids: set[str] | None = None) StateValidation[source]
Validate state keys, references, ranges, and required segment coverage.
- Parameters:
contract (StateContract) – The contract to validate.
required_segment_ids (set of str or None, optional) – Segments that must have at least one state. When
None, the check is skipped.
- Returns:
StateValidation – Errors, warnings, and object counts.