inventoryMetrics_spatial: Complete inventory metrics with optional sf reconstruction...

In basifoR: Retrieval and Processing of the Spanish National Forest Inventory

Complete inventory metrics with optional sf reconstruction Complete inventory workflow carrying a spatial sidecar

Description

Run the complete inventory workflow while preserving optional plot geometry

This function is a conservative spatial companion to inventoryMetrics. It keeps the original calculation engines for Spanish NFI and external inventories, but prepares or reuses a plot-level geometry registry and carries that registry in attributes. The geometry column is reconstructed only at the end when spatial = "sf". The original inventoryMetrics() function is not replaced.

Usage

inventoryMetrics_spatial(nfi, 
    backend = c("auto", 
        "snfi", "external"), 
    summ.vr = "Estadillo", 
    cut.dt = "d == d", 
    report = FALSE, mc.cores = getOption("mc.cores", 
        1L), design = NULL, 
    schema = NULL, method_registry = NULL, 
    domheight_method = "Hd_strict", 
    domheight_registry = dominant_height_method_registry(), 
    parameter_table = NULL, 
    ..., spatial = c("attribute", 
        "sf", "none", 
        "inherit"), spatial.summary = c("auto", 
        "centroid", "none"), 
    keep.geometry.meta = TRUE, 
    geometry.role.name = NULL, 
    geometry.dt.nm = NULL, 
    coord.nm = NULL, 
    coords = NULL, x.col = NULL, 
    y.col = NULL, pr.col = NULL, 
    plot.col = NULL, 
    crs = NULL, coord.units = "m", 
    geometry.source = c("auto", 
        "snfi", "external", 
        "none"), file_ext = NULL, 
    file_name = NULL, 
    coord.factor = NULL, 
    huso.method = c("auto", 
        "candidate", 
        "xgap", "province", 
        "none"), huso.candidates = NULL, 
    target.crs = NULL, 
    boundary = TRUE, 
    boundary.source = c("auto", 
        "gisco", "gadm", 
        "user", "none"), 
    boundary.object = NULL, 
    boundary.level = 2, 
    boundary.path = tools::R_user_dir("basifoR", 
        "cache"), boundary.ext = "json", 
    boundary.version = "4.1", 
    boundary.crs = NULL, 
    infer.huso = NULL, 
    validate = TRUE, 
    na.action = c("keep", 
        "drop", "error"))

Arguments

nfi	Inventory source accepted by the selected backend. For Spanish NFI this can be a province code/name, URL, ZIP file, decompressed files, a readNFI object, a readNFI_spatial object, or an sf object. For external inventories it can be the same input accepted by external_dendroMetrics().
backend	Backend selector. The default infers "external" when schema or parameter_table is supplied, otherwise uses "snfi".
summ.vr	Grouping variable passed to the selected backend. When omitted, Spanish NFI uses "Estadillo" and external inventories use the schema level or detected plot identifier. Supply a vector such as plot and species for finer groups, or NULL for tree-level output.
cut.dt	Logical expression used by the backend to subset the metric output.
report	Request backend reports when supported.
mc.cores	Number of cores passed to the selected backend.
design	Optional sampling design passed to the backend.
schema	Optional external schema. If it contains defaults$spatial, it can also define external coordinates for the spatial sidecar.
method_registry	Optional volume method registry passed to the selected backend.
domheight_method	Dominant-height method passed to dendroMetrics() for SNFI inputs. For external inputs, this method is resolved to a function and passed as domheight_fun.
domheight_registry	Named dominant-height registry created with dominant_height_method_registry().
parameter_table	Optional parameter table for external inventories.
...	Additional arguments forwarded to the selected backend. A safe subset such as nfi.nr, dt.nm, dir, and timeOut is also used by readNFI_spatial() when a sidecar must be prepared from a source.
spatial	Spatial policy. "attribute" returns a tabular result with attr(x, "nfi_geometry_registry"). "sf" returns an sf object when geometry can be restored. "none" runs the original tabular workflow. "inherit" returns sf for sf input, "attribute" for sidecar input, and tabular output otherwise.
spatial.summary	Geometry rule after summarization. "auto" preserves observed plot points when plot identity remains and uses centroids for multi-plot summaries. "centroid" forces centroid construction for multi-plot summaries. "none" leaves the result tabular while preserving the sidecar attribute.
keep.geometry.meta	Store geometry role and spatial-summary metadata as attributes.
geometry.role.name	Optional visible column containing the geometry role, for example "plot_point" or "summary_centroid".
geometry.dt.nm	Optional table name used by readNFI_spatial() to build the sidecar.
coord.nm	Optional coordinate table name for Spanish NFI.
coords	Optional external coordinate table.
x.col	External X/easting/longitude coordinate column.
y.col	External Y/northing/latitude coordinate column.
pr.col	Optional province/region key for coordinate joins.
plot.col	Optional plot identifier key for coordinate joins.
crs	CRS for external coordinates, for example EPSG 25830.
coord.units	Coordinate units recorded in the sidecar.
geometry.source	Geometry source passed to readNFI_spatial().
file_ext	Optional file extension passed to readNFI_spatial().
file_name	Optional file name filter passed to readNFI_spatial().
coord.factor	Optional coordinate multiplier for Spanish NFI tables. IFN2 kilometre coordinates are converted to metres by default in readNFI_spatial().
huso.method	UTM-zone assignment method passed to readNFI_spatial().
huso.candidates	Optional candidate UTM zones passed to readNFI_spatial(), for example c(29, 30) for IFN2 provinces that span Huso 29 and 30 when no Huso columns are available in the coordinate table.
target.crs	Optional common CRS for Spanish NFI geometries.
boundary	logical. If TRUE (default), attach an optional administrative boundary sidecar for plot maps.
boundary.source	Boundary source passed to readNFI_spatial(). For external inventories, "auto" uses only a supplied boundary.object; it does not infer a Spanish built-in boundary. For Spanish inputs, "auto" tries GISCO/NUTS before GADM.
boundary.object	Optional user-provided sf polygon or multipolygon layer. This is the supported boundary route for external inventories.
boundary.level	GADM administrative level, used when boundary.source resolves to "gadm".
boundary.path	Cache directory for optional boundary downloads.
boundary.ext	GADM extension used by gadm_spatial().
boundary.version	GADM version used by gadm_spatial().
boundary.crs	CRS assigned to boundary.object when missing. It is required when the supplied object has no CRS metadata.
infer.huso	Backward-compatible Huso inference argument passed to readNFI_spatial().
validate	Warn about sidecar or geometry-restoration problems.
na.action	Handling of metric rows that do not match the plot geometry registry when spatial = "sf".

