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.

  • LinearEFIModel Typed linear model with predict.

  • 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: RuntimeError

Raised when an EFI model cannot be loaded, applied, or backtested.

class femic.efi.application.LinearEFIModel(card, intercept, coefficients)[source]

Bases: object

A 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:

EFIModelCard

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_columns maps 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 with model_in_domain false; "drop" omits it. require_domain takes precedence.

Returns:

Copies of the input rows with predicted_<attribute>, model provenance, model_in_domain, and model_domain_reasons fields.

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.v1 JSON card.

  • coefficients_path (pathlib.Path) – femic.efi.coefficients.v1 JSON document.

Returns:

The validated model.

Return type:

LinearEFIModel

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.