This function computes a set of metrics and variables from the Terrestrial-Based Technologies point cloud data, which have a high potential to be related or used as direct estimates (in the case of variables) of forest attributes at plot level. These can be obtained for different plot designs (circular fixed area, k-tree and angle-count plots). This function also includes methodologies for correcting occlusions generated in TLS single-scan point clouds.
metrics.variables(tree.tls, tree.ds = NULL, tree.field = NULL,
plot.design = c("fixed.area", "k.tree", "angle.count"),
plot.parameters = data.frame(radius = 25, k = 10, BAF = 2),
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 including TLS-based metrics and variables computed for plot designs considered. The list will contain one element per plot design considered (fixed.area.plot, k.tree.plot and angle.count.plot):
If no value for plot.radius is specified in the plot.parameters argument, NULL; otherwise, the data frame will include TLS metrics and variables estimated in a circular fixed area plot design (rows represent simulations). The data frame will have the following columns:
Stratum, plot identification and radius:
stratum: stratum identification encoded as a character string or
numeric. It must coincide with those included in the stratum column of tree.list.tls.
id: plot identification encoded as character string or
numeric. It will coincide with those included in the id
column of tree.list.tls and, if applicable, the
distance.sampling argument.
radius: radius (m) of the simulated plot.
Terrestrial-Based Technologies variables:
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 (see distance.sampling). These columns will not appear if the distance.sampling
argument is NULL.
N.sh: stand density (trees/ha) with correction of the
shadowing effect.
respectively).
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 (see distance.sampling). These columns are missing if 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 (see distance.sampling). 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.
Terrestrial-Based Technologies metrics:
n.pts, n.pts.est, n.pts.red, n.pts.red.est: number of points and estimated number of
points (points) belonging to trees normal sections (+/- 5 cm) in the
original point cloud (n.pts and n.pts.est,
respectively); and number of points and estimated number of points
(points) belonging to trees normal sections (+/- 5 cm) in the reduced
point cloud (n.pts.red and n.pts.red.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 (m).
mean.arit.z/rho/phi, mean.qua.z/rho/phi, mean.geom.z/rho/phi, mean.harm.z/rho/phi, median.z/rho/phi, mode.z/rho/phi: central tendency statistics for z, rho (horizontal distance) and r (euclidean distance) coordinates (arithmetic, quadratic, geometrical and harmonic means, median and mode, respectively).
var.z/rho/phi, sd.z/rho/phi, CV.z/rho/phi, D.z/rho/phi, ID.z/rho/phi, max.z/rho/phi, min.z/rho/phi: dispersion tendency statistics for z, rho and r coordinates (variance, standar deviation, coefficient of variation, range, interquartile range, maximum and minimum, respectively).
kurt.z/rho/phi, skw.z/rho/phi: curtosis and skewness, respectively.
L1.z/rho/phi, L2.z/rho/phi, L3.z/rho/phi, L4.z/rho/phi, L-CV.z/rho/phi, MAD-median.z/rho/phi, MAD-mode.z/rho/phi: L-moments of order 2, 3 and 4, median of the absolute deviations from the overall median and mode of the absolute deviations from the overall mode, respectively.
L3.mu.z/rho/phi, L4.mu.z/rho/phi: third and fourth central moments, respectively.
PA.2m, PA.mean.z, PA.mode.z: percentage of laser returns above 2 m, mean and mode, respectively.
PB.2m, PB.mean.z, PB.median.z, PB.mode.z: percentage of laser returns below 2 m, mean and mode, respectively.
weibull.b.z/rho/phi, weibull.c.z/rho/phi: scale and shape parameters, respectively, for Weibull distribution fitted for z coordinates of TLS point clouds relative to ground level.
If no value for k.tree is specified in the plot.parameters argument, NULL; otherwise, the data frame will include TLS metrics and variables estimated in the k-tree plot design (rows represent simulations). The data frame will include the following columns (same description and format as indicated in fixed.area.plot element):
Stratum, plot identification and k:
stratum: stratum identification encoded as character string or
numeric. It must coincide with those included in the stratum column of tree.list.tls.
id: plot identification encoded as character string or numeric value. It will coincide with those included in id
column of tree.list.tls or, if applicable, the
distance.sampling argument.
k: number of trees in the simulated plot.
Terrestrial-Based Technologies variables:
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
Terrestrial-Based Technologies metrics:
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 is specified in the plot.parameters argument, NULL; otherwise, the data frame will include TLS metrics and variables estimated in the angle-count plot design (rows represent simulations). The data frame will include the following columns:
Stratum, plot identification and BAF:
stratum: stratum identification encoded as character string or
numeric. It must coincide with those included in stratum column of tree.list.tls.
id: plot identification encoded as character string or numeric. It will coincide with those included in the id column of tree.list.tls.
BAF: BAF (\({m}^{2}/ha\)) of the simulated plot.
Terrestrial-Based Technologies variables:
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.
fixed.area.plot element.
G.tls: same description and format as indicated for the
fixed.area.plot element.
G.pam: stand basal area (\({m}^{2}/ha\)) with occlusion correction
based on gap probability attenuation with distance from TLS.
V.tls: same description and format as indicated for the
fixed.area.plot element.
V.pam: stand volume (\({m}^{3}/ha\)) with occlusion correction based
on gap probability attenuation with distance from 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
Terrestrial-Based Technologies metrics:
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 for the fixed.area.plot element.
Data frame with information about trees detected from terrestrial-based technologies point clouds data in the same format as tree.detection.single.scan or tree.detection.multi.scan ‘Values’.
Optional list containing detection probabilities of trees with distance sampling methods. The format must be the same as the ‘Value’ obtained with distance.sampling. If this argument is not specified by the user, it will be set to NULL by default and, as a consequence, TLS metrics using distance sampling based correction will not be calculated for circular fixed area and 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.
h.dist: horizontal distance (m) from plot
centre to tree centre. Centres of the field plots must coincide with
centres of their corresponding Terrestrial-based technologies plots.
dbh: tree diameter (cm) at breast height (1.3 m).
h: tree total height (m).
h.blc: height based live crown (m) (optional).
h.bdc: height based dead crown (m) (optional).
v.user: tree volume (m^3) (optional).
w.user: tree biomass (Mg) (optional).
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).
Data frame containing parameters for circular fixed area, k-tree and angle-count plot designs. If there is a stratum column in the tree.list.tls argument, it must have the same number of rows as strata values and they must be named using strata encoding. If plot parameters are not specified, the corresponding plot designs will not be considered in the function. If no parameter is specified, the function will stop giving an error message! The parameters are as follows:
radius: plot radius (m) considered for circular fixed area plots. Absence of this argument rules out this plot design.
k.tree: number of trees (trees) considered for k-tree plots. Absence of this argument rules out this plot design.
BAF: basal area factor (\({m}^{2}/ha\)) considered for angle-count plots. Absence of this argument rules out this plot design.
num.trees: number of dominant trees per ha (tree/ha), i.e. those with largest dbh, considered for calculating dominant diameters and heights. In the absence of this argument, the number will be assumed to be 100 trees/ha.
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.data, 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 consequence, the current working directory of the R process will be
assigned to dir.dat during the execution.
Optional logical which indicates whether 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 consequence, the output files will be 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.
After computing metrics and variables, if the save.result argument is TRUE, the function will save the elements in the list described in ‘Value’ (fixed.area.plot, k.tree.plot and angle.count.plot), which are different from NULL as CSV files. Data frames are written without row names in the dir.result directory by using write.csv function from the utils package. The pattern used for naming these files is ‘metrics.variables.<plot design>.csv’,
being ‘<plot design>’ equal to “fixed.area.plot”, “k.tree.plot” or “angle.count.plot”
according to the plot design.
Juan Alberto Molina-Valero, Adela Martínez-Calvo.
This function also works for several plots. In this case, a column named "id" to identify plots (string character or numeric) must be included in the tree.list.tls database argument. This must coincide with the corresponding "id" assigned in normalize to TXT files saved in dir.data (for more details see normalize). In addition, if there are several strata, they can be processed separately according to plot.parameters values (where each row will represent one stratum). If tree.list.tls does not include a specific "stratum" column, it will be assumed to have only one stratum, which will be encoded according to rownames(plot.parameters)[1].
Using TLS data, this function computes metrics and estimations of variables (see ‘Value’) for plot design specified in the plot.parameters argument. 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 value is
specified in the plot.parameters argument.
k-tree plots, simulated only if a k.tree value is
specified in the plot.parameters argument.
Angle-count plots, simulated only if a BAF value is
specified in the plot.parameters argument.
Volume is estimated modelling stem profile as a paraboloid and calculating the volumes of revolution; where trees dbh are estimated in tree.detection.single.scan and tree.detection.multi.scan, and total heights are estimated as percentile 99 of z coordinate of points delimited by Voronoi polygons.
Regarding occlusion corrections for estimating variables, apart from distance sampling methods considered in distance.sampling, another occlusion corection based on correcting the shadowing effect (Seidel & Ammer, 2014) has been included to estimate some variables in circular fixed area and k-tree plots. In the case of angle-count plots, occlusion corrections are based on gap probability attenuation with distance to TLS depending on Poisson model (Strahler et al., 2008; Lovell et al., 2011).
IUFRO (1959). Standarization of symbols in forest mensuration. Vienna, Austria, IUFRO.
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{
# Establishment of working directories (optional)
# By default here we propose the current working directory of the R process
dir.data <- getwd()
dir.result <- getwd()
# Loading example data included in FORTLS
data("Rioja.data")
tree.tls <- Rioja.data$tree.tls
tree.tls <- tree.tls[tree.tls$id == "1", ]
# Download example of TXT file corresponding to plot 1 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")
# Considering distance sampling methods (only for single-scan approaches)
# ds <- distance.sampling(tree.tls)
met.var.TLS <- metrics.variables(tree.tls = tree.tls,
# tree.ds = ds,
plot.parameters = data.frame(radius = 10, k = 10, BAF = 2),
dir.data = dir.data, dir.result = dir.result)
# }
Run the code above in your browser using DataLab