nfiMetrics_spatial: Tree-level metrics carrying a spatial sidecar

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

Tree-level metrics carrying a spatial sidecar

Description

Compute tree-level Spanish NFI metrics while preserving plot geometry

This function mirrors the public arguments and calculations of nfiMetrics but adds an optional spatial sidecar. The metric computation itself is delegated to the original nfiMetrics(), so the returned diameter, height, basal-area, trees-per-hectare, dominant-height, dominant-diameter, unit, and design metadata remain consistent with the non-spatial workflow.

Spatial information is prepared before the metric call by invoking readNFI_spatial() with spatial = "attribute" and copied back to the metric output after nfiMetrics() finishes. Thus the geometry column never travels through the tree-metric calculations. If spatial = "sf", the function reconstructs an sf point object only at the end.

Usage

nfiMetrics_spatial(nfi, 
    var = c("d", "h", 
        "ba", "n", "Hd", 
        "Dd"), levels = c("esta", 
        "espe"), design = snfi_design(), 
    domheight_method = "Hd", 
    domheight_registry = dominant_height_method_registry(), 
    ..., spatial = c("attribute", 
        "sf", "none", 
        "inherit"), geometry.dt.nm = NULL, 
    schema = 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"), validate = TRUE, 
    coord.nm = NULL, 
    coord.factor = NULL, 
    huso.method = c("auto", 
        "candidate", 
        "province", "none"), 
    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, 
    na.action = c("keep", 
        "drop", "error"))

Arguments

nfi	character(1), "readNFI", "readNFI_spatial", or "sf" object. Province codes/names and file paths are first read through readNFI_spatial() when spatial output is requested. Objects that already carry attr(x, "nfi_geometry_registry") reuse that sidecar.
var	Same as nfiMetrics(). Metrics to compute: diameter 'd', height 'h', basal area 'ba', trees per hectare 'n', dominant height 'Hd', and dominant diameter 'Dd'.
levels	Same as nfiMetrics(). Column-name patterns used to keep grouping variables in the tree-level output. Spatial reconstruction to sf requires a plot identifier to remain in the output, so the default should usually be kept while developing the spatial chain.
design	Same as nfiMetrics(). Sampling design used to compute expansion factors for 'n', dominant height, and dominant diameter.
domheight_method	Dominant-height method code resolved through domheight_registry when 'Hd' is requested. The default matches nfiMetrics().
domheight_registry	Named dominant-height registry created with dominant_height_method_registry().
...	Additional arguments passed to readNFI_spatial() and then to nfiMetrics(). Typical examples are nfi.nr, dt.nm, dir, file_ext, and timeOut.
spatial	Spatial output mode. "attribute" keeps the ordinary tabular nfiMetrics() output and stores the plot geometry registry in attributes. "sf" reconstructs point geometry at the end. "none" runs the original non-spatial workflow. "inherit" returns "sf" for sf input, "attribute" for objects already carrying a sidecar, and "none" otherwise.
geometry.dt.nm	Optional table name used to build the geometry registry. When NULL, the default of readNFI_spatial() is used, normally the same table requested by dt.nm.
schema	Optional external schema forwarded to readNFI_spatial(). This lets compatible non-standard inventories define spatial metadata in schema$defaults$spatial while keeping the metric calculation unchanged.
coords	Optional coordinate table forwarded to readNFI_spatial() when coordinates are stored outside the main table.
x.col	Optional X/easting/longitude coordinate column for external coordinate tables.
y.col	Optional Y/northing/latitude coordinate column for external coordinate tables.
pr.col	Optional province, region, or stratum column used in spatial joins.
plot.col	Optional plot identifier column used in spatial joins.
crs	Optional CRS for external coordinates, for example an EPSG code such as 25830.
coord.units	Coordinate units recorded in the spatial sidecar when external coordinates are supplied.
geometry.source	Forwarded to readNFI_spatial(). Use "snfi" to force Spanish NFI coordinate discovery and "external" when coordinates come from the main table or a user-supplied coordinate table.
validate	Warn about missing spatial helpers, failed sidecar creation, or failed sf reconstruction. Metric calculations still follow nfiMetrics().
coord.nm	Optional SNFI coordinate table name forwarded to readNFI_spatial().
coord.factor	Optional coordinate multiplier for SNFI coordinate tables. By default IFN2 kilometre coordinates are detected and converted to metres.
huso.method	UTM-zone assignment method forwarded to readNFI_spatial(). "auto" uses direct Huso, then historical huso1/huso2/huso3 + CoorX, then province fallback.
target.crs	Optional common CRS for SNFI geometries. When NULL, mixed ED50 zones are transformed to EPSG:23030.
boundary	logical. If TRUE (default), attach an optional administrative boundary sidecar for plot maps.
boundary.source	Boundary source passed to readNFI_spatial(). "auto" tries GISCO/NUTS before GADM for Spanish province-like inputs.
boundary.object	Optional user-provided sf polygon layer.
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.
infer.huso	Backward-compatible fallback argument forwarded to readNFI_spatial().
na.action	Used only when spatial = "sf". It controls rows that do not match the plot geometry registry during final sf reconstruction.

Details

The default spatial = "attribute" returns a normal

data.frame with the nfiMetrics metadata intact

and an extra attr(x, "nfi_geometry_registry") sidecar.

This is the safest mode for developing

metrics2Vol_spatial() and dendroMetrics_spatial()

because no geometry column is passed through the metric

internals. Use spatial = "sf" only when direct spatial

output is needed at this stage.

Value

A nfiMetrics object. With spatial = "attribute", the result remains tabular and carries a plot-level geometry registry in attr(x, "nfi_geometry_registry") for later *_spatial() functions. With spatial = "sf", the function attempts to return an sf object by joining plot geometries back to the tree-level metric rows. If the metric output no longer contains a plot identifier, the function warns and returns the tabular output with the sidecar instead.

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

	toy <- data.frame(
	    nfi.nr = 4,
	    pr = 28,
	    esta = c("P1", "P1", "P2"),
	    espe = c(21, 21, 25),
	    Dn = c(120, 185, 260),
	    altura = c(7.1, 9.4, 13.2),
	    x = c(-3.70, -3.70, -3.69),
	    y = c(40.40, 40.40, 40.41)
	)
	attr(toy, "nfi.nr") <- 4

	x <- nfiMetrics_spatial(
	    toy,
	    var = c("d", "h", "ba", "n"),
	    levels = c("esta", "espe"),
	    spatial = "attribute",
	    geometry.source = "external",
	    plot.col = "esta",
	    x.col = "x",
	    y.col = "y",
	    crs = 4326,
	    boundary = FALSE
	)

	inherits(x, "nfiMetrics")
	hasNFIgeometry_spatial(x)

	## Spanish NFI: compute metrics and carry geometry as an attribute sidecar.
	## x <- nfiMetrics_spatial(28, nfi.nr = 3, dir = tempdir())
	## inherits(x, "nfiMetrics")
	## hasNFIgeometry_spatial(x)
## reg <- getNFIgeometry_spatial(x)
## reg$geometry
## attr(x, "dominant_height_meta")

## Direct sf output for visual checks.
## xsf <- nfiMetrics_spatial(28, nfi.nr = 3, dir = tempdir(),
##                           spatial = "sf")
## inherits(xsf, "sf")

## Disable spatial behavior and recover the ordinary nfiMetrics workflow.
	## y <- nfiMetrics_spatial(28, nfi.nr = 3, dir = tempdir(),
	##                         spatial = "none")

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