femic.efi.application Module
The femic.efi.application module applies a linear EFI model card and
coefficients document to row-wise metrics, checks the applicability domain, and
backtests against observed values.
Use this page when you are applying a published or project EFI model, checking where it applies, or producing a backtest report.
Start Here If…
Use this page first if you are trying to:
apply an EFI model to an attribute table;
verify that a coefficients document matches its model card;
flag or reject rows outside the model’s applicability domain; or
compute bias, RMSE, MAE, and R-squared against observed values.
Typical Usage
from pathlib import Path
from femic.efi.application import (
apply_linear_model,
backtest_linear_model,
load_linear_efi_model,
)
model = load_linear_efi_model(
Path("data/efi/site_index_card.json"),
Path("data/efi/site_index_coefficients.json"),
)
predictions = apply_linear_model(rows, model, out_of_domain="flag")
report = backtest_linear_model(
rows, model, observed_column="observed_site_index"
)
Key Entry Surfaces
load_linear_efi_model()Load and cross-check a model card and its coefficients.LinearEFIModelTyped linear model withpredict.apply_linear_model()Predict, attach provenance, and flag or drop out-of-domain rows.backtest_linear_model()Compute bias, RMSE, MAE, R-squared, and ranges on in-domain rows.
Cross-References
Apply linear EFI attribute models to row-wise metrics.
This module is the execution layer above femic.efi.model.v1. A model card
describes the claim; a coefficients document supplies the linear form; this
module predicts, checks the applicability domain, and backtests against
observed values.
The linear form is intentionally simple. It is a transport for published or project coefficients, not a new statistical method.
- exception femic.efi.application.EFIApplicationError[source]
Bases:
RuntimeErrorRaised when an EFI model cannot be loaded, applied, or backtested.
- class femic.efi.application.LinearEFIModel(card, intercept, coefficients)[source]
Bases:
objectA model card plus a linear predictor.
- Parameters:
card (EFIModelCard)
intercept (float)
coefficients (dict[str, float])
- card
Validated model card that defines the target, predictors, accuracy, and applicability domain.
- Type:
- intercept
Model intercept.
- Type:
float
- coefficients
Predictor coefficients, keyed by the card’s predictor names.
- Type:
dict[str, float]
- predict(metrics)[source]
Predict one value from a mapping of predictor metrics.
- Parameters:
metrics (mapping[str, float]) – Predictor values keyed by the card’s predictor names.
- Returns:
intercept + sum(coefficient * metric).- Return type:
float
- Raises:
EFIApplicationError – If a predictor is missing or non-finite.
- femic.efi.application.apply_linear_model(rows, model, *, predictor_columns=None, require_domain=False, out_of_domain='flag')[source]
Apply a linear model to row-wise metrics.
- Parameters:
rows (sequence[mapping[str, object]]) – Attribute rows. The model’s predictor names are used as column names unless
predictor_columnsmaps them to different columns.model (LinearEFIModel) – Loaded model.
predictor_columns (mapping[str, str] | None, optional) – Predictor name to row-column mapping.
require_domain (bool, optional) – If true, an out-of-domain row raises instead of being flagged.
out_of_domain ({"flag", "drop"}, optional) –
"flag"keeps the row withmodel_in_domainfalse;"drop"omits it.require_domaintakes precedence.
- Returns:
Copies of the input rows with
predicted_<attribute>, model provenance,model_in_domain, andmodel_domain_reasonsfields.- Return type:
list[dict[str, object]]
- Raises:
EFIApplicationError – If a row is not a mapping, a predictor is missing or non-finite, the out-of-domain policy is unknown, or a domain failure is required to raise.
- femic.efi.application.backtest_linear_model(rows, model, *, observed_column, predictor_columns=None)[source]
Backtest a linear model against observed values.
- Parameters:
rows (sequence[mapping[str, object]]) – Attribute rows with predictor columns and an observed target.
model (LinearEFIModel) – Loaded model.
observed_column (str) – Row column holding the observed target in
model.card.unit.predictor_columns (mapping[str, str] | None, optional) – Predictor name to row-column mapping.
- Returns:
Sample size, in/out-of-domain counts, bias, RMSE, MAE, R-squared when defined, and the observed/predicted ranges. Out-of-domain rows are counted but excluded from the metrics.
- Return type:
dict[str, object]
- Raises:
EFIApplicationError – If no in-domain row has an observed value, or an observed value is non-numeric.
- femic.efi.application.load_linear_efi_model(card_path, coefficients_path)[source]
Load and validate a model card and its coefficients.
- Parameters:
card_path (pathlib.Path) –
femic.efi.model.v1JSON card.coefficients_path (pathlib.Path) –
femic.efi.coefficients.v1JSON document.
- Returns:
The validated model.
- Return type:
- Raises:
EFIApplicationError – If the coefficients document is malformed, its identity does not match the card, its predictor set does not match the card, or the card is invalid.