Define target trees in forest inventory data

define_target() takes a forest_inv dataset and returns an updated forest inventory with highlighted target trees for analysis with compete_inv. Target trees can be manually specified by tree ID, imported from a different dataset or identified automatically by excluding edge trees from their coordinates.

Usage

define_target(
  inv,
  target_source = "buff_edge",
  radius = 10,
  tol = 1,
  crop_to_target = FALSE,
  verbose = TRUE
)

Arguments

inv

object of class forest_inv as created with read_inv().

target_source

one of the following:

1. a vector of class "character" containing the tree IDs identifying the target trees in the same format as in the id column of inv.

2. a vector of class logical specifying for each row of inv whether the corresponding tree is a target tree.

3. another object of class forest_inv containing the coordinates of the target trees. In this case, the coordinates are matched against the coordinates in inv and IDs may differ (useful e.g. when target trees are defined based on GPS coordinates and matched against an airborne laser scanning dataset).

4. a character vector of length 1 defining the method by which the target trees should be determined. Allowed are "buff_edge" for excluding all trees that are at least one search radius from the forest edge, "exclude_edge" for only excluding edge trees or "all_trees" for including all trees of the dataset (which is hardly ever a good idea unless all trees in the entire forest are in the dataset). The standard is "buff_edge". See below for details.

radius

numeric of length 1, Search radius (in m) around target tree wherein all neighboring trees are classified as competitors. Only used if target_source is "buff_edge", "exclude_edge" or if crop_to_target = TRUE. Defaults to 10.

tol

numeric of length 1. Only used when target_source is an inventory with a second set of coordinates. Tolerance for the match between tree coordinates in the forest inventory and target datasets if specified as a second set of coordinates. If (GPS-based) field measurements of coordinate are used to identify target trees and the full inventory is from a different data source (e.g. ALS data), a the tolerance value may have to be adjusted to identify the trees depending on the GPS accuracy. Values of 0 mean exact matching. Defaults to 1 (match within a 1 m buffer).

crop_to_target

logical of length 1. Should the inventory be limited to the extent of the target coordinates? If TRUE, the extent of inv will be cropped to the extent of forest_inv \(\pm\) radius + 1 m for safety to reduce computational load in later steps. Defaults to FALSE.

verbose

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

Value

object of class target_inv (inherits from forest_inv): a modified data.table with the x and y coordinates of the tree, a unique tree identifier (id), at least one of tree diameter at breast height (dbh, in cm) and tree height (height,in m) and a new logical column target specifying whether a tree is defined as a target tree.

Details

define_target() can be used to select target trees from a forest_inv object either by manually specifying them as a character vector with tree IDs, as a logical vector that specifies for each tree in the inventory whether or not it is treated as a target tree, a separate set of (approximate) coordinates of the target trees that is matched against the original inventory, or a character string describing how to choose the target trees based on their spatial arrangement.

When the target is defined by a second set of coordinates, these coordinates will then be matched against the inventory data. IDs are ignored in this case and matching is based only on the closest trees with in a buffer of tol m (the default is tol = 1: matching within 1 m). All further size-related variables in the second set of coordinates are ignored as well to make sure that in later steps competition indices will be computed with data from the same data source. When different target trees are matched to the same tree in the inventory, or when two trees in the inventory have the same distance to a target tree within 5 cm, the function fails with an error. If two inventory trees are within the specified tolerance and the difference is larger, the function proceeds with a warning. The intended use case for determining target trees in this way is to compute tree competition from ALS data based on GPS coordinates of single trees in studies that are based on single tree rather than plot-level data, which creates a need for different data sources to compute competition.

The methods target_source = "buff_edge" and target_source = "exclude_edge" are intended for cases where it is desired to compute valid competition indices for as many trees as possible while avoiding edge effects. While it is possible to designate all trees in the dataset as target tree by setting target_source = "all_trees", this is not a good idea in the majority of cases: unless your dataset contains all trees in the forest (possible for ALS-based data, but very unlikely for data based on classical inventory methods and TLS/MLS), there will be very extreme edge effects at the outer edge of the extent of the covered trees resulting in strongly underestimated competition for edge trees. target_source = "buff_edge" excludes all trees who are less than one search radius (radius) away from the plot border (approximated by a concave hull based on concaveman::concaveman() using a length threshold of 2 times the desired search radius) and hence guarantees to only include trees that can obtain valid competition index values for that search radius. target_source = "exclude_edge" only removes the edge trees and hence is less restrictive, but more prone to edge effects.

Do not use target_source = "all_trees" unless you know exactly what you are doing!

See also

read_inv() to read forest inventory data, 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. For visualized examples, see competition inventory

Examples

if (FALSE) { # \dontrun{
# read inventory
inventory1 <- read_inv(inv_source = "data/inventory1.csv", dbh_unit = "m")

# designate target trees based on character vector with tree ids
targets1 <- define_target(
  inv = inventory1,
  target_source = c("FASY-43-24", "FASY-43-27", "FASY-43-30")
)

# designate target trees based on logical vector
targets2 <- define_target(
  inv = inventory1,
  target_source = grepl("FASY", inventory1$id)
)

# designate target trees based on GPS coordinates
# read target tree positions
target_pos <- read_inv("data/target_tree_gps.csv",
                       x = gps_x, y = gps_y, verbose = FALSE)

# read inventory
inventory4 <- readr::read_csv("data/inventory4.csv") %>%
  dplyr::filter(plot_id == "Plot 1") %>%
  read_inv(dbh = diam, verbose = FALSE)

# define target trees
targets3 <- define_target(
  inv = inventory4,
  target_source = target_pos,
  tol = 1 # match within 1 m accuracy
)

# designate target trees with a 10 m buffer to the plot border
targets4 <- define_target(
  inv = inventory4,
  target_source = "buff_edge",
  radius = 8)

# designate target trees by only excluding the plot border
targets5 <- define_target(
  inv = inventory4,
  target_source = "exclude_edge",
  radius = 8
)

# designate all trees as target trees
targets6 <- define_target(
  inv = inventory4,
  target_source = "all_trees")
} # }