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.

  • EFIModelCard Typed card with canonical to_dict, from_dict, and applies_to.

  • EFITrainingData Training source, region, plot count, species, and period.

  • EFIValidation Validation design, sample size, RMSE, bias, unit, and R-squared.

  • EFIApplicability Regions, 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: object

Applicability 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)

classmethod from_dict(payload)[source]

Validate and construct an applicability domain.

Parameters:

payload (Mapping[str, object])

Return type:

EFIApplicability

to_dict()[source]

Return the canonical dict form.

Return type:

dict[str, object]

class femic.contracts.efi.EFIApplicabilityCheck(in_domain, reasons, model_id, model_version)[source]

Bases: object

Result 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: ValueError

Raised 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: object

One validated femic.efi.model.v1 model 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_domain is false when a restricted dimension is missing from the query or falls outside the domain. reasons explains each failure.

Return type:

EFIApplicabilityCheck

classmethod from_dict(payload)[source]

Validate and construct a model card from a mapping.

Parameters:

payload (Mapping[str, object])

Return type:

EFIModelCard

to_dict()[source]

Return the canonical dict form, including nested objects.

Return type:

dict[str, object]

class femic.contracts.efi.EFITrainingData(source_id, source_version, region, plot_count, species=(), period=None, notes=None)[source]

Bases: object

Training-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)

classmethod from_dict(payload)[source]

Validate and construct training data.

Parameters:

payload (Mapping[str, object])

Return type:

EFITrainingData

to_dict()[source]

Return the canonical dict form.

Return type:

dict[str, object]

class femic.contracts.efi.EFIValidation(design, n, rmse, bias, unit, r2=None, notes=None)[source]

Bases: object

Validation evidence for an EFI model card.

Parameters:
  • design (str)

  • n (int)

  • rmse (float)

  • bias (float)

  • unit (str)

  • r2 (float | None)

  • notes (str | None)

classmethod from_dict(payload)[source]

Validate and construct validation evidence.

Parameters:

payload (Mapping[str, object])

Return type:

EFIValidation

to_dict()[source]

Return the canonical dict form.

Return type:

dict[str, object]

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.v1 model card. Call efi_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, and model_applicability fields.

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.v1 JSON 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) – .json file containing one model card.

Returns:

The validated model card.

Return type:

EFIModelCard

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 .json path.

  • card (EFIModelCard) – Model card to write.

Raises:

EFIContractError – If the suffix is unsupported or the card is invalid.

Return type:

None