Details

External inventories keep their original backend path. When

external coordinates are supplied through an sf input,

coords, or schema$defaults$spatial, the geometry

registry is carried in attributes and may be restored if the

output keeps compatible grouping keys. Without external

coordinate information, external outputs remain tabular.

When summ.vr is omitted for an external inventory, the

function uses schema$levels when available and otherwise

detects the plot identifier from the prepared input.

External boundaries are never inferred from province-like

columns. Supply an sf polygon or multipolygon through

boundary.object; its CRS must be present or supplied

through boundary.crs.

Value

A result equivalent to the selected backend output, augmented

with class "inventoryMetrics_spatial". With

spatial = "attribute", the output is tabular and carries

the plot geometry in attr(x, "nfi_geometry_registry").

With spatial = "sf", the result is an sf object

when geometry restoration succeeds. Preserve explicit summ.vr = NULL; NULL selects tree-level output. Preserve explicit summ.vr = NULL; NULL selects tree-level output.

Author(s)

Wilson Lara [aut, cre] (ORCID: <https://orcid.org/0000-0003-3527-1380>), Cristobal Ordonez [aut] (ORCID: <https://orcid.org/0000-0001-5354-3760>), Aitor Vázquez-Veloso [aut] (ORCID: <https://orcid.org/0000-0003-0227-506X>), Felipe Bravo [aut] (ORCID: <https://orcid.org/0000-0001-7348-6695>)

Examples

	ext <- data.frame(
	    plot = c("P1", "P1", "P2"),
	    species = c("sp1", "sp1", "sp2"),
	    diameter_mm = c(120, 185, 260),
	    height_m = c(7.1, 9.4, 13.2),
	    x = c(-3.70, -3.70, -3.69),
	    y = c(40.40, 40.40, 40.41)
	)

	sch <- new_external_schema(
	    colmap = list(
	        plot = "plot",
	        species = "species",
	        d = "diameter_mm",
	        h = "height_m"
	    ),
	    units = list(d = "mm", h = "m"),
	    levels = "plot",
	    keep_cols = c("plot", "species"),
	    defaults = list(
	        spatial = list(plot = "plot", x = "x", y = "y", crs = 4326)
	    )
	)

	dsg <- new_inventory_design(
	    sample_area_m2 = 1000,
	    min_dbh_cm = 7.5,
	    name = "Square 0.1-ha plot"
	)

	x <- inventoryMetrics_spatial(
	    ext,
	    backend = "external",
	    schema = sch,
	    design = dsg,
	    summ.vr = "plot",
	    var = c("d", "h", "ba", "n"),
	    spatial = "attribute",
	    geometry.source = "external",
	    boundary = FALSE
	)

	inherits(x, "inventoryMetrics")
	hasNFIgeometry_spatial(x)

	## Tabular sidecar output for Spanish NFI:
	## x <- inventoryMetrics_spatial(28, nfi.nr = 2, dir = tempdir())
	## hasNFIgeometry_spatial(x)

## Direct sf output:
## xsf <- inventoryMetrics_spatial(28, nfi.nr = 2, dir = tempdir(), spatial = "sf")
## inherits(xsf, "sf")
## attr(xsf, "geometry_role")

## Dominant-height calculations use the same inspectable registry exposed
## by nfiMetrics(). Metadata is preserved in attr(x, "dominant_height_meta")
## when Hd is computed.
##
	## External inventories keep the original external backend. If the schema
	## contains defaults$spatial or the input is sf, the sidecar can be carried.

basifoR documentation built on Aug. 26, 2026, 9:06 a.m.