new_volume_method: Define one external volume-computation method

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

Define one external volume-computation method

Description

Create a method specification for registry-based volume calculations in external inventory workflows.

Usage

new_volume_method(output, 
    fun = NULL, fun_name = NULL, 
    unit = "m3", raw_unit = unit, 
    scale_to_m3 = 1, 
    build_args = function(ctx, 
        pars, resolved) list(), 
    fallback = function(ctx, 
        pars, resolved) null_or(resolved$preexisting_v_m3, 
        NA_real_), match_by = character(0), 
    get_pars = NULL, 
    pars = NULL, filter_pars = NULL, 
    required_inputs = NULL)

Arguments

output	character(1). Name of the output column produced by the method, for example "v", "vcc", or "vsc".
fun	Optional function. Direct function used to compute the raw output value.
fun_name	Optional character(1). Name of a function to resolve at run time when fun is not supplied.
unit	character(1). Unit reported for the returned value after scaling.
raw_unit	character(1). Unit produced by the raw method before applying scale_to_m3.
scale_to_m3	numeric(1). Multiplicative factor used to convert the raw result to cubic metres.
build_args	function. Builds the argument list passed to the equation function. It receives the current row context, the selected parameter row, and already resolved outputs.
fallback	function. Returns a fallback value when the method cannot compute a raw result, for example because the function, parameters, or arguments are missing.
match_by	character. Column names used to match candidate parameter rows against the current row context.
get_pars	Optional function. Custom resolver that returns the parameter rows to use for the current tree or observation.
pars	Optional embedded parameter table stored inside the method definition.
filter_pars	Optional function. Additional filter applied after parameter matching and before row selection.
required_inputs	Optional character. Standardized inputs that must be available before the method can run, for example c("d", "h").

Details

The fallback function should return a scalar numeric value, typically NA_real_ or a pre-existing volume estimate already present in the data. Define required_inputs with the standardized variable names expected by the method so the workflow can resolve prerequisites before evaluation.

Value

A named list describing one external volume method.

The list contains the components output, fun,

fun_name, unit, raw_unit,

scale_to_m3, build_args, fallback,

match_by, get_pars, pars,

filter_pars, and required_inputs.

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 standalone example
vm <- new_volume_method(
    output = "vcc",
    fun = function(dbh_cm, h_m, pars) dbh_cm * h_m * pars$k[1],
    unit = "m3",
    raw_unit = "cm3",
    scale_to_m3 = 1 / 1e6,
    build_args = function(ctx, pars, resolved) {
        list(dbh_cm = ctx$d_cm, h_m = ctx$h_m, pars = pars)
    },
    fallback = function(ctx, pars, resolved) NA_real_,
    match_by = "species",
    pars = data.frame(species = "sp1", k = 2500),
    required_inputs = c("d", "h")
)

names(vm)
vm$output
vm$build_args(
    ctx = list(d_cm = 20, h_m = 12),
    pars = vm$pars,
    resolved = list()
)

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