Skip to contents

Compute Metrics and Variables for Simulated TLS and Field Plots

simulations.Rd

Computes TLS metrics derived from simulated TLS plots and variables estimated on the basis of simulated field plots. Real TLS and field data from the same set of plots are required in order to build simulated plots. Three different plot designs are currently available: circular fixed area, k-tree and angle-count. During the simulation process, plots with incremental values for radius, k and BAF are simulated for circular fixed area, k-tree and angle-count designs, respectively, according to the parameters specified in the plot.parameters argument. For TLS metrics, different method are included for correcting occlusions generated in TLS point clouds.

Usage

simulations(tree.tls, tree.ds = NULL, tree.field,
            plot.design = c("fixed.area", "k.tree", "angle.count"),
            plot.parameters = data.frame(radius.max = 25, k.max = 50, BAF.max = 4),
            scan.approach = "single", var.metr = list(tls = NULL, field = NULL),
            v.calc = "parab", dbh.min = 4, h.min = 1.3, max.dist = Inf,
            dir.data = NULL, save.result = TRUE, dir.result = NULL)

Arguments

tree.tls

Data frame with information about trees detected from TLS point cloud data. The structure and format must be analogous to output returned by tree.detection.single.scan and tree.detection.multi.scan (or tree.detection.several.plots) functions. In particular, each row must correspond to a (plot, tree) pair, and it must include at least the following columns:

  • id, file, tree, x, y, phi.left, phi.right, horizontal.distance, dbh, num.points, num.points.hom, num.points.est, num.points.hom.est, partial.occlusion: same description and format as indicated for the same named columns in tree.detection.single.scan ‘Value’.

tree.ds

An optional list containing results arises from the application of distance sampling methodologies. The structure and format must be analogous to output returned by distance.sampling function. In particular, it must include at least the following elements:

  • tree: data frame with detection probabilities for each tree using distance sampling methodologies. Each row must correspond to a (plot, tree) pair, and it must include at least the following columns:

    • id, tree, P.hn, P.hn.cov, P.hr, P.hr.cov: same description and format as indicated for same named columns of tree in distance.sampling ‘Value’. In addition, plot identification and tree numbering included in id and tree columns must coincide with those included in the same named columns of tree.tls argument.

    If this argument is not specified by the user, it will be set to NULL by default and, as a consequence, the TLS metrics using distance sampling based correction will not be calculated for a circular fixed area or k-tree plot designs.

tree.field

Data frame with information about trees measured in the field plots. Each row must correspond to a (plot, tree) pair, and it must include at least the following columns:

  • id: plot identification encoded as character string or numeric. Plot identifications must coincide with those included in id column of the tree.tls argument.

  • tree: trees numbering.

  • horizontal.distance: horizontal distance (m) from plot centre to tree centre. Centres of the field plots must coincide with centres of their corresponding TLS plots.

  • dbh: tree diameter (cm) at breast height (1.3 m).

  • total.height: tree total height (m).

  • dead: integer value indicating for each tree if it is dead (1) or not (NA).

plot.design

Vector containing the plot designs considered. By default, all plot designs will be considered (circular fixed area, k-tree and angle-count plots).

plot.parameters

Optional list containing parameters for circular fixed area, k-tree and angle-count plot designs. User can set all or any of the following parameters specifying them as named elements of the list:

  • radius.max: maximum radius (m) allowed for the increasing sequence of radius values to be used in the simulation process of TLS and field plots under circular fixed area plot design. If this element is not included in the argument, circular fixed area plots will not be simulated.

  • radius.increment: positive increment (m) for the increasing sequence of radius values to be used in the simulation process of TLS and field plots in a circular fixed area plot design. If this element is not included in the argument, it is set to 0.1 m by default.

  • k.tree.max: maximum number of trees (trees) allowed for the increasing sequence of k values to be used in the simulation process of TLS and field plots under k-tree plot design. If this element is not included in the argument, k-tree plots will not be simulated.

  • BAF.max: maximum BAF (\({m}^{2}/ha\)) allowed for the increasing sequence of BAF values to be used in the simulation process of TLS and field plots in an angle-count plot design. If this element is not included in the argument, angle-count plots will not be simulated.

  • BAF.increment: positive increment (\({m}^{2}/ha\)) for the increasing sequence of BAF values to be used in the simulation process of TLS and field plots under angle-count plot design. If this element is not included in the argument, it is set to 0.1 \({m}^{2}/ha\) by default.

  • num.trees: number of dominant trees per ha (tree/ha) to be used for calculating dominant diameters and heights during the simulation process of TLS and field plots under all the available plot designs. Dominant trees are those with the largest diameter at breast height. If this element is not included in plot.parameters argument, it is set to 100 trees/ha by default.

