femic.efi.pipeline Module

The femic.efi.pipeline module is the file-level seam between femic.efi.model.v1 and attribute tables. It attaches model-card provenance and an explicit applicability decision to every row of a CSV, Parquet, or Feather table. It does not predict, fit, or change a curve.

Start Here If…

Use this page first if you are trying to:

  • attach an EFI model card to an ALS-derived attribute table;

  • flag or drop rows outside the card’s region/species/age/height domain;

  • write a reproducible annotation summary; or

  • inspect the published cards checked into config/efi/models/.

Typical Usage

from pathlib import Path

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.parquet"),
    summary_path=Path("attributes_annotation_summary.json"),
    domain_policy="flag",
)
print(result.in_domain_count, result.out_of_domain_count)

Key Entry Surfaces

The output table adds:

  • model_card_schema_version;

  • model_id, model_version, model_attribute, model_unit;

  • model_rmse, model_bias, model_licence_id;

  • model_applicability (JSON string);

  • model_in_domain; and

  • model_domain_reasons (JSON list).

Domain Policies

A restricted card dimension is conservative: if the card restricts region, species, age, or height and the table does not provide that column, the row is out of domain.

Published Cards

The two cards under config/efi/models/ are metadata-only published cards:

  • als_loreys_height_cwh_2015.json (CWH, Cw/Hw/Hm)

  • als_site_index_loblolly_seus_2019.json (southeastern USA, Pinus taeda)

They are not linear models and do not carry the authors’ coefficients or forest objects. See EFI Model Card (femic.efi.model.v1) for the citations and limits.

Cross-References

Annotate FEMIC attribute tables with an EFI model card.

This is the file-level seam between femic.efi.model.v1 and the attribute tables produced by an instance or a downstream synthesis workflow. It attaches model provenance and an explicit applicability decision to every row. It does not apply a model prediction or change a curve.

class femic.efi.pipeline.EFIAttributeAnnotationResult(input_path, output_path, summary_path, model_id, model_version, attribute, row_count, rows_written, in_domain_count, out_of_domain_count, domain_policy, columns_added)[source]

Bases: object

Summary of one attribute-table annotation run.

Parameters:
  • input_path (Path)

  • output_path (Path)

  • summary_path (Path | None)

  • model_id (str)

  • model_version (str)

  • attribute (str)

  • row_count (int)

  • rows_written (int)

  • in_domain_count (int)

  • out_of_domain_count (int)

  • domain_policy (str)

  • columns_added (tuple[str, ...])

femic.efi.pipeline.annotate_attribute_table(input_path, card_path, output_path, *, summary_path=None, domain_policy='flag', region_column='region', species_column='species', age_column='age', height_column='height')[source]

Attach an EFI model card and applicability decision to an attribute table.

Parameters:
  • input_path (str | Path) – CSV, Parquet, or Feather attribute table.

  • card_path (str | Path) – femic.efi.model.v1 JSON model card.

  • output_path (str | Path) – Destination table. The suffix selects CSV, Parquet, or Feather.

  • summary_path (str | Path | None) – Optional JSON summary path.

  • domain_policy (str) – flag keeps every row and writes model_in_domain / model_domain_reasons; drop omits out-of-domain rows; require raises on the first out-of-domain row.

  • region_column (str | None) – Row columns used for the applicability check. Set a column to None when the table does not carry that dimension.

  • species_column (str | None) – Row columns used for the applicability check. Set a column to None when the table does not carry that dimension.

  • age_column (str | None) – Row columns used for the applicability check. Set a column to None when the table does not carry that dimension.

  • height_column (str | None) – Row columns used for the applicability check. Set a column to None when the table does not carry that dimension.

Returns:

Paths, row counts, and the model identity.

Return type:

EFIAttributeAnnotationResult

Raises:

EFIApplicationError – If the card, input, output suffix, policy, or domain fails.