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

Calibrated 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, or prior.

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

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

Calibration 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: ValueError

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

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

One 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 - 1 when density is present, otherwise None.

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