If this argument is specified by the user, it must include at least one of the following elements: radius.max, k.tree.max or BAF.max. If this argument is not specified by the user, it is set to list(radius.max = 25, k.tree.max = 50, BAF.max = 4) by default and, as a consequence, the three available plot designs will be simulated.

scan.approach

Character parameter indicating TLS single-scan (‘single’) or TLS multi-scan approach or SLAM point clouds (‘multi’) approaches. If this argument is not specified by the user, it will be set to ‘multi’ approach.

var.metr

Optional vector containing all the metrics and variables of interest. By default it will be set as NULL and thus, all the metrics and variables available will be generated.

v.calc

Optional parameter to calculate volume when is not included in tree.tls input data.

dbh.min

Optional minimum dbh (cm) considered for detecting trees. By default it will be set at 4 cm.

h.min

Optional minimum h (m) considered for detecting trees. By default it will be set at 1.3 m.

max.dist

Optional argument to specify the maximum horizontal distance considered in which trees will be included.

dir.data

Optional character string naming the absolute path of the directory where TXT files containing TLS point clouds are located. .Platform$file.sep must be used as the path separator in dir.dat, and TXT files in the directory must have the same description and format as indicated for TXT files in normalize ‘Output Files’. If this argument is not specified by the user, it will be set to NULL by default and, as a consequence, the current working directory of the R process will be assigned to dir.dat during the execution.

save.result

Optional logical which indicates wheter or not the output files described in ‘Output Files’ section must be saved in dir.result. If this argument is not specified by the user, it will be set to TRUE by default and, as a consequence, the output files are saved.

dir.result

Optional character string naming the absolute path of an existing directory where files described in ‘Output Files’ section will be saved. .Platform$file.sep must be used as the path separator in dir.result. If this argument is not specified by the user, and save.result is TRUE, it will be set to NULL by default and, as a consequence, the current working directory of the R process will be assigned to dir.result during the execution.

Details

Using real TLS and field data from the same set of plots, this function enables construction of simulated plots under different plot designs and computation of the corresponding TLS metrics and estimated variables. The notation used for variables is based on IUFRO (1959).

At this stage, three plot designs are available:

  • Circular fixed area plots, simulated only if a radius.max value is specified in the plot.parameters argument.

  • k-tree plots, simulated only if a k.tree.max value is specified in the plot.parameters argument.

  • Angle-count plots, simulated only if a BAF.max value is specified in the plot.parameters argument.

For each real plot, a simulation process is run under each of the plot designs specified by means of elements of the plot.parameters argument. Although there are some minor differences depending on the plot design, the rough outline of the simulation process is similar for all, and it consists of the following main steps:

  1. Define an increasing sequence of the plot design parameter (radius, k or BAF) according to the maximum value and, if applicable, the positive increment set in plot.parameters argument.

  2. Build simulated plots for each parameter value in the previous sequence based on either TLS or field data.

  3. Compute either TLS metrics or variables estimated on the basis of simulated plots for each parameter value (see ‘Value’ section for details). For the simulated TLS plots, note that in addition to the counterparts of variables computed for the simulated field plots, the function also computes the following:

    • Metrics related to the number of points belonging to normal tree sections.

    • Metrics with occlusion corrections based on the following:

      • Distance sampling methodologies (Astrup et al., 2014) for circular fixed area and k-tree plot designs, if the distance.sampling argument is not NULL.

      • Correction of the shadowing effect (Seidel & Ammer, 2014) for circular fixed area and k-tree plot designs.

      • Gap probability attenuation with distance to TLS (Strahler et al., 2008; Lovell et al., 2011) for angle-count plot design.

    • Height percentiles derived from z coordinates of TLS point clouds relative to ground level.

