FORTLS (version 1.0.1)

metrics.variables: Compute Metrics and Variables for TLS Plots

Description

This function computes a set of TLS-based metrics and variables from the TLS point cloud data, which have a high potential to be related or used as direct estimates (in the case of TLS-based 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 point clouds.

Usage

metrics.variables(tree.list.tls,
                  distance.sampling = NULL,
                  plot.parameters,
                  dir.data = NULL, save.result = TRUE, dir.result = NULL)

Arguments

tree.list.tls

Data frame with information about trees detected from TLS point clouds data in the same format as tree.detection ‘Value’.

distance.sampling

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.

plot.parameters

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:

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.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.

save.result

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.

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.

Value

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):

fixed.area.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.

TLS metrics:

• 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.

• num.points, num.points.est, num.points.hom, num.points.hom.est: number of points and estimated number of points (points) belonging to trees 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).

• 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.

• 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).

k.tree.plot

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.

TLS metrics:

• N.tls, N.hn, N.hr, N.hn.cov, N.hr.cov, N.sh, num.points, num.points.est, num.points.hom, num.points.hom.est, 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, 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 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.

TLS metrics:

• 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.

• num.points, num.points.est, num.points.hom, num.points.hom.est: same description and format as indicated for the 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, 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.

Output Files

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 <U+2018>metrics.variables.<plot design>.csv<U+2019>, being <U+2018><plot design><U+2019> equal to <U+201C>fixed.area.plot<U+201D>, <U+201C>k.tree.plot<U+201D> or <U+201C>angle.count.plot<U+201D> according to the plot design.

Details

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, 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).

References

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. 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. 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<U+00AE>). Canadian Journal of Remote Sensing, 34(sup2), S426-S440. 10.5589/m08-046

See Also

tree.detection, tree.detection.multiple, distance.sampling, normalize.

Examples

# NOT RUN {
# }
# NOT RUN {
# 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.list.tls <- Rioja.data$tree.list.tls

# Download example of TXT file corresponding to plot 1 from Rioja data set

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


# Without considering distance sampling methods

met.var.TLS <- metrics.variables(tree.list.tls = tree.list.tls,
                                 plot.parameters = data.frame(radius = 10, k.tree = 10, BAF = 2),
                                 dir.data = dir.data, dir.result = dir.result)


# Considering distance sampling methods

ds <- distance.sampling(tree.list.tls)

met.var.TLS <- metrics.variables(tree.list.tls = tree.list.tls,
                                 distance.sampling = ds,
                                 plot.parameters = data.frame(radius = 10, k.tree = 10, BAF = 2),
                                 dir.data = dir.data, dir.result = dir.result)


# Considering strata
# Loading dataset with strata

plot.attributes <- Rioja.data$plot.attributes

# Merging the plot.attributes data set with strata information

tree.list.tls <- merge(tree.list.tls, plot.attributes, by = "id")

# Download example of TXT file corresponding to strata 2 (plot 9) from Rioja data set

download.file(url = "https://www.dropbox.com/s/5rwmbyn8tmqc48m/9.txt?raw=1",
              destfile = file.path(dir.data, "9.txt"), method = "wininet",
              mode = "wb")

plot.parameters <- data.frame(radius = c(10, 15), k.tree = c(8, 12), BAF = c(1.5, 2))

met.var.TLS <- metrics.variables(tree.list.tls = tree.list.tls,
                                 distance.sampling = ds,
                                 plot.parameters = plot.parameters,
                                 dir.data = dir.data, dir.result = dir.result)

# }