ForestElementsR (version 2.2.0)

fe_stand: User Friendly Construction of an fe_stand Object from a Data Frame

Description

fe_stand() provides a user-friendly interface for the constructor new_fe_stand. While the constructor does not prevent users from creating malformed fe_stand objects, fe_stand does everything to achieve a well-defined object mostly based on an initial data.frame that might be, e.g. drawn out of a user's own data base.

Usage

fe_stand(
  x,
  tree_id_col,
  species_id_col,
  time_yr_col,
  dbh_cm_col,
  area_ha,
  stand_id = "my_fe_stand",
  layer_key_col = NA,
  age_yr_col = NA,
  height_m_col = NA,
  crown_base_height_m_col = NA,
  crown_radius_m_col = NA,
  removal_col = NA,
  ingrowth_col = NA,
  n_rep_ha_col = NA,
  small_trees = data.frame(),
  verbose = TRUE
)

Value

If the user input allows to construct a well-defined fe_stand

object, this object will be returned. If not, the function will terminate with an error.

Arguments

x

data.frame to be coerced into the goal object. Each line of x must represent a single tree. As a minimum requirement, there must be a column for the tree id, the species id, the time (in years), the diameter at breast height (dbh), each.

tree_id_col

name of the column in x which contains the tree id's (character, required, must not contain missing values)

species_id_col

name of the column in x which contains the species id's. Must be an object of one of the fe_species classes supported by this package. This column is required, must not contain missing values.

time_yr_col

name of the column in x which provides time information in years (character, required, must not contain missing values)

dbh_cm_col

name of the column in x which contains the dbh in cm (character, required, must not contain missing values)

area_ha

size of the stand area in ha (numeric. It is possible to have no defined stand area; in this case area_ha must be NULL, and n_rep_ha_col must be given (with no missing values).

stand_id

arbitrary id of the stand (character, default: "my_fe_stand")

layer_key_col

name of the column in x that contains codes for the stand layer a given tree belongs to. These codes are whole numbers. The following values are allowed: 1 - Main stand, 2 - Understorey, 3 - Pregeneration (ger: "Vorausverjuengung"), 4 - Remnant trees, hold over trees, veteran trees (ger: "Nachhiebsreste", "Ueberhaelter", "Altbaeume"). Must not contain missing values if provided. If not provided, it will be set to 1 (main stand) for every tree.

age_yr_col

name of the column in x which provides the tree ages in years (character, optional, may contain missing values)

height_m_col

name of the column in x which provides the tree heights in m (character, optional, may contain missing values)

crown_base_height_m_col

name of the column in x which provides the crown base heights in m (character, optional, may contain missing values)

crown_radius_m_col

name of the column in x which provides the crown radii in m (character, optional, may contain missing values)

removal_col

name of the column in x which provides the tree's removal status. If TRUE, this indicates the tree was removed or dead at the time indicated in age_yr_col (character, optional, must not contain missing values if provided). If not provided, the removal status will be FALSE for all trees in the resulting fe_stand object.

ingrowth_col

name of the column in x which provides the tree's ingrowth status. If TRUE, this indicates a tree that grew newly in at the time indicated in age_yr_col (character, optional, must not contain missing values if provided). If not provided, the ingrowth status will be FALSE for all trees in the resulting fe_stand object.

n_rep_ha_col

name of the column in the trees data frame which provides each tree's representation number per ha. Not required if a stand area is provided under area_ha. If a stand outline is given, n_rep_ha will be always recalculated based on the outline and the tree positions.

small_trees

An fe_stand object does contain an extra slot for small trees, defined as trees which are too small to have an own dbh (i.e. having a height > 1.3 m). So far, this slot is still experimental. The only requirement is that it is a data.frame. Such a data.frame can be provided via this parameter, it will be directly put into the goal object's small_trees slot. The default is a data.frame with zero rows and zero columns (data.frame()).

verbose

logical, if TRUE (default) the tree size variables will be checked for plausible orders of magnitude after successful construction of the fe_stand object. In case of a potential implausibility, a warning will be raised. The purpose of this mechanism is to avoid unit mismatches.

Details

The initial data.frame (or even nicer, tibble) provided by the user must contain a a minimum set of columns (tree id, species id, time variable, diameter at breast height). These columns must not contain missing values. Other columns (containing tree height, height to crown base, crown radius, tree age) are optional for the user to provide. If provided, they may contain missing values. If not provided these columns will only contain missing values in the fe_stand object. The columns about the trees' removal and ingrowth status are also optional, but if provided, they must not contain missing values. If not provided, both columns will be filled with FALSE in the resulting fe_stand object.

The columns from the user's data.frame that correspond to the columns defined in fe_stand objects will turn up in the object under standard names. All other columns that might be in the data.frame will be transferred to the fe_stand object with their orignal names. It is the user's responsibility to take care of them.

fe_stand will automatically add a column n_rep_ha which contains for each tree the number of trees it represents per ha. This may seem redundant if looking at fe_stand objects alone, but it allows a broad range of evaluation functions to be applied to different objects containing trees.

Examples

# Constructing an fe_stand object based on the minimum required information
# - make data.frame (or, nicer, a tibble) with stand information from
#   scratch
candidate_stand <- tibble::tibble(
  tree_no    = as.character(c(1:100)),
  species_id = as_fe_species_tum_wwk_short(c(rep("1", 30), rep("5", 70))),
  time_yr    = 2022,
  dbh        = c(rnorm(30, 45, 12), rnorm(70, 38, 9))
)

# - call fe_stand
goal_fe_stand_object <- fe_stand(
  x = candidate_stand,
  tree_id_col = "tree_no",
  species_id_col = "species_id",
  time_yr_col = "time_yr",
  dbh_cm_col = "dbh",
  area_ha = 0.33
)


# Using raw data that could come out of a user's data bases; here one
# example stands (spruce_beech_1_raw) provided with the ForestElementsR
# package
spruce_beech_1_raw$year <- 2022 # No time information in the data frame
spruce_beech_1_raw$species <- as_fe_species_tum_wwk_short(
  spruce_beech_1_raw$species
)

spruce_beech_stand <- fe_stand(
  spruce_beech_1_raw,
  tree_id_col = "no",
  species_id_col = "species",
  time_yr_col = "year",
  dbh_cm_col = "d",
  area_ha = 0.49,
  stand_id = spruce_beech_1_raw[1, ]$stand,
  age_yr_col = "age",
  height_m_col = "h",
  crown_base_height_m_col = "hcb",
  crown_radius_m_col = "crad"
)

# Little summary
spruce_beech_stand |> summary()