brushline.vegetation.treatment
Method- and season-specific treatment parameters, the immediate top-kill and cover reduction, the resprouting and delay rules, the post-delay growth trajectory, cost hooks, and the treatment validator.
Method-specific low-vegetation treatment transitions.
A treatment is a transition, not a reset to zero. The model records the immediate top-kill and cover reduction, a density change from resprouting, a regrowth delay, and a post-delay trajectory through the P4.2 growth model. The efficacy parameters are priors; P4.4 calibrates them.
- class brushline.vegetation.treatment.TreatmentConfig(*, min_residual_height_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 0.05, min_residual_cover_pct: Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = 1.0, season_factors: dict[str, float]=<factory>, growth_config: GrowthConfig = <factory>, state_space: StateSpaceConfig = <factory>, max_regrowth_years: Annotated[int, ~annotated_types.Ge(ge=0)] = 20, model_card_id: str = 'brushline.low-vegetation.prototype.v0')[source]
Bases:
BaseModelResidual, season, growth, and cost rules.
- Parameters:
min_residual_height_m (float, optional) – Minimum height after treatment. Defaults to
0.05.min_residual_cover_pct (float, optional) – Minimum cover after treatment. Defaults to
1.season_factors (dict of str to float, optional) – Season multipliers.
growth_config (GrowthConfig, optional) – Post-treatment growth rules.
state_space (StateSpaceConfig, optional) – Discretization rules.
max_regrowth_years (int, optional) – Maximum post-treatment trajectory. Defaults to
20.model_card_id (str, optional) – Model card id.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.vegetation.treatment.TreatmentError[source]
Bases:
ValueErrorRaised when a treatment request is internally inconsistent.
- class brushline.vegetation.treatment.TreatmentParameters(*, method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], efficacy: Annotated[float, Ge(ge=0), Le(le=1)], selectivity: Annotated[float, Ge(ge=0), Le(le=1)], top_kill: Annotated[float, Ge(ge=0), Le(le=1)], resprout_factor: Annotated[float, Ge(ge=0), Le(le=1)], regrowth_delay_years: Annotated[int, Ge(ge=0), Le(le=20)], cost_per_ha: Annotated[float, Ge(ge=0)], fixed_cost: Annotated[float, Ge(ge=0)] = 0, currency: str = 'CAD', notes: str = '')[source]
Bases:
BaseModelBase parameters for one treatment method.
- Parameters:
method (str) – Treatment method.
efficacy (float) – Base efficacy.
selectivity (float) – Preserved non-target fraction from 0 to 1.
top_kill (float) – Height-reduction share from 0 to 1.
resprout_factor (float) – Density increase from resprouting from 0 to 1.
regrowth_delay_years (int) – Delay before regrowth.
cost_per_ha (float) – Variable cost per hectare.
fixed_cost (float) – Fixed cost per action.
currency (str) – Currency.
notes (str) – Caveat.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.treatment.TreatmentRequest(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], current: ~brushline.vegetation.state_space.StateDistribution, method: ~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'], intensity: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], quantity_ha: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, regrowth_years: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)] = 0, environment: ~brushline.vegetation.growth.GrowthEnvironment = <factory>)[source]
Bases:
BaseModelOne treatment transition request.
- Parameters:
segment_id (str) – Segment id.
functional_group (str) – Functional group.
current (StateDistribution) – Current distribution.
method (str) – Treatment method.
season (str) – Treatment season.
intensity (float) – Operational intensity from 0 to 1.
quantity_ha (float, optional) – Treated area for cost. Defaults to
1.regrowth_years (int, optional) – Post-treatment trajectory length. Defaults to
0.environment (GrowthEnvironment, optional) – Growth environment after the delay.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.treatment.TreatmentResult(*, schema_version: Literal['brushline.treatment.v1'] = 'brushline.treatment.v1', segment_id: str, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], status: str, previous: StateDistribution, immediate: StateDistribution | None = None, next: StateDistribution | None = None, immediate_state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'] | None = None, next_state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'] | None = None, efficiency: float = 0.0, height_reduction_m: float | None = None, cover_reduction_pct: float | None = None, density_change_per_ha: float | None = None, cost: Annotated[float, Ge(ge=0)] = 0, currency: str = 'CAD', regrowth_delay_years: int = 0, regrowth_years: int = 0, environment: GrowthEnvironment, reason: str = '', model_card_id: str = 'brushline.low-vegetation.prototype.v0')[source]
Bases:
BaseModelThe result of one treatment transition.
- Parameters:
schema_version ({"brushline.treatment.v1"}) – Result schema version.
segment_id (str) – Segment id.
functional_group (str) – Functional group.
method (str) – Method.
season (str) – Season.
status (str) –
applied,out_of_domain, orunknown.previous (StateDistribution) – Pre-treatment distribution.
immediate (StateDistribution or None) – Immediate post-treatment distribution.
next (StateDistribution or None) – Distribution at the end of the requested regrowth horizon.
immediate_state_class (str or None) – Immediate class.
next_state_class (str or None) – Trajectory class.
efficiency (float) – Effective efficacy after season and intensity.
height_reduction_m (float or None) – Immediate height reduction.
cover_reduction_pct (float or None) – Immediate cover reduction.
density_change_per_ha (float or None) – Immediate density change.
cost (float) – Treatment cost.
currency (str) – Cost currency.
regrowth_delay_years (int) – Delay before regrowth.
regrowth_years (int) – Requested trajectory length.
environment (GrowthEnvironment) – Growth environment.
reason (str) – Result reason.
model_card_id (str) – Model card.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- to_vegetation_state(state_year: int) VegetationState[source]
Convert the trajectory distribution to a state contract.
- Parameters:
state_year (int) – Output state year.
- Returns:
VegetationState – The next or immediate state.
- Raises:
TreatmentError – When no post-treatment distribution exists.
- brushline.vegetation.treatment.apply_treatment(request: TreatmentRequest, config: TreatmentConfig | None = None) TreatmentResult[source]
Apply one method-specific treatment transition.
- Parameters:
request (TreatmentRequest) – Current distribution and treatment context.
config (TreatmentConfig, optional) – Residual, season, growth, and cost rules.
- Returns:
TreatmentResult – Immediate and trajectory distributions, cost, and reason.
- Raises:
TreatmentError – When a regrowth horizon exceeds the configured maximum.
- brushline.vegetation.treatment.validate_treatment_result(result: TreatmentResult) ContractValidation[source]
Validate a treatment result and its transition invariants.
- Parameters:
result (TreatmentResult) – Result to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.