Read forest inventory data

Read inventory table sourced from a file path or an object that inherits from class data.frame.

Usage

read_inv(
  inv_source,
  x = NULL,
  y = NULL,
  dbh = NULL,
  height = NULL,
  size = NULL,
  id = NULL,
  dbh_unit = c("cm", "m", "mm"),
  height_unit = c("m", "cm", "mm"),
  keep_rest = FALSE,
  verbose = TRUE,
  ...
)

Arguments

inv_source

object that inherits from class data.frame, or character path to a file in any file format readable with data.table::fread(). If provided with forest inventory data in a data.frame, the structure and column names are validated and homogenized; else, the function tries to read the dataset in the specified path.

x

character of length 1 or name of the variable in inv_source containing the x coordinates of the tree in m. If NULL (default), the function tries to identify the x coordinate from the data.

y

character of length 1 or name of the variable in inv_source containing the y coordinates of the tree in meters. If NULL (default), the function tries to identify the y coordinate from the data.

dbh

character of length 1 or name of the variable in inv_source containing the diameter at breast height of the tree (by default in cm, but can be defined via dbh_unit). If NULL (default), the function tries to identify the dbh from the data.

height

character of length 1 or name of the variable in inv_source containing the height of the tree (by default in m, but can be defined via heigh_unit). If NULL (default), the function tries to identify the height from the data.

size

character of length 1 or name of the variable in inv_source containing a generic size-related variable for CI_size(). If NULL (default), the variable is not assigned.

id

character of length 1 or name of the variable in inv_source containing a unique tree ID. If NULL (default), the function tries to identify the ID from the data. If this is not possible, the trees are assigned a unique number. All IDs are coerced to character.

dbh_unit

character of length 1. Unit for the diameter measurements (one of "cm", "m" or "mm". defaults to "cm").

height_unit

character of length 1. Unit for the diameter measurements (one of "m", "cm" or "mm". defaults to "m").

keep_rest

logical of length 1. Keep additional variables in the inventory table besides x, y, dbh, size and id for filtering or further computations? Defaults to FALSE.

verbose

logical of length 1. Should information about progress be printed? Defaults to TRUE.

...

additional arguments passed on to data.table::fread()

Value

object of class forest_inv: a modified data.table with x and y coordinates of the tree, a unique tree identifier (id) and tree diameter at breast height (dbh, in cm) and tree height (height, in m) if available.

Details

Function for reading and validating forest inventory data. Supports any formats readable with data.table::fread().

If provided with tabular data without explicitly specified variable names, the function by default takes the columns named "X" and "Y" (or "x" and "y") to be the tree coordinates, and looks for columns named "height", "height_m" or "h" as well as "dbh", "diameter","diam", or "d" (in any capitalization) as size-related variables. The tree ids are taken from columns named "id", "tree_id", "treeID" or "tree.id" (in any capitalization). All special characters besides "." and "_" are stripped from the column names before matching. For "size", the variable has to be specified explicitly; if not specified no generic size-related variable will be selected. All other columns in the source dataset are appended to the inventory when keep_rest = TRUE, but they are not validated, type-checked or sanitized.

If no columns with coordinates can be identified, the function fails with an error. If no ID column is available, the function assigns a unique number to each tree (but note that this will make specifying custom target trees difficult). It is possible to read in datasets without dbh and height, but usually only sensible if these are used as accessory datasets for identifying target trees (e.g. if target trees where identified by taking their GPS coordinates manually in the field).

See also

define_target() for designating target trees, compete_inv() for computing tree competition from inventory data, competition_indices for a list of available indices, plot_target() to plot target tree positions in target_inv and compete_inv objects. Find more examples in our tutorial.

Examples