femic.lidar.inventory Module

The femic.lidar.inventory module applies a pinned area-based inventory model card to a FEMIC LiDAR product bundle and writes the long inventory.als table. It is a consumer seam: it does not fit ABA models or invent coefficients.

Key Entry Surfaces

  • InventoryAlsModel Validated model card with coefficients, RMSE, training scope, and ranges.

  • load_inventory_als_model() Load and validate a JSON model card.

  • build_inventory_als() Apply the model to the bundle’s canopy table or an explicit feature CSV and optionally validate against a plot table.

  • build_chm_grid_features() Derive a CHM grid feature table (mean, CV, p95, percent cover) from a bundle chm product.

  • build_pointcloud_grid_features() Derive first-return grid metrics (mean, CV, p95, cover) from LAS/LAZ tiles and a co-registered DEM. Optional grid_origin_x/grid_origin_y make adjacent tiles share a global cell grid.

  • write_inventory_als() Write inventory_als.csv and inventory_als.json.

  • InventoryAlsResult Bundle/model provenance, long rows, warnings, and caveats.

Cross-References

Area-based inventory predictions from a pinned FEMIC LiDAR bundle.

The module is the INV-01 consumer seam, not a new ABA fitting algorithm. It reads a versioned model card, applies that model to a table product in a FEMIC LiDAR product bundle, and writes the long inventory.als table. A model card must identify its coefficients, training scope, and error; FEMIC does not invent them.

The first supported product is the tabular canopy artifact (one row per LiDAR tile). The output is intentionally a fragment table: a real application can substitute fragment polygons and zonal metrics without changing the output contract, but that join is not done here.

class femic.lidar.inventory.InventoryAlsModel(path, model_id, model_version, attribute, unit, intercept, coefficients, rmse, sample_count, training_scope, source, caveats, link='identity', output_scale=1.0, applicability=<factory>, predictor_ranges=<factory>, model_type='linear', terms=(), sha256='', schema_version='femic.inventory.als.model.v1')[source]

Bases: object

A validated, pinned area-based model card.

Parameters:
  • path (Path)

  • model_id (str)

  • model_version (str)

  • attribute (str)

  • unit (str)

  • intercept (float)

  • coefficients (Mapping[str, float])

  • rmse (float)

  • sample_count (int | None)

  • training_scope (str)

  • source (str)

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

  • link (str)

  • output_scale (float)

  • applicability (Mapping[str, object])

  • predictor_ranges (Mapping[str, tuple[float, float]])

  • model_type (str)

  • terms (tuple[InventoryAlsTerm, ...])

  • sha256 (str)

  • schema_version (str)

applicability: Mapping[str, object]
attribute: str
caveats: tuple[str, ...]
coefficients: Mapping[str, float]
property features: tuple[str, ...]

Return the raw predictor names in stable model-card order.

intercept: float
model_id: str
model_type: str = 'linear'
model_version: str
output_scale: float = 1.0
path: Path
predictor_ranges: Mapping[str, tuple[float, float]]
rmse: float
sample_count: int | None
schema_version: str = 'femic.inventory.als.model.v1'
sha256: str = ''
source: str
terms: tuple[InventoryAlsTerm, ...] = ()
to_dict()[source]

Return the model card summary as a JSON-serializable mapping.

Return type:

dict[str, object]

training_scope: str
unit: str
class femic.lidar.inventory.InventoryAlsResult(bundle_dir, manifest_path, bundle_id, bundle_version, model, rows, generated_utc, features_path=None, features_sha256='', validation=None, warnings=(), caveats=('Area-based inventory predictions are model outputs, not field measurements.', "Model transferability and extrapolation are the caller's responsibility.", 'The output table is long: one row per fragment and attribute.', 'No reprojection, resampling, or source-product rewrite is performed.'), schema_version='femic.inventory.als.v1')[source]

Bases: object

The complete inventory.als output contract.

Parameters:
  • bundle_dir (Path)

  • manifest_path (Path)

  • bundle_id (str)

  • bundle_version (str)

  • model (InventoryAlsModel)

  • rows (tuple[InventoryAlsRow, ...])

  • generated_utc (str)

  • features_path (Path | None)

  • features_sha256 (str)

  • validation (InventoryAlsValidation | None)

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

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

  • schema_version (str)

bundle_dir: Path
bundle_id: str
bundle_version: str
caveats: tuple[str, ...] = ('Area-based inventory predictions are model outputs, not field measurements.', "Model transferability and extrapolation are the caller's responsibility.", 'The output table is long: one row per fragment and attribute.', 'No reprojection, resampling, or source-product rewrite is performed.')
features_path: Path | None = None
features_sha256: str = ''
generated_utc: str
manifest_path: Path
model: InventoryAlsModel
rows: tuple[InventoryAlsRow, ...]
schema_version: str = 'femic.inventory.als.v1'
to_dict()[source]

Return the output manifest as a JSON-serializable mapping.

Return type:

dict[str, object]

validation: InventoryAlsValidation | None = None
warnings: tuple[str, ...] = ()
class femic.lidar.inventory.InventoryAlsRow(fragment_id, attribute, value, model_id, rmse, model_version, unit, source)[source]

Bases: object

