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
femic.efi.pipeline.annotate_attribute_table()Read, annotate, domain-check, and write an attribute table.femic.efi.pipeline.EFIAttributeAnnotationResultPaths, model identity, row counts, and domain-policy counts.femic.efi.pipeline.EFI_ATTRIBUTE_TABLE_SCHEMA_VERSIONfemic.efi.attribute_table.v1summary schema.
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; andmodel_domain_reasons(JSON list).
Domain Policies
flagkeeps every row and writes the domain decision.dropomits out-of-domain rows.requireraisesfemic.efi.application.EFIApplicationErroron the first out-of-domain row.
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:
objectSummary 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.v1JSON 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) –
flagkeeps every row and writesmodel_in_domain/model_domain_reasons;dropomits out-of-domain rows;requireraises on the first out-of-domain row.region_column (str | None) – Row columns used for the applicability check. Set a column to
Nonewhen the table does not carry that dimension.species_column (str | None) – Row columns used for the applicability check. Set a column to
Nonewhen the table does not carry that dimension.age_column (str | None) – Row columns used for the applicability check. Set a column to
Nonewhen the table does not carry that dimension.height_column (str | None) – Row columns used for the applicability check. Set a column to
Nonewhen the table does not carry that dimension.
- Returns:
Paths, row counts, and the model identity.
- Return type:
- Raises:
EFIApplicationError – If the card, input, output suffix, policy, or domain fails.