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.
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)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)
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.
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.
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.
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’.
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.
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).
Vector containing the plot designs considered. By default, all plot designs will be considered (circular fixed area, k-tree and angle-count plots).
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.
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.
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.
Optional parameter to calculate volume when is not included in tree.tls input data.
Optional minimum dbh (cm) considered for detecting trees. By default it will be set at 4 cm.
Optional minimum h (m) considered for detecting trees. By default it will be set at 1.3 m.
Optional argument to specify the maximum horizontal distance considered in which trees will be included.
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.
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.
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.
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.
Juan Alberto Molina-Valero and Adela Martínez-Calvo.
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:
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.
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.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.
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. tools:::Rd_expr_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. tools:::Rd_expr_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. tools:::Rd_expr_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. tools:::Rd_expr_doi("10.5589/m08-046")
tree.detection.single.scan, tree.detection.multi.scan, tree.detection.several.plots, distance.sampling,
normalize.
# \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 <- 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)
# }
Run the code above in your browser using DataLab