external_dendroMetrics: Summarize external inventory tree data and optional volume...

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

Summarize external inventory tree data and optional volume outputs

Description

Process external tree data through a unified workflow that standardizes measurements, computes missing dendrometric variables, optionally derives volume outputs, and returns either tree-level records or grouped stand-level summaries. The function can work from already standardized inputs or from raw external tables, and it supports repeated processing of several tables with optional parallel execution.

Usage

external_dendroMetrics(x, 
    summ.vr = NULL, cut.dt = "d == d", 
    report = FALSE, mc.cores = getOption("mc.cores", 
        1L), var = c("d", 
        "h", "ba", "n", 
        "Hd", "Dd"), 
    parametro = NULL, 
    design = NULL, parameter_table = NULL, 
    method_registry = external_volume_method_registry(), 
    levels = NULL, metric_levels = NULL, 
    keep_cols = NULL, 
    metric_keep_cols = NULL, 
    colmap = 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], 
    tree_d_unit_out = NULL, 
    tree_h_unit_out = NULL, 
    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")), 
    selector = c("first", 
        "priority")[1], 
    track_provenance = FALSE, 
    compute_metrics_if_needed = TRUE, 
    schema = NULL, domheight_fun = NULL, 
    domdiameter_fun = NULL, 
    domheight_method = "Hd_strict", 
    domheight_registry = dominant_height_method_registry(), 
    ...)

Arguments

x	External input table, processed table, or list of such objects. Raw inputs must contain enough columns to resolve the requested metrics and, if needed, the volume selectors.
summ.vr	Grouping variable or character vector of grouping variables. Leave NULL to keep tree-level output; supply one or more column names to obtain grouped summaries.
cut.dt	Character filter evaluated on the final table. The expression is evaluated after metrics or summaries have been computed. Use n_tot for grouped stand density.
report	Whether to write the returned table to ‘report.csv’. The file is written in the working directory only when report = TRUE.
mc.cores	Number of worker processes used when x is a list. Values smaller than 1 are reset to 1.
var	Requested variables. Typical metric requests are "d", "h", "ba", "n", "Hd", and "Dd"; volume-like names can also trigger volume processing.
parametro	Optional volume-method codes, for example "V". If NULL, the function tries to infer required methods from var and method_registry.
design	Inventory design used when missing metrics must be computed. Supply an object inheriting from "inventory_design" when the function must derive metrics such as n from raw external data.
parameter_table	Optional parameter table for the volume stage. Passed to externalMetrics2Vol() for method-specific coefficients or selection metadata.
method_registry	Volume method registry. Usually created by external_volume_method_registry() or a custom registry following the same structure.
levels	Grouping variables forwarded to schema resolution. When schema is not used, these serve as defaults for workflow grouping metadata.
metric_levels	Grouping variables used during internal metric computation. These are forwarded specifically to externalMetrics() when missing metrics are derived internally.
keep_cols	Source columns to preserve in the output or schema defaults. These columns are retained in the returned data whenever possible.
metric_keep_cols	Columns to preserve during internal metric computation. These are passed to externalMetrics() when metrics are derived internally.
colmap	Optional aliases that update the default mappings. Use this when source names differ from the expected volume or metric names.
metric_colmap	Aliases used to resolve raw diameter and height columns during internal metric computation.
d_unit	Optional diameter unit override shared with schema resolution. Accepted values are "mm" and "cm".
metric_d_unit	Diameter unit expected by metric_colmap. Used when metrics must be computed internally.
h_unit	Optional height unit override shared with schema resolution. Accepted values are "m", "dm", and "cm".
metric_h_unit	Height unit expected by metric_colmap. Used when metrics must be computed internally.
tree_d_unit_out	Optional output unit for tree-level diameter values. Only used when summ.vr = NULL. Accepted values are "mm" and "cm".
tree_h_unit_out	Optional output unit for tree-level height values. Only used when summ.vr = NULL. Accepted values are "m", "dm", and "cm".
volume_colmap	Aliases used by the optional volume stage to locate metrics, species, region, and equation-set selectors.
selector	Rule used by externalMetrics2Vol() when several matches remain. "first" keeps the first surviving row; "priority" uses the highest numeric priority value when available.
track_provenance	Whether to keep provenance columns from the volume workflow. When TRUE, provenance columns are retained until the final summary stage removes them from grouped output.
compute_metrics_if_needed	Whether to compute missing metrics from raw inputs. If FALSE, the function stops when required standardized columns are absent.
schema	Optional "external_schema" object created by new_external_schema(). It centralizes column aliases, units, grouping defaults, and kept columns for repeated workflows.
domheight_fun	Optional function used to compute dominant height. When supplied, it overrides domheight_method during internal metric computation.
domdiameter_fun	Optional function used to compute dominant diameter. Supply it with a custom domheight_fun when "Dd" is requested; it must accept standardized d and n arguments.
domheight_method	Dominant-height method code resolved through domheight_registry.
domheight_registry	Named registry created with dominant_height_method_registry().
...	Additional arguments passed to downstream helpers. These are mainly useful for custom options in the internal metric or volume-processing steps.

Details

This wrapper mirrors the arguments and behaviour of dendroMetrics().

When summ.vr = NULL, the function returns tree-level records after applying cut.dt. When summ.vr contains one or more grouping variables, the function aggregates by those groups, reporting weighted means for d, h, Hd, and Dd, arithmetic sums for ba and volume variables, total stand density as n_tot, and quadratic mean diameter dg when diameter and expansion factors are available.

The function can work from already standardized inputs or from raw external tables. If requested metrics are missing and compute_metrics_if_needed = TRUE, it calls externalMetrics() internally, so raw inputs usually need a valid design plus diameter and, when relevant, height mappings. When schema is supplied, it provides reusable defaults for column aliases, units, grouping variables, and retained columns, while explicit arguments supplied in the call override those defaults.

Volume outputs are optional. They are computed only when parametro is supplied explicitly or can be inferred from var and method_registry. This lets the same entry point handle metric-only workflows, mixed metric-plus-volume workflows, and repeated processing of several input tables with optional parallel execution through mc.cores.

Value

A data.frame with classes "external_dendroMetrics", "dendroMetrics", and "data.frame".

With summ.vr = NULL, the returned rows represent tree-level records and retain the expansion-factor column n. With summ.vr supplied, grouped summaries return total stand density as n_tot, together with standardized units such as "cm", "m", "m2 ha-1", "ha-1", and "m3 ha-1" when those variables are present.

The returned object stores the matched call in attr(out, "call"). When available, it also preserves "units", "design_meta", "dominant_height_meta", "dominant_diameter_meta", and "volume_meta" attributes from upstream processing, which makes the result suitable for downstream inspection and update methods.

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
)

external_dendroMetrics(
    x = x,
    summ.vr = "plot",
    var = c("d", "h", "ba", "n"),
    design = sq_0.1ha,
    metric_colmap = list(d = "diameter_mm", h = "height_m"),
    metric_d_unit = "mm",
    metric_h_unit = "m"
)

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