Inventory ALS Contract ====================== Purpose ------- This page defines the INV-01 area-based inventory prediction boundary. FEMIC does not fit an ABA model in this layer. It consumes a pinned model card, applies it to one pinned FEMIC LiDAR product bundle, and emits a long ``inventory.als`` table with provenance and model error. The reader accepts the bundle's ``canopy`` table product or an explicit feature CSV (``--features``). ``inventory-features`` derives a CHM grid table from a bundle ``chm`` product; ``inventory-pointcloud-features`` derives first-return metrics from non-overlapping LAS/LAZ tiles and a co-registered DEM. The spatial join is deliberately explicit: the reader does not silently invent fragments. Schemas ------- - Output table: ``femic.inventory.als.v1`` - Model card: ``femic.inventory.als.model.v1`` - Input bundle: ``femic.lidar.product.v1`` / ``femic.lidar.bundle.v1`` Output Table ------------ ``inventory_als.csv`` has these required columns: - ``fragment_id`` - ``attribute`` - ``value`` - ``model_id`` - ``rmse`` The writer also carries ``model_version``, ``unit``, and ``source`` so the long table can be joined without guessing provenance. When ``--features`` is used, the output manifest records the feature-table path and SHA-256. Model Card ---------- A model card is JSON. Coefficients are explicit; FEMIC never estimates them from the bundle being predicted. .. code-block:: json { "schema_version": "femic.inventory.als.model.v1", "model_id": "example-aba-volume", "model_version": "1.0.0", "attribute": "gross_volume_m3_per_ha", "unit": "m3/ha", "link": "log", "output_scale": 16.0, "intercept": -2.7, "coefficients": {"chm_p95_m": 1.4, "canopy_cover_pct": 0.29}, "rmse": 31.4, "sample_count": 120, "training_scope": "BEC and acquisition range you fitted for", "source": "publication or calibration report", "applicability": { "regions": ["BEC zone or training domain"], "species": ["species group"], "notes": "Do not apply outside this domain without a transfer test." }, "predictor_ranges": { "chm_p95_m": [2.0, 45.0], "canopy_cover_pct": [0.0, 100.0] }, "caveats": ["Not validated outside the training range."] } ``link`` is ``identity`` by default or ``log`` for equations of the form ``exp(intercept + sum(coefficient * ln(predictor)))``. ``output_scale`` converts the published plot total to the declared attribute unit; it defaults to ``1.0``. For example, the published boreal Wulder et al. (2012) basal-area and volume equations predict 25 x 25 m plot totals, so their cards use ``output_scale: 16.0`` to report per hectare. Term-based cards ^^^^^^^^^^^^^^^^ A card may instead declare ``model_type: log_terms`` and a list of terms: - ``{"kind": "constant", "coefficient": ...}`` - ``{"kind": "log", "feature": "Lhmean", "coefficient": ...}`` - ``{"kind": "log_square", "feature": "Lhmean", "coefficient": ...}`` - ``{"kind": "log_product", "feature": "Lhmean", "feature2": "CC2m", "coefficient": ...}`` The reader sums the terms and applies ``exp``. ``predictor_ranges`` still refers to the raw predictor columns. This supports nonlinear regional cards without a separate application script. ``predictor_ranges`` is optional but strongly recommended. Predictions outside a declared range are refused rather than silently extrapolated. An ``applicability`` block is metadata only; the reader records a warning that the bundle region was not verified. The fixture model in ``tests/fixtures/lidar/inventory_model.json`` is a synthetic identity model used only to test the contract. It is not an ABA model and must not be used for inventory. Published cards live under ``config/inventory/models/``. The current boreal cards are a transfer benchmark, not a CWH/TSA 23 operational model: - ``als_boreal_lorey_height_2012.json`` - ``als_boreal_basal_area_2012.json`` - ``als_boreal_gross_volume_2012.json`` They use the published equations in Wulder et al. (2012), *Canadian Journal of Remote Sensing* 38(5): 600-618, https://doi.org/10.5589/m12-049. Their applicability domain is boreal Canada; applying them to the CWH TFL 6 pilot is a transfer test. The CHM grid helper is also a proxy for the published first-return metrics, not an exact reconstruction. The local CWH pilot cards are also metadata-complete cards, but they are FEMIC fits rather than published models: - ``als_cwh_lorey_height_2026.json`` - ``als_cwh_basal_area_2026.json`` - ``als_cwh_gross_volume_2026.json`` They use 14 public FAIB PSP plots and LidarBC CHMs, with a 0-2 year offset. They are CWH northern Vancouver Island pilots, not TSA 23 operational models. See ``notes/reports/inv01-cwh-local-model-tfl6.md`` and ``notes/reports/inv01-als-transfer-tfl6.md``. The TSA 23 IDF pilot cards use 14 public FAIB plots, LidarBC 2019/2024 first-return point clouds, and exact FAIB plot support: - ``als_tsa23_idf_lorey_height_2026.json`` - ``als_tsa23_idf_basal_area_2026.json`` - ``als_tsa23_idf_gross_volume_2026.json`` They are still pilot cards: LOOCV only, no spatial holdout, and no P48/P49 validation. See ``notes/reports/inv01-tsa23-idf-pilot.md``. The point-cloud grid helper accepts optional ``grid_origin_x`` and ``grid_origin_y``. Pass the same global UTM origin to every tile when building a multi-tile mosaic; otherwise each DEM supplies its own origin and cell IDs will not align. See :doc:`../../guides/inv01-tsa23-full-run` and ``notes/reports/inv01-tsa23-full-mosaic.md``. Bundle Prerequisite ------------------- The bundle must validate against the LiDAR product-bundle contract. Without ``--features`` it must contain a table product named ``canopy``. With ``--features`` the CSV supplies ``fragment_id`` and the model predictor columns; the bundle still supplies the pinned ``bundle_id`` and ``bundle_version``. The reader uses the manifest's ``relative_path``; it does not discover products or re-run materialization. Plot Validation --------------- The optional validation lane accepts a CSV with: - ``fragment_id`` - ``attribute`` - ``observed`` It writes predicted/observed/residual rows and bias, MAE, and RMSE. The TSA/WS4 P48/P49 plot tables are the intended external validation source; no plot data are bundled here. A validation table with no matching rows is reported as a warning, not treated as a successful validation. Limits ------ - This is a **consumer** of a fitted model, not an ABA fitting implementation. - The fixture canopy table is one row per LiDAR tile, not a real fragment map. - The CHM grid helper is a proxy for first-return point-cloud metrics. - ``inventory-pointcloud-features`` requires the optional ``laspy[lazrs]`` dependency and does not deduplicate overlapping point-cloud tiles. - No reprojection, resampling, or source-product rewrite is implicit. - A model card is only as credible as its documented training scope and error. - No WS4/FHOPS objective, constraint, growth, or solver code is changed. See Also -------- - :doc:`lidar-product-bundle` - :doc:`../../guides/lidar-inventory` - :doc:`../api/femic-lidar-inventory`