brushline.vegetation.calibration
The treatment evidence, pooling and shrinkage, calibrated parameters, leave-one-out checks, and the calibration validator.
Calibration of treatment efficacy, resprouting, and regrowth delay.
The calibration uses treatment observations with before/after height, cover, and density. It shrinks thin evidence toward the P4.3 priors, records intervals and evidence level, and runs deterministic leave-one-out checks. It does not acquire field data or change the plan schema.
- class brushline.vegetation.calibration.CalibratedTreatmentParameters(*, method: ~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], efficacy: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], top_kill: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], resprout_factor: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], regrowth_delay_years: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)], height_efficacy: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], cover_efficacy: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], efficacy_interval: tuple[float, float], resprout_interval: tuple[float, float], delay_min_years: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)], delay_max_years: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)], sample_size: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], effective_sample_size: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], evidence_level: str, pooled: bool, source_ids: list[str] = <factory>, model_card_id: str)[source]
Bases:
BaseModelCalibrated parameters for one method, season, and group.
- Parameters:
method (str) – Method.
season (str) – Season.
functional_group (str) – Functional group.
efficacy (float) – Effective cover reduction fraction.
top_kill (float) – Height-reduction share.
resprout_factor (float) – Density increase share.
regrowth_delay_years (int) – Delay before regrowth.
height_efficacy (float) – Observed height reduction.
cover_efficacy (float) – Observed cover reduction.
efficacy_interval (tuple of float) – Lower and upper efficacy interval.
resprout_interval (tuple of float) – Lower and upper resprout interval.
delay_min_years (int) – Minimum observed delay.
delay_max_years (int) – Maximum observed delay.
sample_size (int) – Number of records.
effective_sample_size (float) – Weighted sample size.
evidence_level (str) –
exact,method_group,method, orprior.pooled (bool) – Whether the evidence was pooled.
source_ids (list of str) – Source observation ids.
model_card_id (str) – Model card id.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- to_treatment_parameters(base: TreatmentParameters) TreatmentParameters[source]
Apply the calibrated values to a base treatment parameter set.
- Parameters:
base (TreatmentParameters) – Method parameters that supply cost and notes.
- Returns:
TreatmentParameters – Calibrated parameters.
- class brushline.vegetation.calibration.CalibrationCheck(*, observation_id: str, method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], observed_efficacy: Annotated[float, Ge(ge=0), Le(le=1)], predicted_efficacy: Annotated[float, Ge(ge=0), Le(le=1)], absolute_error: Annotated[float, Ge(ge=0)], tolerance: Annotated[float, Ge(ge=0), Le(le=1)], passed: bool)[source]
Bases:
BaseModelOne deterministic leave-one-out check.
- Parameters:
observation_id (str) – Held-out observation.
method (str) – Method.
season (str) – Season.
functional_group (str) – Functional group.
observed_efficacy (float) – Observed cover efficacy.
predicted_efficacy (float) – Predicted cover efficacy.
absolute_error (float) – Absolute error.
tolerance (float) – Acceptance tolerance.
passed (bool) – Whether the error is within tolerance.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.calibration.TreatmentCalibrationConfig(*, prior_strength: Annotated[float, Gt(gt=0)] = 4.0, min_observations: Annotated[int, Ge(ge=1)] = 2, holdout_every: Annotated[int, Ge(ge=2)] = 5, holdout_tolerance: Annotated[float, Ge(ge=0), Le(le=1)] = 0.25, confidence_z: Annotated[float, Gt(gt=0)] = 1.96, model_card_id: str = 'brushline.treatment-calibration.v1')[source]
Bases:
BaseModelCalibration pooling, interval, and holdout rules.
- Parameters:
prior_strength (float, optional) – Pseudo-observation weight for the prior. Defaults to
4.min_observations (int, optional) – Minimum records for an exact evidence level. Defaults to
2.holdout_every (int, optional) – Hold out every nth sorted observation. Defaults to
5.holdout_tolerance (float, optional) – Maximum absolute cover-efficacy error. Defaults to
0.25.confidence_z (float, optional) – Interval multiplier. Defaults to
1.96.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.calibration.TreatmentCalibrationError[source]
Bases:
ValueErrorRaised when treatment calibration evidence is inconsistent.
- class brushline.vegetation.calibration.TreatmentCalibrationReport(*, schema_version: ~typing.Literal['brushline.treatment-calibration.v1'] = 'brushline.treatment-calibration.v1', created_utc: ~datetime.datetime, config: ~brushline.vegetation.calibration.TreatmentCalibrationConfig, parameters: ~typing.Annotated[list[~brushline.vegetation.calibration.CalibratedTreatmentParameters], ~annotated_types.MinLen(min_length=1)], holdout_checks: list[~brushline.vegetation.calibration.CalibrationCheck] = <factory>, open_questions: list[str] = <factory>)[source]
Bases:
BaseModelThe calibrated treatment parameters and held-out checks.
- Parameters:
schema_version ({"brushline.treatment-calibration.v1"}) – Report schema version.
created_utc (datetime) – Timezone-aware creation time.
config (TreatmentCalibrationConfig) – Calibration rules.
parameters (list of CalibratedTreatmentParameters) – Calibrated cells.
holdout_checks (list of CalibrationCheck) – Leave-one-out checks.
open_questions (list of str) – Reviewer questions.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.calibration.TreatmentObservation(*, observation_id: Annotated[str, MinLen(min_length=1)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], before_height_m: Annotated[float, Gt(gt=0)], after_height_m: Annotated[float, Ge(ge=0)], before_cover_pct: Annotated[float, Gt(gt=0), Le(le=100)], after_cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], before_density_per_ha: Annotated[float | None, Ge(ge=0)] = None, after_density_per_ha: Annotated[float | None, Ge(ge=0)] = None, regrowth_delay_years: Annotated[int, Ge(ge=0), Le(le=20)], sample_size: Annotated[int, Ge(ge=1)] = 1, observed_date: date | None = None, source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)], notes: str = '')[source]
Bases:
BaseModelOne before/after treatment observation.
- Parameters:
observation_id (str) – Stable observation id.
method (str) – Treatment method.
season (str) – Treatment season.
functional_group (str) – Functional group.
before_height_m (float) – Pre-treatment height.
after_height_m (float) – Post-treatment height.
before_cover_pct (float) – Pre-treatment cover.
after_cover_pct (float) – Post-treatment cover.
before_density_per_ha (float or None) – Pre-treatment density.
after_density_per_ha (float or None) – Post-treatment density.
regrowth_delay_years (int) – Observed delay before regrowth.
sample_size (int, optional) – Independent samples represented by this record. Defaults to
1.observed_date (datetime.date or None) – Observation date.
source (str) – Evidence source.
source_version (str) – Source version.
notes (str) – Caveat.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- property height_efficacy: float
Return the observed height reduction fraction.
- Returns:
float –
1 - after / before, clamped to 0 to 1.
- property cover_efficacy: float
Return the observed cover reduction fraction.
- Returns:
float –
1 - after / before, clamped to 0 to 1.
- property resprout_factor: float | None
Return the observed density increase fraction.
- Returns:
float or None –
after / before - 1when density is present, otherwiseNone.
- brushline.vegetation.calibration.calibrate_treatment(observations: list[TreatmentObservation], config: TreatmentCalibrationConfig | None = None, *, created_utc: datetime | None = None) TreatmentCalibrationReport[source]
Calibrate treatment efficacy, resprouting, and delay.
- Parameters:
observations (list of TreatmentObservation) – Evidence records.
config (TreatmentCalibrationConfig, optional) – Pooling, interval, and holdout rules.
created_utc (datetime, optional) – Report time.
- Returns:
TreatmentCalibrationReport – Calibrated cells and held-out checks.
- Raises:
TreatmentCalibrationError – When the evidence is empty or has duplicate observation ids.
- brushline.vegetation.calibration.validate_treatment_calibration(report: TreatmentCalibrationReport) ContractValidation[source]
Validate calibrated cells, intervals, and held-out checks.
- Parameters:
report (TreatmentCalibrationReport) – Report to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.