externalMetrics2Vol: Compute tree-level volume outputs from external inventory...

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

Compute tree-level volume outputs from external inventory data

Description

Compute one or more tree-level volume outputs from external inventory data or from a precomputed external metrics table.

Usage

externalMetrics2Vol(x, 
    parametro = c("V"), 
    parameter_table = NULL, 
    method_registry = external_volume_method_registry(), 
    colmap = NULL, selector = c("first", 
        "priority")[1], 
    track_provenance = FALSE, 
    compute_metrics_if_needed = TRUE, 
    design = NULL, var = NULL, 
    metric_var = NULL, 
    levels = NULL, metric_levels = NULL, 
    keep_cols = NULL, 
    metric_keep_cols = NULL, 
    metric_colmap = list(d = c("d", 
        "dbh", "diameter", 
        "diameter_mm"), 
        h = c("h", "height", 
            "height_m")), 
    d_unit = NULL, metric_d_unit = c("mm", 
        "cm")[1], h_unit = NULL, 
    metric_h_unit = c("m", 
        "dm", "cm")[1], 
    volume_colmap = list(d = c("d"), 
        h = c("h"), dnm = c("dnm", 
            "d_nm", "D.n.m."), 
        v = c("v"), species = c("species", 
            "spec", "especie"), 
        region = c("region", 
            "pr"), equation_set = c("equation_set", 
            "eqset", 
            "tariff", 
            "model_set")), 
    ...)

Arguments

x	Input data.frame or object inheriting from "externalMetrics". Standardized columns such as d, h, dnm, or v must have named unit metadata in the "units" attribute of x.
parametro	Requested volume outputs or method names.
parameter_table	Optional data.frame of coefficients or parameter rows used by the selected methods. Rows may be filtered by columns such as parameter, parametro, or method.
method_registry	Named list of method definitions, usually created with external_volume_method_registry() and new_volume_method().
colmap	Optional alias list used to resolve contextual inputs for the volume methods. If NULL, volume_colmap is used.
selector	Rule used when several parameter rows remain after filtering.
track_provenance	If TRUE, append provenance columns and store volume_meta.
compute_metrics_if_needed	If TRUE, derive missing standardized inputs with externalMetrics().
design	Inventory design passed to externalMetrics() when metric derivation is needed.
var	Legacy alias for metric_var.
metric_var	Metric variables requested during automatic derivation.
levels	Legacy alias for metric_levels.
metric_levels	Grouping or identifier columns kept during metric derivation.
keep_cols	Legacy alias for metric_keep_cols.
metric_keep_cols	Extra columns kept during metric derivation.
metric_colmap	Alias list for raw diameter and height columns used by externalMetrics().
d_unit	Legacy alias for metric_d_unit.
metric_d_unit	Unit of raw diameter columns used during metric derivation.
h_unit	Legacy alias for metric_h_unit.
metric_h_unit	Unit of raw height columns used during metric derivation.
volume_colmap	Default alias list used to resolve standardized inputs and contextual columns such as species, region, and equation set.
...	Additional arguments passed only to externalMetrics() when metric derivation is triggered.

Details

Required inputs are inferred from the selected methods in method_registry. When one or more standardized inputs are missing and compute_metrics_if_needed = TRUE, the function calls externalMetrics() to derive them, using design, metric_colmap, units, grouping columns, and retained columns from the corresponding arguments.

Each requested output is evaluated with its method definition. A method can resolve its own parameter rows with get_pars, use embedded parameters in pars, or fall back to parameter_table. Raw outputs are converted to cubic metres with scale_to_m3.

When track_provenance = TRUE, the result stores per-output provenance columns together with a volume_meta attribute describing input units, returned units, required inputs, and method settings.

Value

A data.frame containing the original columns in x plus the requested volume outputs.

The returned object inherits from classes "externalMetrics2Vol" and "metrics2vol". Named unit metadata are stored in attr(out, "units"), and the result may also preserve design_meta and volume_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

x <- data.frame(
    species = c("sp1", "sp2"),
    d = c(120, 260),
    h = c(7.1, 13.2)
)
attr(x, "units") <- c(d = "mm", h = "m")

pars <- data.frame(
    parameter = "V",
    species = c("sp1", "sp2"),
    a = c(0.00002, 0.00003),
    b = c(2.30, 2.10),
    model = c("demo_sp1", "demo_sp2")
)

ext_methods <- external_volume_method_registry(list(
    V = new_volume_method(
        output = "v",
        fun = function(dbh_mm, h_m, pars) {
            dbh_cm <- dbh_mm / 10
            pars$a + pars$b * (dbh_cm^2) * h_m
        },
        raw_unit = "cm3",
        unit = "m3",
        scale_to_m3 = 1 / 1e6,
        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_,
        match_by = "species",
        required_inputs = c("d", "h")
    )
))

out <- externalMetrics2Vol(
    x,
    parametro = "V",
    parameter_table = pars,
    method_registry = ext_methods,
    track_provenance = TRUE
)

out[, c("species", "v", "v_source", "v_status")]

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