Low-vegetation model card

The model card is the inspectable boundary of the P4 low-vegetation model. It names the predictors, training and validation evidence, error, interval coverage, functional groups, treatment methods, applicability domain, licence, citation, caveats, and decision boundary.

The committed card is notes/reference/low-vegetation-model-card.v1.json.

Card

A LowVegetationModelCard carries:

  • model id, name, version, status, creation time, licence, citation, and description;

  • predictor specs with units, ranges, and required flags;

  • supported functional groups;

  • an ApplicabilityDomain with site-index, climate, lag, coverage, group, and treatment bounds;

  • training and validation evidence with source, version, licence, record count, spatial blocks, period, and provenance;

  • validation metrics and candidate benchmark;

  • an uncertainty contract;

  • caveats and a decision boundary.

The committed card is a prototype. Its evidence is synthetic until a field calibration replaces it.

Domain check

check_domain(card, request) rejects a request when:

  • the functional group is not supported;

  • the treatment method is not supported;

  • site index is outside its range;

  • climate factor is outside its range;

  • prediction lag exceeds the card maximum;

  • observation coverage is below the card minimum.

The check returns DomainCheck with named reasons. require_in_domain raises ModelCardDomainError instead of allowing a silent extrapolation.

from pathlib import Path
from brushline.vegetation.model_card import (
    LowVegetationModelCard,
    ModelCardRequest,
    check_domain,
    require_in_domain,
    validate_model_card,
)

card = LowVegetationModelCard.model_validate_json(
    Path("notes/reference/low-vegetation-model-card.v1.json").read_text()
)
assert validate_model_card(card).is_valid
check = check_domain(
    card,
    ModelCardRequest(
        functional_group="shrub",
        treatment_method="mowing",
        site_index_m=20,
        climate_factor=1.0,
        lag_years=1,
        coverage_pct=100,
    ),
)
assert check.in_domain
require_in_domain(card, check_request)

Uncertainty contract

The card declares a 95 percent interval level and the semantics for height, cover, and density:

  • each prediction is a mean with a standard deviation;

  • the state distribution and intervals enter growth, treatment, and planning;

  • the interval is decision-support evidence, not a guarantee.

The card does not replace the state distribution with a point estimate.

Evidence and benchmark

The card names the training and validation datasets, record counts, spatial blocks, period, licence, and provenance. It includes validation metrics by functional group and variable and candidate benchmark summaries with RMSE differences.

The P4.6 candidate disagreement is recorded in the card. It is not hidden or treated as a model failure by itself.

Named errors

Prefix

Meaning

MODEL-CARD-TIME

Creation time is not timezone-aware.

MODEL-CARD-STATUS

Unknown card status.

MODEL-CARD-LICENCE

Missing licence or citation.

MODEL-CARD-BOUNDARY

Missing decision boundary.

MODEL-CARD-PREDICTOR

Predictor range is not ordered.

MODEL-CARD-GROUP, MODEL-CARD-DOMAIN

Unknown group, or a domain group/method outside the card.

MODEL-CARD-EVIDENCE

Training or validation has no records.

MODEL-CARD-METRIC

Unknown variable, no records, or a group outside the card.

MODEL-CARD-CANDIDATE

Candidate has no records (warning when the benchmark is absent).

MODEL-CARD-INTERVAL

A metric has no interval coverage (warning).

MODEL-CARD-UNCERTAINTY

Missing uncertainty propagation.

MODEL-CARD-CAVEAT

The card has no caveat.

MODEL-CARD-ID

Duplicate predictor, group, metric, or candidate key.

Limits

  • The committed card is a prototype backed by synthetic evidence.

  • A card field is not a guarantee of field accuracy.

  • The domain check is a boundary, not an approval to treat.

  • The card does not replace a field inspection, a qualified reviewer, or the owner’s work-control rules.