femic.contracts.efi Module
The femic.contracts.efi module owns the femic.efi.model.v1 model-card
contract. It records the target, predictors, training data, validation,
applicability domain, and licence for an ALS-derived inventory model.
Use this page when you are producing, reading, validating, or attaching an EFI model card to attribute rows for a FEMIC instance or a Nemora workflow.
Start Here If…
Use this page first if you are trying to:
describe an area-based or tree-level EFI model;
check a card’s unit, accuracy, applicability, or licence before a consumer uses it;
attach model metadata to an ALS-derived attribute table;
decide whether an attribute is inside the model’s applicability domain; or
report which model version and validation produced an attribute.
Typical Usage
from pathlib import Path
from femic.contracts.efi import (
annotate_attribute_rows,
read_efi_model_card,
summarize_efi_model_card,
write_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
)
write_efi_model_card(Path("data/efi/copy.json"), card)
Key Entry Surfaces
validate_efi_model_card()Validate one card and its cross-field rules.EFIModelCardTyped card with canonicalto_dict,from_dict, andapplies_to.EFITrainingDataTraining source, region, plot count, species, and period.EFIValidationValidation design, sample size, RMSE, bias, unit, and R-squared.EFIApplicabilityRegions, species, age and height bounds, and notes.read_efi_model_card()Read and validate one JSON model card.write_efi_model_card()Write one validated model card.summarize_efi_model_card()Return a compact, provenance-bearing summary.annotate_attribute_rows()Attach model metadata to copies of attribute rows.efi_model_schema()Return a defensive copy of the JSON Schema document.
Cross-References
Versioned EFI model-card contract for ALS-derived inventory attributes.
This module owns the femic.efi.model.v1 model card: the metadata that
travels with an area-based or tree-level EFI model. 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 is not a validation certificate and not a model registry. It makes the claim inspectable; it does not make the claim true.
- class femic.contracts.efi.EFIApplicability(regions, species, age_min=None, age_max=None, height_min=None, height_max=None, notes=None)[source]
Bases:
objectApplicability domain for an EFI model card.
- Parameters:
regions (tuple[str, ...])
species (tuple[str, ...])
age_min (int | None)
age_max (int | None)
height_min (float | None)
height_max (float | None)
notes (str | None)
- class femic.contracts.efi.EFIApplicabilityCheck(in_domain, reasons, model_id, model_version)[source]
Bases:
objectResult of checking a query against an applicability domain.
- Parameters:
in_domain (bool)
reasons (tuple[str, ...])
model_id (str)
model_version (str)
- exception femic.contracts.efi.EFIContractError[source]
Bases:
ValueErrorRaised when a model card violates
femic.efi.model.v1.
- class femic.contracts.efi.EFIModelCard(model_id, model_version, attribute, unit, predictors, training, validation, applicability, licence_id, created_utc, notes=None, schema_version='femic.efi.model.v1')[source]
Bases:
objectOne validated
femic.efi.model.v1model card.- Parameters:
model_id (str)
model_version (str)
attribute (str)
unit (str)
predictors (tuple[str, ...])
training (EFITrainingData)
validation (EFIValidation)
applicability (EFIApplicability)
licence_id (str)
created_utc (str)
notes (str | None)
schema_version (str)
- applies_to(*, region=None, species=None, age=None, height=None)[source]
Check a query against the card’s applicability domain.
- Parameters:
region (str | None, optional) – Region or BEC label to test.
species (str | None, optional) – Species label to test.
age (float | None, optional) – Stand age in years.
height (float | None, optional) – Stand or tree height in the card’s unit.
- Returns:
in_domainis false when a restricted dimension is missing from the query or falls outside the domain.reasonsexplains each failure.- Return type:
- class femic.contracts.efi.EFITrainingData(source_id, source_version, region, plot_count, species=(), period=None, notes=None)[source]
Bases:
objectTraining-data provenance for an EFI model card.
- Parameters:
source_id (str)
source_version (str)
region (str)
plot_count (int)
species (tuple[str, ...])
period (str | None)
notes (str | None)
- class femic.contracts.efi.EFIValidation(design, n, rmse, bias, unit, r2=None, notes=None)[source]
Bases:
objectValidation evidence for an EFI model card.
- Parameters:
design (str)
n (int)
rmse (float)
bias (float)
unit (str)
r2 (float | None)
notes (str | None)
- femic.contracts.efi.EFI_ATTRIBUTE_UNITS: dict[str, str] = {'basal_area': 'm2_ha', 'biomass': 't_ha', 'canopy_cover': 'fraction', 'carbon': 'tC_ha', 'density': 'stems_ha', 'height': 'm', 'other': '', 'site_index': 'm', 'species_fraction': 'fraction', 'volume': 'm3_ha'}
Canonical target attributes and their required units.
- femic.contracts.efi.EFI_MODEL_SCHEMA: dict[str, object] = {'$defs': {'applicability': {'additionalProperties': False, 'properties': {'age_max': {'minimum': 0, 'type': ['integer', 'null']}, 'age_min': {'minimum': 0, 'type': ['integer', 'null']}, 'height_max': {'minimum': 0, 'type': ['number', 'null']}, 'height_min': {'minimum': 0, 'type': ['number', 'null']}, 'notes': {'type': ['string', 'null']}, 'regions': {'items': {'minLength': 1, 'type': 'string'}, 'type': 'array', 'uniqueItems': True}, 'species': {'items': {'minLength': 1, 'type': 'string'}, 'type': 'array', 'uniqueItems': True}}, 'required': ['regions', 'species'], 'type': 'object'}, 'training': {'additionalProperties': False, 'properties': {'notes': {'type': ['string', 'null']}, 'period': {'type': ['string', 'null']}, 'plot_count': {'minimum': 0, 'type': 'integer'}, 'region': {'minLength': 1, 'type': 'string'}, 'source_id': {'minLength': 1, 'type': 'string'}, 'source_version': {'minLength': 1, 'type': 'string'}, 'species': {'items': {'minLength': 1, 'type': 'string'}, 'type': 'array', 'uniqueItems': True}}, 'required': ['source_id', 'source_version', 'region', 'plot_count'], 'type': 'object'}, 'validation': {'additionalProperties': False, 'properties': {'bias': {'type': 'number'}, 'design': {'minLength': 1, 'type': 'string'}, 'n': {'minimum': 1, 'type': 'integer'}, 'notes': {'type': ['string', 'null']}, 'r2': {'maximum': 1, 'minimum': 0, 'type': ['number', 'null']}, 'rmse': {'minimum': 0, 'type': 'number'}, 'unit': {'minLength': 1, 'type': 'string'}}, 'required': ['design', 'n', 'rmse', 'bias', 'unit'], 'type': 'object'}}, '$id': 'https://femic.ubc.ca/schemas/efi.model.v1.json', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'additionalProperties': False, 'properties': {'applicability': {'$ref': '#/$defs/applicability'}, 'attribute': {'enum': ['basal_area', 'biomass', 'canopy_cover', 'carbon', 'density', 'height', 'other', 'site_index', 'species_fraction', 'volume'], 'type': 'string'}, 'created_utc': {'format': 'date-time', 'type': 'string'}, 'licence_id': {'minLength': 1, 'type': 'string'}, 'model_id': {'minLength': 1, 'type': 'string'}, 'model_version': {'minLength': 1, 'type': 'string'}, 'notes': {'type': ['string', 'null']}, 'predictors': {'items': {'minLength': 1, 'type': 'string'}, 'minItems': 1, 'type': 'array', 'uniqueItems': True}, 'schema_version': {'const': 'femic.efi.model.v1'}, 'training': {'$ref': '#/$defs/training'}, 'unit': {'type': 'string'}, 'validation': {'$ref': '#/$defs/validation'}}, 'required': ['schema_version', 'model_id', 'model_version', 'attribute', 'unit', 'predictors', 'training', 'validation', 'applicability', 'licence_id', 'created_utc'], 'title': 'FEMIC efi.model.v1 model card', 'type': 'object'}
JSON Schema for one
femic.efi.model.v1model card. Callefi_model_schema()for a defensive copy.
- femic.contracts.efi.annotate_attribute_rows(rows, card)[source]
Attach model metadata to attribute rows.
- Parameters:
rows (sequence[mapping[str, object]]) – Attribute rows to annotate. They are copied, not mutated.
card (EFIModelCard) – Model card to attach.
- Returns:
Copies of the rows with
model_id,model_version,model_attribute,model_unit,model_rmse,model_bias,model_licence_id, andmodel_applicabilityfields.- Return type:
list[dict[str, object]]
- Raises:
EFIContractError – If a row is not a mapping or the card is invalid.
- femic.contracts.efi.efi_model_schema()[source]
Return a defensive copy of the
femic.efi.model.v1JSON Schema.- Returns:
A copy of the schema document, safe for a caller to mutate.
- Return type:
dict[str, object]
- femic.contracts.efi.read_efi_model_card(path)[source]
Read and validate one EFI model card from JSON.
- Parameters:
path (pathlib.Path) –
.jsonfile containing one model card.- Returns:
The validated model card.
- Return type:
- Raises:
EFIContractError – If the suffix is unsupported or the card is invalid.
- femic.contracts.efi.summarize_efi_model_card(card)[source]
Return a compact, provenance-bearing summary of a model card.
- Parameters:
card (EFIModelCard) – Validated model card.
- Returns:
Model identity, target, predictors, training source and region, validation design and accuracy, applicability domain, and licence.
- Return type:
dict[str, object]
- femic.contracts.efi.validate_efi_model_card(payload)[source]
Validate one model card against
femic.efi.model.v1.- Parameters:
payload (mapping[str, object]) – Candidate model card.
- Raises:
EFIContractError – If the card is not a mapping, has unknown or missing fields, carries an unsupported attribute, has a unit that does not match the attribute, has duplicate or empty predictors, has invalid nested metadata, or has a validation unit that does not match the card unit.
- Return type:
None
- femic.contracts.efi.write_efi_model_card(path, card)[source]
Write one validated EFI model card to JSON.
- Parameters:
path (pathlib.Path) – Destination
.jsonpath.card (EFIModelCard) – Model card to write.
- Raises:
EFIContractError – If the suffix is unsupported or the card is invalid.
- Return type:
None