metrics2Vol_spatial: Tree-level volumes carrying a spatial sidecar

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

Tree-level volumes carrying a spatial sidecar

Description

Compute tree-level SNFI volume variables while preserving plot geometry

This function mirrors the public arguments and calculations of metrics2Vol but adds an optional spatial sidecar. The volume computation itself is delegated to the original metrics2Vol(), so the equation registry, fallback logic, provenance, units, and volume metadata remain consistent with the non-spatial workflow.

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

Usage

metrics2Vol_spatial(nfi, 
    cub.met = "freq", 
    parametro = c("VCC"), 
    keep.var = TRUE, 
    keep.legacy = FALSE, 
    method_registry = snfi_volume_method_registry(), 
    track_provenance = FALSE, 
    ..., spatial = c("attribute", 
        "sf", "none", 
        "inherit"), var = c("d", 
        "h", "ba", "n", 
        "Hd", "Dd"), 
    levels = c("esta", 
        "espe"), design = snfi_design(), 
    domheight_method = "Hd", 
    domheight_registry = dominant_height_method_registry(), 
    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	Input accepted by metrics2Vol. This can be a province code/name, a file path, a "readNFI" object, a "readNFI_spatial" object, a "nfiMetrics" object, or an "sf" object carrying plot-level SNFI records.
cub.met	Same as metrics2Vol(). Cubication selector used when several coefficient rows match.
parametro	Same as metrics2Vol(). One or more volume outputs to compute.
keep.var	Same as metrics2Vol(). Keep auxiliary coefficient columns when available.
keep.legacy	Same as metrics2Vol(). Also return the legacy volume estimate for backward compatibility.
method_registry	Same as metrics2Vol(). Registry that maps each requested output to its equation function, output column name, units, and fallback rule.
track_provenance	Same as metrics2Vol(). Add per-row provenance columns and audit metadata.
...	Additional arguments passed to nfiMetrics_spatial() when metrics must be computed before volume calculation. Typical examples are nfi.nr, dt.nm, dir, file_ext, and timeOut.
spatial	Spatial output mode. "attribute" keeps the ordinary tabular metrics2Vol() 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.
var	Forwarded to nfiMetrics_spatial() if the input is not already an "nfiMetrics" object.
levels	Forwarded to nfiMetrics_spatial(). Keeping the plot identifier is important for final sf reconstruction.
design	Forwarded to nfiMetrics_spatial().
domheight_method	Dominant-height method forwarded to nfiMetrics_spatial() or, when metrics are computed inside metrics2Vol(), to nfiMetrics().
domheight_registry	Named dominant-height registry created with dominant_height_method_registry().
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 nfiMetrics_spatial() and readNFI_spatial().
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. Volume calculations still follow metrics2Vol().
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 metrics2vol metadata intact and

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

This is the safest mode for developing

dendroMetrics_spatial() and inventoryMetrics_spatial()

because no geometry column is passed through the volume

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

output is needed at this stage.

Value

A metrics2vol 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 volume rows. If the volume 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", "P2"),
	    especie = c(21, 21),
	    Dn = c(180, 260),
	    altura = c(9.5, 14.2),
	    x = c(-3.70, -3.69),
	    y = c(40.40, 40.41)
	)
	attr(toy, "nfi.nr") <- 4

	demo_registry <- snfi_volume_method_registry(list(
	    VCC = list(
	        output = "vcc_demo",
	        fun = function(dbh_mm, h_m, pars) {
	            pars$k[1] * dbh_mm^2 * h_m
	        },
	        raw_unit = "m3 tree-1",
	        unit = "m3 tree-1",
	        scale_to_m3 = 1,
	        build_args = function(ctx, pars, resolved) {
	            list(dbh_mm = ctx$d_mm, h_m = ctx$h_m, pars = pars)
	        },
	        fallback = function(ctx, pars, resolved) NA_real_,
	        pars = data.frame(
	            nfi.nr = 4,
	            pr = 28,
	            especie = 21,
	            k = 1e-7
	        )
	    )
	))

	x <- metrics2Vol_spatial(
	    toy,
	    parametro = "VCC",
	    method_registry = demo_registry,
	    var = c("d", "h", "ba", "n"),
	    levels = c("esta", "especie"),
	    spatial = "attribute",
	    geometry.source = "external",
	    plot.col = "esta",
	    x.col = "x",
	    y.col = "y",
	    crs = 4326,
	    boundary = FALSE
	)

	inherits(x, "metrics2vol")
	hasNFIgeometry_spatial(x)

	## Spanish NFI: compute tree metrics, volumes, and carry geometry as an
	## attribute sidecar.
	## x <- metrics2Vol_spatial(28, nfi.nr = 3, dir = tempdir(),
	##                          parametro = c("VCC", "VSC"))
	## inherits(x, "metrics2vol")
## hasNFIgeometry_spatial(x)
## attr(x, "units")
## attr(x, "volume_meta")
## attr(x, "dominant_height_meta")

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

## Continue from an existing spatial nfiMetrics object.
## nm <- nfiMetrics_spatial(28, nfi.nr = 3, dir = tempdir())
## vv <- metrics2Vol_spatial(nm, parametro = "VCC")
## hasNFIgeometry_spatial(vv)

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

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