| simulations {FORTLS} | R Documentation |
Compute Metrics and Variables for Simulated TLS and Field Plots
Description
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.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
|
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:
|
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:
If this argument is specified by the user, it must include at least one of
the following elements: |
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. |
save.result |
Optional logical which indicates wheter or not the output files described in
‘Output Files’ section must be saved in |
dir.result |
Optional character string naming the absolute path of an existing directory
where files described in ‘Output Files’ section will be saved.
|
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.maxvalue is specified in theplot.parametersargument.k-tree plots, simulated only if a
k.tree.maxvalue is specified in theplot.parametersargument.Angle-count plots, simulated only if a
BAF.maxvalue is specified in theplot.parametersargument.
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:
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.parametersargument.Build simulated plots for each parameter value in the previous sequence based on either TLS or field data.
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.samplingargument is notNULL.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 Plot identification and radius:
Variables estimated on the basis of simulated field plots:
TLS variables derived from simulated TLS plots:
TLS metrics derived from simulated TLS plots:
|
k.tree.plot |
If no value for Plot identification and k:
Estimated variables based on simulated field plots:
TLS variables derived from simulated TLS plots:
TLS metrics derived from simulated TLS plots:
|
angle.count.plot |
If no value for Plot identification and BAF:
Estimated variables based on simulated field plots:
TLS variables derived from simulated TLS plots:
TLS metrics derived from simulated TLS plots:
|
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.
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(s)
Juan Alberto Molina-Valero and Adela Martínez-Calvo.
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
See Also
tree.detection.single.scan, tree.detection.multi.scan, tree.detection.several.plots, distance.sampling,
normalize.
Examples
# 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 <- getwd()
# 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 <- getwd()
# 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)