dendroMetrics: Summarize dendrometrics

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

Summarize dendrometrics

Description

This function summarizes dendrometric data from the Spanish National Forest Inventory (SNF). It primarily accepts a province name or number, a local compressed SNF file, or a URL to a compressed SNF file hosted by www.miteco.gob.es. It can also process data frames previously returned by readNFI, nfiMetrics, or metrics2Vol. Dendrometric variables in the output are transformed into stand units, see Details section.

Usage

dendroMetrics(nfi, summ.vr = "Estadillo", 
    metric_levels = NULL, 
    cut.dt = "d == d", 
    report = FALSE, mc.cores = getOption("mc.cores", 
        1L), domheight_method = "Hd_strict", 
    domheight_registry = dominant_height_method_registry(), 
    ...)

Arguments

nfi	character, data.frame, or list. A province name or province number used to locate SNF data; a local path or URL to a compressed SNF file (.zip), including ZIP files hosted by www.miteco.gob.es; a data frame such as that returned by readNFI, nfiMetrics, or metrics2Vol; or a list of such objects.
summ.vr	character or NULL. Name of a Categorical variables in the SNF data used to summarize the outputs. If NULL then output from metrics2Vol is returned. Default 'Estadillo' processes sample plots.
metric_levels	character or NULL. Grouping variables used to compute tree-level metrics such as Hd before final summarization. When NULL, metric computation follows summ.vr.
cut.dt	character. Logical condition used to subset the output. For grouped summaries, use n_tot to filter total stand density. Default 'd == d' avoids subsetting.
report	logical. Print a report of the output in the current working directory.
mc.cores	integer. Number of cores used when several inputs are processed.
domheight_method	Dominant-height method used when Hd is recomputed during summary preparation. The default preserves the previous strict dendrometric behavior.
domheight_registry	Named dominant-height registry created with dominant_height_method_registry().
...	Additional arguments passed to readNFI, nfiMetrics, or metrics2Vol, including nfi.nr when required.

Details

Dendrometric variables are summarized according to the levels of argument summ.vr. Summary outputs include the categorical columns defined by summ.vr together with the quantitative variables available after processing with nfiMetrics and metrics2Vol.

These variables may include tree basal area ba ('m2 ha-1'), mean diameter at breast height d ('cm'), quadratic mean diameter dg ('cm'), mean tree height h ('m'), total stand density n_tot ('ha-1'), and over-bark volume v ('m3 ha-1').

When summ.vr = NULL, the function returns tree-level outputs from metrics2Vol after applying the filter defined in cut.dt.

When summ.vr is not NULL, the function converts supported variables to stand units, splits the data by the requested grouping variable, and computes summaries by group. The tree-level expansion factor n is used internally for weighting and summation; its group total is returned as n_tot. Variables d, h, and Hd, when present, are returned as averages weighted by n.

If both ba and n are available, the function also derives the quadratic mean diameter dg.

Output subsets are extracted using the logical expression supplied in cut.dt, see syntax in Logic.

The function accepts one input object or several inputs. When several inputs are supplied, each one is processed independently and the results are merged into a single output data frame. Parallel processing is controlled by mc.cores. Values greater than 1 process several inputs in parallel.

Value

data.frame. With summ.vr = NULL, tree-level output keeps the expansion-factor column n. With grouped summaries, total stand density is returned as n_tot. See Details.

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

## Minimal precomputed metrics object with units
toy_metrics <- structure(
    data.frame(
        Estadillo = c("plot1", "plot1", "plot2"),
        Especie   = c("sp1", "sp2", "sp1"),
        d         = c(120, 185, 260),          # mm
        h         = c(7.1, 9.4, 13.2),         # m
        ba        = c(0.0113, 0.0269, 0.0531), # m2 tree-1
        n         = c(127.32, 31.83, 14.15),
        stringsAsFactors = FALSE
    ),
    class = c("nfiMetrics", "data.frame"),
    units = c(
        d  = "mm",
        h  = "m",
        ba = "m2 tree-1",
        n  = "ha-1"
    ),
    nfi.nr = 4
)

## Summarize by plot
dendromet_toy <- dendroMetrics(toy_metrics, summ.vr = "Estadillo")

## Display output structure
str(dendromet_toy)

## The tree-level expansion factor n is summed and returned as n_tot
names(dendromet_toy)
attr(dendromet_toy, "units")

## Return tree-level processed data
tree_toy <- dendroMetrics(toy_metrics, summ.vr = NULL, cut.dt = "h > 8")
head(tree_toy)

## Alternatively, download data from 'www.miteco.gob.es'
## Specify province name/number and nfi number to compute dendrometrics.

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