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: object

The 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 – True when there are no errors.

to_dict() → dict[str, object][source]

Return a JSON-ready report.

Returns:

dict of str to object – Validity, errors, warnings, and counts.

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: BaseModel

The 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: BaseModel

One 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. unknown is 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: BaseModel

A 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: BaseModel

The 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: BaseModel

One 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: BaseModel

The root state, treatment, transition, and observation contract.

Parameters:
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.