Value

List with field estimates and TLS metrics for plot designs considered. It will contain one element per plot design considered (fixed.area.plot, k.tree.plot and angle.count.plot)

fixed.area.plot

If no value for radius.max is specified in the plot.parameters argument, NULL; otherwise, data frame with TLS metrics and variables will be estiamted on the basis of simulated plots in a circular fixed area plot design. Each row will correspond to a (plot, radius) pair, and the following columns will be included:

Plot identification and radius:

  • id: plot identification encoded as a character string or numeric. It will coincide with those included in the id column of tree.tls, tree.field or, if applicable, distance.sampling arguments.

  • radius: radius (m) of the simulated plot.

Variables estimated on the basis of simulated field plots:

  • N: stand density (trees/ha).

  • G: stand basal area (\({m}^{2}/ha\)).

  • V: stand volume (\({m}^{3}/ha\)).

  • d, dg, dgeom, dharm: mean tree diameters (cm) at breast height (1.3 m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

  • h, hg, hgeom, hharm: mean tree heights (m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

  • d.0, dg.0, dgeom.0, dharm.0: dominant mean tree diameters (cm) at breast height (1.3 m), calcualted from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

  • h.0, hg.0, hgeom.0, hharm.0: dominant mean tree heights (m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

TLS variables derived from simulated TLS plots:

  • N.tls: stand density (trees/ha) without occlusion corrections.

  • N.hn, N.hr, N.hn.cov, N.hr.cov: stand density (trees/ha) with occlusion corrections based on distance sampling methodologies. These columns will be missing if the distance.sampling argument is NULL.

  • N.sh: stand density (trees/ha) with correction of the shadowing effect.

  • G.tls: stand basal area (\({m}^{2}/ha\)) without occlusion corrections.

  • G.hn, G.hr, G.hn.cov, G.hr.cov: stand basal area (\({m}^{2}/ha\)) with occlusion corrections based on distance sampling methodologies. These columns will be missing if the distance.sampling argument is NULL.

  • G.sh: stand basal area (\({m}^{2}/ha\)) with correction of the shadowing effect.

  • V.tls: stand volume (\({m}^{3}/ha\)) without occlusion corrections.

  • V.hn, V.hr, V.hn.cov, V.hr.cov: stand volume (\({m}^{3}/ha\)) with occlusion corrections based on distance sampling methodologies. These columns will be missing if the distance.sampling argument is NULL.

  • V.sh: stand volume (\({m}^{3}/ha\)) with correction of the shadowing effect.

  • d.tls, dg.tls, dgeom.tls, dharm.tls: mean tree diameters (cm) at breast height (1.3 m), calculated from the arithmetic mean, quadratic mean geometric mean, and harmonic mean, respectively.

  • h.tls, hg.tls, hgeom.tls, hharm.tls: mean tree heights (m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

  • d.0.tls, dg.0.tls, dgeom.0.tls, dharm.0.tls: dominant mean tree diameters (cm) at breast height (1.3 m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

  • h.0.tls, hg.0.tls, hgeom.0.tls, hharm.0.tls: dominant mean tree heights (m), calculated from the arithmetic mean, quadratic mean, geometric mean and harmonic mean, respectively.

TLS metrics derived from simulated TLS plots:

  • num.points, num.points.est, num.points.hom, num.points.hom.est: number of points and estimated number of points (points) belonging to trees with normal sections (+/- 5 cm) in the original point cloud (num.points and num.points.est, respectively); and number of points and estimated number of points (points) belonging to trees normal sections (+/- 5 cm) in the reduced point cloud (num.points.hom and num.points.hom.est, respectively).

  • P01, P05, P10, P20, P25, P30, P40, P50, P60, P70, P75, P80, P90, P95, P99: height percentiles derived from z coordinates of TLS point clouds relative to ground level.

k.tree.plot

If no value for k.tree.max is specified in the plot.parameters argument, NULL; otherwise the data frame with TLS metrics and estimations of variables will be based on simulated plots in the k-tree plot design. Each of row will correspond to a (plot, k) pair, and the following columns will be included:

Plot identification and k:

  • id: plot identification encoded as character string or numeric. The id will coincide with those included in the id column of tree.tls, tree.field or, if applicable, distance.sampling arguments.

  • k: number of trees (trees) in the simulated plot.

Estimated variables based on simulated field plots:

  • N, G, V, d, dg, dgeom, dharm, h, hg, hgeom, hharm, d.0, dg.0, dgeom.0,
    dharm.0, h.0, hg.0, hgeom.0, hharm.0: same description and format as indicated in the fixed.area.plot element.

TLS variables derived from simulated TLS plots:

  • N.tls, N.hn, N.hr, N.hn.cov, N.hr.cov, N.sh,
    G.tls, G.hn, G.hr, G.hn.cov, G.hr.cov, G.sh,
    V.tls, V.hn, V.hr, V.hn.cov, V.hr.cov, V.sh,
    d.tls, dg.tls, dgeom.tls, dharm.tls,
    h.tls, hg.tls, hgeom.tls, hharm.tls,
    d.0.tls, dg.0.tls, dgeom.0.tls, dharm.0.tls,
    h.0.tls, hg.0.tls, hgeom.0.tls, hharm.0.tls

TLS metrics derived from simulated TLS plots:

  • num.points, num.points.est, num.points.hom, num.points.hom.est,
    P01, P05, P10, P20, P25, P30, P40, P50, P60, P70, P75, P80, P90, P95, P99: same description and format as indicated in fixed.area.plot element.

angle.count.plot

If no value for BAF.max is specified in the plot.parameters argument, NULL; otherwise the data frame will include TLS metrics and estimated variables based on simulated plots in the angle-count plot design. Each row will correspond to a (plot, BAF) pair, and the following columns will be included:

Plot identification and BAF:

  • id: plot identification encoded as character string or numeric. The id will coincide with those included in the id column of tree.tls and tree.field.

  • BAF: BAF (\({m}^{2}/ha\)) of the simulated plot.

Estimated variables based on simulated field plots:

  • N, G, V, d, dg, dgeom, dharm, h, hg, hgeom, hharm, d.0, dg.0, dgeom.0,
    dharm.0, h.0, hg.0, hgeom.0, hharm.0: same description and format as indicated in the fixed.area.plot element.

TLS variables derived from simulated TLS plots:

  • N.tls: same description and format as indicated in the fixed.area.plot element.

  • N.pam: stand density (trees/ha) with occlusion correction based on gap probability attenuation with distance to TLS.

  • G.tls: same description and format as indicated in fixed.area.plot element.

  • G.pam: stand basal area (\({m}^{2}/ha\)) with occlusion correction based on gap probability attenuation with distance to TLS.

  • V.tls: same description and format as indicated in fixed.area.plot element.

  • V.pam: stand volume (\({m}^{3}/ha\))with occlusion correction based on gap probability attenuation with distance to TLS.

  • d.tls, dg.tls, dgeom.tls, dharm.tls,
    h.tls, hg.tls, hgeom.tls, hharm.tls,
    d.0.tls, dg.0.tls, dgeom.0.tls, dharm.0.tls,
    h.0.tls, hg.0.tls, hgeom.0.tls, hharm.0.tls

TLS metrics derived from simulated TLS plots:

  • num.points, num.points.est, num.points.hom, num.points.hom.est,
    P01, P05, P10, P20, P25, P30, P40, P50, P60, P70, P75, P80, P90, P95, P99: same description and format as indicated in fixed.area.plot element.

Output Files

At the end of the simulation process, if the save.result argument is TRUE, the function will print all the elements described in ‘Value’ section and which are different from NULL to files. Data frames are written without row names in dir.result directory using the write.csv function from the utils package. The pattern used for naming these files is simulations.<plot design>.csv, where <plot design> is equal to “fixed.area.plot”, “k.tree.plot” or “angle.count.plot” according to plot design.

References

Astrup, R., Ducey, M. J., Granhus, A., Ritter, T., & von Lüpke, N. (2014). Approaches for estimating stand level volume using terrestrial laser scanning in a single-scan mode. Canadian Journal of Forest Research, 44(6), 666-676. doi:10.1139/cjfr-2013-0535

IUFRO (1959). Standarization of symbols in forest mensuration. IUFRO, Wien, 32 pp.

Lovell, J. L., Jupp, D. L. B., Newnham, G. J., & Culvenor, D. S. (2011). Measuring tree stem diameters using intensity profiles from ground-based scanning lidar from a fixed viewpoint. ISPRS Journal of Photogrammetry and Remote Sensing, 66(1), 46-55. doi:10.1016/j.isprsjprs.2010.08.006

Seidel, D., & Ammer, C. (2014). Efficient measurements of basal area in short rotation forests based on terrestrial laser scanning under special consideration of shadowing. iForest-Biogeosciences and Forestry, 7(4), 227. doi:10.3832/ifor1084-007

Strahler, A. H., Jupp, D. L. B., Woodcock, C. E., Schaaf, C. B., Yao, T., Zhao, F., Yang, X., Lovell, J., Culvenor, D., Newnham, G., Ni-Miester, W., & Boykin-Morris, W. (2008). Retrieval of forest structural parameters using a ground-based lidar instrument (Echidna®). Canadian Journal of Remote Sensing, 34(sup2), S426-S440. doi:10.5589/m08-046

Note

The simulation process implemented in this function is computationally intensive. Although the function currently uses the vroom function from the vroom package for reading large files and contains fast implementations of several critical calculations (C++ via Rcpp package), long computation times may be required when a large number of plots are considered, number of points in TLS point clouds are very high, or the radius, k or BAF sequences used in the simulation process are very long.

Using reduced point clouds (according to point cropping process implemented in the normalize function), rather than original ones, may be recommended in order to cut down on computing time. Another possibility would be to specify large increments for radius and BAF, and/or low maximum values for radius, number of trees and BAF in the plot.parameters argument. This would make the function more efficient, though there may be a notable loss of detail in the results generated.

Author

Juan Alberto Molina-Valero and Adela Martínez-Calvo.

See also

tree.detection.single.scan, tree.detection.multi.scan, tree.detection.several.plots, distance.sampling, normalize.

Examples

# \donttest{

# Load information of trees detected from TLS point clouds data corresponding to
# plots 1 and 2 from Rioja data set

data("Rioja.data")
example.tls <- subset(Rioja.data$tree.tls, id < 3)

# Compute detection probabilities using distance sampling methods

example.ds <- distance.sampling(example.tls)

# Load information of trees measured in field plots corresponding to plot 1 and 2
# from Rioja data set

example.field <- subset(Rioja.data$tree.field, id < 3)

# Establish directory where TXT file containing TLS point cloud corresponding to
# plot 1 from Rioja data set is located. For instance, current working directory

dir.data <- tempdir()

# Download example of TXT file corresponding to plots 1 and 2 from Rioja data set

download.file(url = "https://www.dropbox.com/s/w4fgcyezr2olj9m/Rioja_1.txt?dl=1",
              destfile = file.path(dir.data, "1.txt"), mode = "wb")

download.file(url = "https://www.dropbox.com/s/sghmw3zud424s11/Rioja_2.txt?dl=1",
              destfile = file.path(dir.data, "2.txt"), mode = "wb")

# Establish directory where simulation results corresponding to plots 1 and 2
# from Rioja data set will be saved. For instance, current working directory

dir.result <- tempdir()

# Compute metrics and variables for simulated TLS and field plots corresponding
# to plots 1 and 2 from Rioja data set
# Without occlusion correction based on distance sampling methods

sim <- simulations(tree.tls = example.tls, tree.field = example.field,
                   plot.parameters = data.frame(radius.max = 10, k.max = 20,
                                                BAF.max = 2),
                   dir.data = dir.data, dir.result = dir.result)
#> Computing simulations for plot: '1'
#>  (547.77 secs)
#> Computing simulations for plot: '2'
#>  (509.81 secs)


# }