externalMetrics: Compute tree-level metrics from external inventory data

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

Compute tree-level metrics from external inventory data

Description

Standardize external tree measurements for external inventory workflows and return requested tree-level metrics in basifoR units.

Usage

externalMetrics(x, var = c("d", 
    "h", "ba", "n", "Hd", 
    "Dd"), levels = NULL, 
    design, colmap = NULL, 
    d_unit = c("mm", 
        "cm")[1], h_unit = c("m", 
        "dm", "cm")[1], 
    keep_cols = NULL, 
    domheight_fun = NULL, 
    domdiameter_fun = NULL, 
    domheight_method = "Hd_strict", 
    domheight_registry = dominant_height_method_registry())

Arguments

x	Input data.frame with one row per tree or stem.
var	Requested metrics to return. Supported values are "d", "h", "ba", "n", "Hd", and "Dd". Requesting "Hd" requires "d", "h", and "n"; requesting "Dd" requires "d" and "n".
levels	Columns defining the groups within which dominant metrics are computed.
design	Inventory design used to compute expansion factors for n.
colmap	Named list of candidate raw column names for diameter and height. Matching is case-insensitive and also accepts numeric suffixes such as diameter_1 or height.2.
d_unit	Unit of raw diameter columns in colmap$d.
h_unit	Unit of raw height columns in colmap$h.
keep_cols	Additional source columns to carry into the result without changing the groups defined by levels.
domheight_fun	Optional function used when "Hd" is requested. If supplied, it overrides domheight_method.
domdiameter_fun	Optional function used when "Dd" is requested together with a custom domheight_fun. It must accept d and n.
domheight_method	Dominant-height method code resolved through domheight_registry when domheight_fun = NULL.
domheight_registry	Named registry created with dominant_height_method_registry.

Details

The function first resolves measurement columns from colmap. Exact matches are preferred, then case-insensitive matches with optional numeric suffixes are considered. When several repeated measurement columns are found for the same variable, row-wise non-missing means are used.

Zero values in resolved diameter or height columns are treated as missing before aggregation. Returned units are standardized to millimetres for d and Dd, metres for h and Hd, square metres per tree for ba, and trees per hectare for n.

When var includes "n", the function uses design to obtain expansion factors. Fixed-area designs call trees_per_ha(), while concentric designs choose the proper factor from the design thresholds. Dominant height and dominant diameter are computed within each resolved group defined only by levels; keep_cols preserves source columns without changing those groups. Both metrics use the diameter ordering, threshold, and fallback convention selected through domheight_registry; Dd uses valid diameter and expansion-factor values and therefore may be available when Hd is missing because heights are unavailable. When both metrics are requested with custom functions, supply both domheight_fun and domdiameter_fun so the pair remains explicit.

Value

A data.frame containing the requested tree-level metrics, optionally preceded by resolved grouping columns.

The returned object inherits from classes "externalMetrics" and "nfiMetrics". Unit metadata are stored in attr(out, "units"). When var includes "n", "Hd", or "Dd", the result also stores sampling design metadata in attr(out, "design_meta").

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

sq_0.1ha <- new_inventory_design(
    sample_area_m2 = 1000,
    min_dbh_cm = 7.5,
    name = "Square 0.1-ha plot",
    metadata = list(shape = "square", side_m = sqrt(1000))
)

x <- 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),
    stringsAsFactors = FALSE
)

externalMetrics(
    x = x,
    var = c("d", "h", "ba", "n"),
    levels = c("plot", "species"),
    design = sq_0.1ha,
    colmap = list(d = "diameter_mm", h = "height_m"),
    d_unit = "mm",
    h_unit = "m"
)

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