buildTree {rBDAT}R Documentation

Build and check tree data for subsequent use in BDAT Fortran subroutines

Description

this functions takes the data provided and builds a data.frame to be used in other BDAT get*-functions. It discriminates between different type of required output via the check-parameter. Checks are done on the type and range of the variables given to make sure calls to the Fortran routines do not suffer from type-mismatch (with potential freezing of R).

Usage

buildTree(tree, check = NULL, vars = NULL, mapping = NULL)

Arguments

tree

either a data.frame or a list containing the variables needed, i.e. spp, D1, H and optionally H1, D2, H2. See details for more information and parameter mapping for mapping of variable names.

check

character vector which indicates the type of required output and determines the checks to be done

vars

named list with additional variables for the specific BDAT-functions; see getDiameter, getHeight, getVolume, getBiomass, getBark, getForm and getAssortment. These variables might be included to tree as well, see details.

mapping

mapping of variable names in case a data.frame is given into parameter tree and vars between final colnames(tree) and required parameter names. See details.

Details

Parameter tree is able to take either a data.frame with correct variables names or arbitrary names if mapping is provided to map the data.frame names to the required names by c("df-colname" = "var-name") or to take a named list. If same-named variables are present in both tree and vars, priority is put on the ones in vars since explicitly given.

Possible variables are (*=required, depending on function):

For deriving assortments, the following variables are optional (if not given, default values are used):

If parameter tree is used to hand over all tree data in form of a data.frame, at least the parameter spp, D1, H must be provided, eventually mapped via mapping. Parameter Hx and Dx, which specify height and diameter for which a diameter or height is requested, respectively, can either be included to the definition of the tree data or alternatively given separately using the vars parameter. In that case, vars is used in priority to a identically named variable in tree. Additionally, tree and vars are merged via a full outer join. The add-on in fixed length assortments can be given in absolute and relative units at the same time, but the higher value will be used.

Value

a data.frame of class datBDAT.<check> having all variables needed in specific functions. If check is NULL, only a basic tree-data.frame of class "datBDAT" is returned.

Examples

## example for only tree data
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
res <- buildTree(tree = tree)
head(res)
class(res)

tree <- list(species = c(1, 1), dbh = c(30, 25), h = c(25, 30))
mapping <- c("species" = "spp", "dbh" = "D1", "h" = "H")
res <- buildTree(tree = tree, mapping = mapping)
head(res)
class(res)

## example for diameter calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
vars <- list(Hx = c(1.3, 1.3))
mapping <- NULL
res <- buildTree(tree = tree, check = "diameter", vars = vars)
head(res)
class(res)
tree <- list(Art = c(1, 1), Bhd = c(30, 25), H = c(25, 30))
vars <- list(X = c(1.3, 1.3))
mapping <- c("Art" = "spp", "Bhd" = "D1", "X" = "Hx")
res <- buildTree(tree = tree, check = "diameter", vars = vars, mapping = mapping)
head(res)
class(res)

## example with many diameters for one tree
tree <- list(spp = c(1), D1 = c(30), H = c(25))
vars <- list(Hx = seq(0, 25, 0.1))
mapping <- NULL
res <- buildTree(tree = tree, check = "diameter", vars = vars)

tree <- data.frame(s = 1, d = 30, h = 25, hx = 1.3)
mapping <- c("s" = "spp", "d" = "D1", "h" = "H", "hx" = "Hx")
res <- buildTree(tree, check = "diameter", mapping = mapping)
head(res)
class(res)

## example for height calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
vars <- list(Dx = c(30, 25))
res <- buildTree(tree = tree, check = "height", vars = vars)
head(res)
class(res)

## example for volume calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
check <- "volume"
vars <- list(A = c(30, 25), B = c(7, 7), sl = 0.1)
mapping <- NULL
res <- buildTree(tree = tree, check = "volume", vars = vars)
head(res)
class(res)

## example for bark calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
vars <- list(Hx = c(1.3, 1.3))
res <- buildTree(tree = tree, check = "bark", vars = vars)
head(res)
class(res)

## example for assortment calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
vars <- list(fixN = 1, fixZ = 10, fixL = 5, fixA = 10, fixR = 0.1)
res <- buildTree(tree = tree, check = "assortment", vars = vars)
head(res)
class(res)

## for cases where 'vars' could be a vector (i.e. getBark, getDiameter and
## getHeight), the following is also possible
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
vars <- c(1.3, 1.3)
res <- buildTree(tree = tree, check = "bark", vars = vars)
head(res)
class(res)

res <- buildTree(tree = tree, check = "height", vars = vars)
head(res)
class(res)

## but it is not possible in case of getVolume or getAssortment
## instead, use a named list to achieve a cross join / cartesian product
vars <- list(A = rep(1, 3), B = 5:7)
res <- buildTree(tree = tree, check = "volume", vars = vars)
head(res)
class(res)

## example for 'biomass' calculation
tree <- list(spp = c(1, 1), D1 = c(30, 25), H = c(25, 30))
res <- buildTree(tree = tree, check = "biomass")
head(res)
class(res)

## example with H1 != 1.3m
tree <- list(
  spp = c(1, 1), D1 = c(30, 25), H1 = c(2, 2), H = c(25, 30)
)
res <- buildTree(tree = tree, check = "biomass")
head(res)
class(res)
getBiomass(res)
[Package rBDAT version 1.0.0 Index]