Treatment calibration
P4.4 calibrates treatment efficacy, top-kill, resprouting, and regrowth delay from before/after observations. It shrinks thin evidence toward the P4.3 priors, records intervals and the evidence level, and runs deterministic leave-one-out checks. It does not acquire field data or change the plan schema.
The committed evidence fixture is notes/reference/treatment-calibration.v1.json.
Evidence
A TreatmentObservation records:
method, season, and functional group;
before/after height and cover;
before/after density, when known;
observed regrowth delay;
sample size, date, source, and source version;
notes.
The derived quantities are:
height_efficacy = 1 - after_height / before_height
cover_efficacy = 1 - after_cover / before_cover
resprout_factor = max(0, after_density / before_density - 1)
The model rejects an after height or cover above the before value. A density pair must be complete.
Pooling and shrinkage
For each method/season/group cell, the evidence level is:
exactwhen there are enough exact records;method_groupwhen the exact cell is thin but the method/group cell is not;methodwhen the method/group cell is also thin;priorwhen no usable records remain.
Pooled and prior cells are flagged. The posterior is:
posterior = (data_mean * effective_n + prior * prior_strength)
/ (effective_n + prior_strength)
The intervals combine the observed weighted spread, sample size, and a normal multiplier. A thin record does not become a precise estimate.
from datetime import UTC, datetime
from pathlib import Path
from brushline.vegetation.calibration import (
TreatmentObservation,
calibrate_treatment,
validate_treatment_calibration,
)
payload = __import__("json").loads(
Path("notes/reference/treatment-calibration.v1.json").read_text()
)
observations = [
TreatmentObservation.model_validate(item) for item in payload["observations"]
]
report = calibrate_treatment(
observations,
created_utc=datetime(2026, 11, 14, tzinfo=UTC),
)
assert validate_treatment_calibration(report).is_valid
Holdout checks
The calibration sorts observations by id and holds out every nth record. It refits on the remaining records, predicts the held-out cover efficacy, and records the absolute error and tolerance. A failed check is an error in the report validator; it is not hidden.
The committed fixture currently performs two leave-one-out checks, both within the default tolerance.
Applying the calibration
CalibratedTreatmentParameters.to_treatment_parameters(base) replaces the base efficacy, top-kill,
resprouting, and delay while preserving the method’s cost and notes. The P4.3 transition model consumes
the calibrated parameters unchanged.
Output
TreatmentCalibrationReport carries:
calibrated cells with method, season, group, efficacy, top-kill, resprout, delay, intervals, sample size, effective sample size, evidence level, source ids, and model card;
leave-one-out checks;
reviewer open questions.
Named errors
Prefix |
Meaning |
|---|---|
|
The report time is not timezone-aware. |
|
Duplicate calibration cell. |
|
Unknown evidence level, a non-prior cell with no samples, or a prior not marked pooled. |
|
A non-prior cell has no source ids. |
|
Effective sample weight is present without samples. |
|
A leave-one-out check exceeds its tolerance. |
|
No held-out checks (warning). |
Limits
The evidence fixture is synthetic; it is not a field calibration.
The priors and posteriors are decision-support evidence, not a guarantee of treatment response.
The model does not simulate chemical mode of action, fire behaviour, grazing preference, or safety permits.
P4.6 validates the growth model; P4.7 publishes the model card and domain.