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 |
|---|---|---|
|
string |
Must be |
|
string |
Stable model identifier. |
|
string |
Model artifact version. |
|
string |
Target attribute from the canonical list below. |
|
string |
Canonical unit for the attribute. |
|
array |
Non-empty, unique predictor names. |
|
object |
Training provenance; see below. |
|
object |
Validation evidence; see below. |
|
object |
Domain; see below. |
|
string |
Licence identifier, for example |
|
string |
Timezone-aware ISO-8601 creation timestamp. |
|
string or null |
Optional free-text note. |
Attributes and Units
Attribute |
Unit |
Meaning |
|---|---|---|
|
|
Height. |
|
|
Volume per hectare. |
|
|
Basal area per hectare. |
|
|
Stems per hectare. |
|
|
Fractional cover in [0, 1]. |
|
|
Species fraction in [0, 1]. |
|
|
Site index. |
|
|
Biomass per hectare. |
|
|
Carbon per hectare. |
|
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; andmodel_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 |
|---|---|---|---|---|
|
height |
CWH, northern Vancouver Island, BC |
Cw, Hw, Hm |
RMSE 2.88 m; bias 0.05 m; 140 plots |
|
site index |
southeastern USA |
Pinus taeda |
RMSE 3.8 m; bias -0.28 m; 75 FIA plots |
Sources:
White et al. (2015), Forests 6:3704, https://doi.org/10.3390/f6103704.
Gopalakrishnan et al. (2019), Forests 10:234, https://doi.org/10.3390/f10030234.
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_versionis exact.attributeis a controlled vocabulary;unitmust match it.predictorsare 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_utcis 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.