inventoryMetrics: Dispatch complete workflows for SNFI and external inventories...

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

Dispatch complete workflows for SNFI and external inventories Unified dispatcher for inventory workflows

Description

Run a complete inventory workflow by dispatching to either dendroMetrics for Spanish National Forest Inventory inputs or to external_dendroMetrics() for external inventories. The function is intentionally thin: it decides which backend to use, forwards the relevant arguments, and stores the original call so the result can be updated later with update.

Usage

inventoryMetrics(nfi, 
    backend = c("auto", 
        "snfi", "external"), 
    summ.vr = "Estadillo", 
    cut.dt = "d == d", 
    report = FALSE, mc.cores = getOption("mc.cores", 
        1L), design = NULL, 
    schema = NULL, method_registry = NULL, 
    parameter_table = NULL, 
    ...)

Arguments

nfi	character, data.frame, or list. One inventory input or several inputs accepted by the selected backend.
backend	character(1). Backend selector. Use "auto" to infer the backend from the supplied arguments.
summ.vr	character or NULL. Grouping variable passed to the selected backend. When this argument is not supplied, inventoryMetrics() uses "Estadillo" for Spanish NFI and the schema level or detected plot identifier for external inventories.
cut.dt	character. Logical expression used to subset the backend output.
report	logical. If TRUE, request a CSV report from the selected backend.
mc.cores	integer. Number of cores used when the backend supports several inputs.
design	Optional sampling design. Passed to the selected backend when relevant.
schema	Optional external schema object. Used only by backend = "external".
method_registry	Optional method registry passed to the selected backend. This may define custom volume or summarization methods.
parameter_table	Optional table of parameters required by the external backend.
...	Additional named arguments forwarded to the selected backend.

Details

The dispatcher keeps computation inside the backend

functions. It only validates the backend choice,

forwards arguments, stores the reconstructed call in

attr(x, "call"), and records the chosen backend in

attr(x, "backend"). That makes the wrapper easier

to maintain while preserving a single public entry point.

Value

A backend result augmented with class

"inventoryMetrics", a stored call in

attr(x, "call"), and the selected backend in

attr(x, "backend"). The returned object otherwise

preserves the class and attributes produced by the backend.

Tree-level outputs use n for the per-record expansion

factor; grouped outputs use n_tot for total stand density.

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, nfiMetrics, metrics2Vol, update.inventoryMetrics NULL is meaningful here: it requests tree-level output. Add it after compacting optional arguments so it is not discarded. NULL is meaningful here: it requests tree-level output.

Examples

## External workflows require an external backend function and the
## corresponding schema, design, and parameter objects.

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

sch <- new_external_schema(
  colmap = list(
    plot = 'plot',
    species = 'species',
    d = 'diameter_mm',
    h = 'height_m'
  ),
  units = list(d = 'mm', h = 'm'),
  levels = 'plot',
  keep_cols = c('plot', 'species')
)

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

pars <- data.frame(
  species = c('sp1', 'sp2'),
  a = c(0.00002, 0.00003),
  b = c(2.30, 2.10),
  stringsAsFactors = FALSE
)

reg <- 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 <- inventoryMetrics(
  ext,
  backend = 'external',
  schema = sch,
  design = dsg,
  parameter_table = pars,
  method_registry = reg,
  summ.vr = 'plot',
  var = c('d', 'h', 'ba', 'n', 'v'),
  parametro = 'V'
)

out
attr(out, 'backend')
attr(out, 'units')

## Downloadable Toledo workflow. It requires internet access and an
## Access backend (mdbtools on Unix-like systems, ODBC on Windows),
## so it is not run during package checks.
## Not run: 
cache <- file.path(tempdir(), 'basifoR-cache')
dir.create(cache, showWarnings = FALSE)
toledo <- inventoryMetrics(
  'toledo',
  nfi.nr = 4,
  dir = cache,
  summ.vr = 'Estadillo'
)
head(toledo)
attr(toledo, 'units')

## End(Not run)

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