rBDAT (version 1.0.0)

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

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.

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

• spp*: numeric, 1 <= spp <= 36, see getSpeciesCode

• D1*: numeric, first measured diameter [cm], usually at 1.3m

• H1: numeric, height of first measured diameter [m], if zero, internally transformed to 1.3m

• D2: numeric, second measured diameter [cm], or form parameter: latter is defined in conjunction with H2:

  • D2=0 and H2=0 => taper form of volume tables according to Grundner & Schwappach (1906-1938), the default

  • D2=0 and 0 < H2 < 100 => german NFI1-taper form, with H2 given as percentile of the NFI1-\(q_{0.30}\)-distribution; H2=50 corresponds to mean NFI1 taper form, H2<50 to slenderly and H2>50 to thicker trees; see getForm for more information about \(q_{0.30}\)

  • D2=0 and H2>100 => mean NFI1 taper form

  • D2>0 and H2=0 => D2 is a diameter and H2 is assumed to be 7m

  • D2>0 and H2>0 => D2 and H2 are given as diameter and height

  • -1<D2<0 => abs(D2) is interpreted as \(q_{0.30}\)

  • -1>D2 => mean NFI1 taper form

• H2: numeric, height of second measured diameter [m], or in conjunction with D2, see there.

• H*: numeric, tree height [m]

• A*: numeric, lower diameter [cm] or height [m] of section for which volume should be calculated, interpretation depends on iAB, see getVolume

• B*: numeric, upper diameter [cm] or height [m] of section for which volume should be calculated, interpretation depends on iAB, see getVolume

• sl: numeric, length of section over which should be integrated, defaults to 2.0m

• Dx*: diameter for which height or bark thickness is required

• Hx*: height for which diameter is required

• inv: inventory for which mean q03 is required, defaults to 1, see getForm

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

• lX: length of unusable wood at stem foot [m], defaults to 0 (X-Holz)

• Hkz: indicator for tree top, 0 - normal (default), 1 - Wipfelbruch, 2 - Gipfelbruch

  • 0 => H=H

  • 1 => H=H+2

  • 2 => DBH < 30 => H=DBH; dbh > 30 => H = 30 + (DBH-30) * 0.3

• Skz: indicator for stem type, defaults to 0

  • 0 => conifer trees => no restriction; deciduous trees => no assortments

  • 1 => monopodial deciduous trees => Hsh = 0.7*H

  • 2 => branching between dbh and 7m => Hsh = 5m

  • 3 => crown base < 3m => Hsh=0.1

  • 4 => dead or broken stem => Az = H*0.7

  • 5 => dead tree => non-usable wood

• Hsh: usable stem height, defaults to 0, i.e. 0.7*H

• Az: minimum cutting diameter over bark [cm], defaults to 0, using an exponential function given DBH

• Zsh: minimum cutting diameter under bark for stem wood [cm], defaults to 0, using parameter Az if estimated length < maximum length (i.e. 20m)

• Zab: minimum cutting diameter under bark for top segment [cm], defaults to 0, i.e. 14cm under bark

• Sokz: type assortment calculation, 0 - no assortment, 1 - Mid diameter (Mittenstärke), 2 - Heilbronner Sortierung, defaults to 1

• fixN: number of fixed length assortments at stem foot, defaults to 0 (no fixed length assortments, irrespective of other fix* parameters)

• fixZ: mininum diameter under bark for fixed length assortment at stem foot, defaults to 0

• fixL: length of fixed length assortment at stem foot, defaults to 0

• fixA: fixed length assortement add-on in [cm], defaults to 0

• fixR: fixed length assortement add-on in [%], defaults to 0

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.

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)