EFI Model Card (femic.efi.model.v1)

Purpose

This page is the source-of-truth contract for the EFI model card that travels with ALS-derived inventory attributes. It records what the model predicts, what it was trained on, how accurate it is, where it applies, and what licence governs it.

The card complements, rather than replaces, the LiDAR product bundle manifest (femic.lidar.product.v1). The bundle describes the sensor product; the card describes the inventory model.

Quick Contract

  • Card schema: femic.efi.model.v1.

  • File: one JSON model-card object.

  • Target attribute and unit are a canonical pair.

  • Predictors are a non-empty, unique list.

  • Training and validation are nested objects.

  • Applicability is a nested object naming at least one region or species.

  • Validation unit must match the card unit.

  • Training region must be in the applicability regions when those are present.

  • Created timestamp must be ISO-8601 and timezone-aware.

Card Fields

Field

Type

Meaning

schema_version

string

Must be femic.efi.model.v1.

model_id

string

Stable model identifier.

model_version

string

Model artifact version.

attribute

string

Target attribute from the canonical list below.

unit

string

Canonical unit for the attribute.

predictors

array

Non-empty, unique predictor names.

training

object

Training provenance; see below.

validation

object

Validation evidence; see below.

applicability

object

Domain; see below.

licence_id

string

Licence identifier, for example OGL-BC.

created_utc

string

Timezone-aware ISO-8601 creation timestamp.

notes

string or null

Optional free-text note.

Attributes and Units

Attribute

Unit

Meaning

height

m

Height.

volume

m3_ha

Volume per hectare.

basal_area

m2_ha

Basal area per hectare.

density

stems_ha

Stems per hectare.

canopy_cover

fraction

Fractional cover in [0, 1].

species_fraction

fraction

Species fraction in [0, 1].

site_index

m

Site index.

biomass

t_ha

Biomass per hectare.

carbon

tC_ha

Carbon per hectare.

other

free text

A declared non-empty unit for an unlisted attribute.

Training Object

Required: source_id, source_version, region, plot_count. Optional: species (unique list), period, notes.

Validation Object

Required: design, n, rmse, bias, unit. Optional: r2 in [0, 1], notes. n is at least 1; rmse is non-negative. The validation unit must equal the card unit.

Applicability Object

Required: regions and species. At least one of the two must be non-empty. Optional: age_min, age_max, height_min, height_max, notes. Minimums must not exceed maximums.

A restricted dimension is conservative: if the card restricts region, species, age, or height and the query does not provide that dimension, the query is out of domain. This prevents a consumer from silently applying a model without the information needed to establish applicability.

Attaching to Attribute Rows

femic.contracts.efi.annotate_attribute_rows() copies each row and adds:

model_id, model_version, model_attribute, model_unit, model_rmse, model_bias, model_licence_id, model_applicability.

The input rows are not mutated.

Attaching to Attribute Tables

femic.efi.pipeline.annotate_attribute_table() is the file-level seam for CSV, Parquet, and Feather attribute tables. It adds the card metadata plus:

  • model_card_schema_version;

  • model_in_domain; and

  • model_domain_reasons (a JSON list).

The domain_policy is flag (keep every row and flag it), drop (omit out-of-domain rows), or require (raise on the first out-of-domain row). The default region/species/age/height columns are region, species, age, and height; each can be remapped or disabled.

femic efi annotate attributes.csv \
  --card config/efi/models/als_loreys_height_cwh_2015.json \
  --output attributes_annotated.csv \
  --summary attributes_annotation_summary.json \
  --domain-policy flag

Published Cards

Two metadata-only cards are checked in under config/efi/models/:

Card

Attribute

Region

Species

Validation

als_loreys_height_cwh_2015.json

height

CWH, northern Vancouver Island, BC

Cw, Hw, Hm

RMSE 2.88 m; bias 0.05 m; 140 plots

als_site_index_loblolly_seus_2019.json

site index

southeastern USA

Pinus taeda

RMSE 3.8 m; bias -0.28 m; 75 FIA plots

Sources:

Both are CC BY 4.0. The cards are metadata-only because the published models are Random Forests or an ALS-height-plus-Landsat workflow, not the linear form in femic.efi.coefficients.v1. Do not invent linear coefficients to force them through the application engine. The cards are published claims, not local FEMIC validation.

Validation Rules

  • Unknown and missing required fields are errors.

  • schema_version is exact.

  • attribute is a controlled vocabulary; unit must match it.

  • predictors are non-empty and unique.

  • Nested training, validation, and applicability objects are validated.

  • Validation unit must match the card unit.

  • Training region must be in the applicability regions when present.

  • created_utc is ISO-8601 and timezone-aware.

  • A card is not a validation certificate; it makes the claim inspectable.

Example

from pathlib import Path
from femic.contracts.efi import (
    annotate_attribute_rows,
    read_efi_model_card,
    summarize_efi_model_card,
)

card = read_efi_model_card(Path("data/efi/als-height-cwh-v1.json"))
summary = summarize_efi_model_card(card)
rows = annotate_attribute_rows(
    [{"fragment_id": 1001, "height_m": 24.5}], card
)

from femic.efi.pipeline import annotate_attribute_table

result = annotate_attribute_table(
    Path("attributes.csv"),
    Path("config/efi/models/als_loreys_height_cwh_2015.json"),
    Path("attributes_annotated.csv"),
    summary_path=Path("attributes_annotation_summary.json"),
    domain_policy="flag",
)
print(result.in_domain_count, result.out_of_domain_count)

Out of Scope

  • Training or retraining an EFI model.

  • A model registry, database, or serving layer.

  • Rebuilding the LiDAR product bundle or its sensor manifest.

  • A claim of field accuracy beyond the recorded validation.

  • A universal or global model card.

Cross-References