nfiMetrics: Tree-level metrics for Spanish NFI inputs

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

Tree-level metrics for Spanish NFI inputs

Description

Compute tree-level diameter, height, basal area, trees per hectare, and optional dominant height from Spanish National Forest Inventory inputs. Supply either an object returned by readNFI or a path/URL that readNFI can import. The function returns the requested metrics together with the matched grouping columns and attaches unit metadata to the result.

Usage

nfiMetrics(nfi, var = c("d", 
    "h", "ba", "n", "Hd", 
    "Dd"), levels = c("esta", 
    "espe"), design = snfi_design(), 
    domheight_method = "Hd", 
    domheight_registry = dominant_height_method_registry(), 
    ...)

Arguments

nfi	character(1) or a "readNFI" object. Supply either a path/URL that readNFI can import or an already imported object returned by readNFI. The input should contain the SNFI diameter and height fields, usually aliases such as Dn and altura.
var	character. Metrics to compute. Supported values are 'd' (diameter in mm), 'h' (height in m), 'ba' (basal area per tree in m^2), 'n' (trees per hectare), 'Hd' (dominant height in m), and 'Dd' (dominant diameter in mm). Request 'h', 'd', and 'n' together when you request 'Hd'.
levels	character. Column-name patterns used to keep grouping variables in the output. Matching ignores case and accepts partial matches. The default usually keeps plot and species identifiers when those fields are present.
design	Sampling design used to derive 'n' and any dependent 'Hd' calculation. Supply the default snfi_design(), another "concentric_design", or any "inventory_design" supported by trees_per_ha. The returned object stores a summary of the design in attr(x, "design_meta") when relevant.
domheight_method	character(1). Dominant-height method code resolved through domheight_registry when 'Hd' is requested.
domheight_registry	Named registry created with dominant_height_method_registry.
...	Additional arguments passed to readNFI when nfi is not already a "readNFI" object.

Details

If you request 'Hd', the function computes

dominant height within the groups selected by

levels by using 'h', 'd', and

'n'. The active method is resolved through

domheight_registry; inspect

dominant_height_method_registry()$Hd to see the

equation, selection rule, threshold, variables, and fallback.

Value

data.frame with the matched identifier and grouping columns plus the metrics requested in var. The output inherits from 'nfiMetrics' and 'data.frame' and stores attr(x, 'nfi.nr') when available. Inspect attr(x, 'units') for the returned metric units and attr(x, 'design_meta') for the sampling design summary attached when 'n', 'Hd', or 'Dd' is requested. When 'Hd' is requested, inspect attr(x, 'dominant_height_meta') to see the method code, equation, selection rule, threshold, and fallback.

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>)

See Also

dendroMetrics, dbhMetric, readNFI, snfi_design, trees_per_ha, dominant_height_method_registry

Examples

## Minimal reproducible example with a small object that mimics
## readNFI() output
toy_ifn <- structure(
    data.frame(
        esta = c("plot1", "plot1", "plot2"),
        espe = c("sp1", "sp2", "sp1"),
        Dn = c(120, 185, 260),
        altura = c(7.1, 9.4, 13.2),
        stringsAsFactors = FALSE
    ),
    class = c("readNFI", "data.frame"),
    nfi.nr = 4
)

x <- nfiMetrics(
    toy_ifn,
    var = c("d", "h", "ba", "n"),
    levels = c("esta", "espe")
)

x
attr(x, "units")

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