One predicted inventory attribute for one fragment.

Parameters:
  • fragment_id (str)

  • attribute (str)

  • value (float)

  • model_id (str)

  • rmse (float)

  • model_version (str)

  • unit (str)

  • source (str)

attribute: str
fragment_id: str
model_id: str
model_version: str
rmse: float
source: str
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

unit: str
value: float
class femic.lidar.inventory.InventoryAlsTerm(kind, coefficient, feature=None, feature2=None)[source]

Bases: object

One term in a log-space model card.

Parameters:
  • kind (str)

  • coefficient (float)

  • feature (str | None)

  • feature2 (str | None)

coefficient: float
feature: str | None = None
feature2: str | None = None
kind: str
to_dict()[source]
Return type:

dict[str, object]

class femic.lidar.inventory.InventoryAlsValidation(plots_path, matched_rows, missing_observations, bias, mae, rmse, rows)[source]

Bases: object

Summary of an optional plot/observation comparison.

Parameters:
  • plots_path (Path)

  • matched_rows (int)

  • missing_observations (int)

  • bias (float | None)

  • mae (float | None)

  • rmse (float | None)

  • rows (tuple[InventoryAlsValidationRow, ...])

bias: float | None
mae: float | None
matched_rows: int
missing_observations: int
plots_path: Path
rmse: float | None
rows: tuple[InventoryAlsValidationRow, ...]
to_dict()[source]

Return the validation summary as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.inventory.InventoryAlsValidationRow(fragment_id, attribute, predicted, observed, residual)[source]

Bases: object

One predicted-versus-observed comparison row.

Parameters:
  • fragment_id (str)

  • attribute (str)

  • predicted (float)

  • observed (float)

  • residual (float)

attribute: str
fragment_id: str
observed: float
predicted: float
residual: float
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

exception femic.lidar.inventory.LidarInventoryError[source]

Bases: RuntimeError

Raised when a model card, bundle, or inventory prediction is invalid.

femic.lidar.inventory.build_chm_grid_features(bundle_dir, output_path, *, grid_size_m=25.0, chm_product='chm', min_cover_pct=0.0)[source]

Derive a 25 m grid feature table from a bundle CHM.

Metrics are CHM proxies for the first-return metrics used by many published ABA models: mean height, coefficient of variation, p95, and percent cover above 2 m. Cells with fewer than three above-2 m pixels are omitted. This is a wall-to-wall feature seam, not a point-cloud metric replacement.

Parameters:
  • bundle_dir (Path)

  • output_path (Path)

  • grid_size_m (float)

  • chm_product (str)

  • min_cover_pct (float)

Return type:

dict[str, object]

femic.lidar.inventory.build_inventory_als(bundle_dir, model_path, *, features_path=None, fragment_id_field=None, plots_path=None, generated_utc=None)[source]

Apply a fitted ABA model to one pinned FEMIC LiDAR bundle.

The default source is the bundle’s tabular canopy product. A caller may instead pass features_path, a CSV with fragment_id and the model’s predictor columns; this is the seam for fragment or grid metrics computed from the bundle without pretending that the join happened here.

Parameters:
  • bundle_dir (Path)

  • model_path (Path)

  • features_path (Path | None)

  • fragment_id_field (str | None)

  • plots_path (Path | None)

  • generated_utc (str | None)

Return type:

InventoryAlsResult

femic.lidar.inventory.build_pointcloud_grid_features(pointcloud_paths, dem_path, output_path, *, grid_size_m=25.0, height_threshold_m=2.0, min_returns=10, min_cover_pct=0.0, grid_origin_x=None, grid_origin_y=None, source_tile=None, batch_size=5000000)[source]

Derive first-return point-cloud metrics on a regular grid.

The point clouds and the DEM must share a CRS. The function samples the DEM, normalizes first returns to height above ground, and aggregates by grid cell. It is the point-cloud counterpart to build_chm_grid_features(); it does not fit an ABA model.

The optional laspy[lazrs] dependency is imported lazily because FEMIC does not make point-cloud processing mandatory for every installation.

Parameters:
  • pointcloud_paths (Sequence[Path])

  • dem_path (Path)

  • output_path (Path)

  • grid_size_m (float)

  • height_threshold_m (float)

  • min_returns (int)

  • min_cover_pct (float)

  • grid_origin_x (float | None)

  • grid_origin_y (float | None)

  • source_tile (str | None)

  • batch_size (int)

Return type:

dict[str, object]

femic.lidar.inventory.load_inventory_als_model(path)[source]

Load and validate a fitted ABA model card.

The model card is JSON. Coefficients are explicit; this function never estimates or imputes them. The card must identify its training scope and prediction error.

Parameters:

path (Path)

Return type:

InventoryAlsModel

femic.lidar.inventory.resolve_inventory_model_path(config_path, model_key)[source]

Resolve a model path from an experimental inventory config.

Paths in the config are relative to the instance root when the config lives under config/inventory/. Absolute paths are preserved.

Parameters:
  • config_path (Path)

  • model_key (str)

Return type:

Path

femic.lidar.inventory.write_inventory_als(result, out_dir)[source]

Write the long inventory table and its provenance manifest.

Parameters:
Return type:

dict[str, Path]