metrics.variables {FORTLS} | R Documentation |
Compute Metrics and Variables for Terrestrial-Based Technologies Point Clouds
Description
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.
Usage
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)
Arguments
tree.tls |
Data frame with information about trees detected from terrestrial-based technologies point clouds data in the same format as |
tree.ds |
Optional list containing detection probabilities of trees with distance sampling methods. The format must be the same as the ‘Value’ obtained with |
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 |
Data frame containing parameters for circular fixed area, k-tree and angle-count plot designs. If there is a |
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 () 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.
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 whether 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
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 theplot.parameters
argument.k-tree plots, simulated only if a
k.tree
value is specified in theplot.parameters
argument.Angle-count plots, simulated only if a
BAF
value is specified in theplot.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).
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 Stratum, plot identification and radius:
Terrestrial-Based Technologies variables:
Terrestrial-Based Technologies metrics:
|
k.tree.plot |
If no value for Stratum, plot identification and k:
Terrestrial-Based Technologies variables:
Terrestrial-Based Technologies metrics:
|
angle.count.plot |
If no value for Stratum, plot identification and BAF:
Terrestrial-Based Technologies variables:
Terrestrial-Based Technologies metrics:
|
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 ‘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.
Note
In order to optimize plot designs and, therefore, for better use of metrics.variables
, other functions such as correlations
, relative.bias
and estimation.plot.size
should be used.
This function will be updated as new metrics are developed.
Author(s)
Juan Alberto Molina-Valero, Adela Martínez-Calvo.
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. 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
# 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)