Plot design optimization

The input data frames

Both TLS and field data from the same sample plots are required to compute the function. The TLS data introduced in tree.tls should have the same format as the data frame returned from the tree.detection.single.scan and tree.detection.multi.scan functions. Thus, each row must correspond to a detected tree and it must contain 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 and partial.occlusion. The data frame containing the field data must be inserted in the argument tree.field. Similar to the TLS data table, each row must correspond to a tree (specified in the columns id and tree) and the values for horizontal.distance, dbh, total.height and an integer value indicating whether the tree is dead (1) or alive (NA, specified in dead) must be included in the data frame.

When the distance sampling method for correction of occlusion effects was applied (function distance.sample, see “Stand-level” vignette), a list with the results in the output data frames from the aforesaid function can be introduced in tree.ds. The list must contain at least the data frame tree with the detection probabilities (P.hn, P.hn.cov, P.hr and P.hr.cov) for each tree. By default tree.ds is set to NULL and as a result, the calculations of the variables based on occlusion correction will not be performed.

Specifying designs of simulated plots

A vector containing the names of the plot designs can specify the plot designs ("fixed.area", "k.tree", "angle.count") that are to be considered for the simulations in plot.design. By default, this argument is set to NULL and all three plots designs will be considered.

Furthermore the argument plot.parameters allows for manually specifying the design of the simulated plots. Many differently-sized plots of the plot designs specified in plot.design are simulated. The list introduced in plot.parameters can include the following elements to customize the generated plots. The elements radius.max, k.tree.max and BAF.max define the maximum radius (in m), the maximum number of trees and the maximum BAF (in m$^2$/ha) respectively to which the sizes of circular fixed area, k-tree and angle-count plots respectively should increase. By default the values are set to radius.max = 25, k.tree.max = 50 and BAF.max = 4. The increment by which the sizes of circular fixed area and angle-count plots sequentially increase can also be customized by specifying the elements radius.increment and BAF.increment respectively. The default settings are radius.increment = 0.1 (in m) and BAF.increment = 0.1 (in m$^2$/ha). An additional element of the list can be num.trees defining the number of dominant trees per hectare (trees/ha). This value is needed for the calculation of dominant diamters and heights and is set to 100 trees/ha by default.

Further adjustable arguments

Similar to the other functions, the scan approach can be specified in scan.approach and is by default set to "multi". Metrics and variables of interest can be defined as a vector in var.metr. Thus, only those metrics and variables named in the vector are calculated. If not specified, var.metr is set to NULL and all possible metrics and variables are computed. The arguments dbh.min, h.min and max.dist can optionally define the minimum $dbh$, height and maximum distance of a tree to be included in the calculations. The default values are dbh.min = 4 (in cm), h.min = 1.3 (in m) and max.dist = NULL (no maximal distance is considered).

The argument dir.data should specify the working directory of the .txt files with the normalized reduced point clouds (output of normalize function). If not specified, it is set to NULL and the current working directory is assigned to it. The output files will be saved by default, since the argument save.result is set to TRUE, to the directory path indicated in dir.result. For each plot design (circular fixed area, k-tree and angle-count plots), a .csv file is created using the write.csv function from the utils package.

Output of the simulations function

The simulations function generates a list with one element for each plot design. The elements are data frames containing the simulated plot. Each row represents a simulated plot defined by their respective plot identification number id and their size determined by either radius, k or BAF depending on the plot design. The columns N, G, V, V.user, W.user, d, dg, dgeom, dharm, h, hg, hgeom, hharm, d.0, dg.0, dgeom.0, dharm.0, h.0, hg.0, hgeom.0 and hharm.0 display the stand-level variables based on the field data. The remaining columns contain the stand-level variables and metrics estimated for each plot based on the TLS data. As an example the data frame for circular fixed area plots is shown below.

head(simulations$fixed.area)

As described above, plots with increasing sizes are estimated and the corresponding variables an metrics are calculated. The plots are ordered from the smallest to the biggest. Plots with small radius can not be simulated for all sample plots (see table above), since trees not always enter, because the plots are too small. But plots with e.g. a radius of 20 m, can be simulated for all sample plots (see end of table below).

tail(simulations$fixed.area)

Computing correlations

The correlations function computes the correlations for all the plot designs that are introduces as elements of a list in simulations. The format and description must be the same as the output list of the simulations function. Also similar to the function relative.bias, the variables for which the correlations are to be calculated can be specified in variables. By default, this argument is set to variables = c("N", "G", "V", "d", "dg", "d.0", "h", "h.0"). If only one of the two above-mentioned correlation measures should be calculated, it can be specified in method. This argument is set to method = c("pearson", "spearman") by default and both correlation coefficients are computed.

cor <- correlations(simulations = simulations,
             variables = c("N", "G", "d", "dg", "d.0", "h", "h.0"),
             method = c("pearson", "spearman"), 
             save.result = FALSE, dir.result = NULL)
#> Computing correlations for fixed area plots
#>  (133.3 secs)
#> Computing correlations for k-tree plots
#>  (34.51 secs)
#> Computing correlations for angle-count plots
#>  (25.35 secs)

In addition to the calculation of the correlation measures, the function also performs tests of association and returns the p-values. The output of this function is a list containing the following three elements correlations, correlations.pval and opt.correlations. Each of them is a list including, if not otherwise specified (in method), two elements pearson and spearman. These two elements are lists again that include separate data frames for each plot design (circular fixed area, k-tree and angle-count plots). The data frames contain the corresponding correlation coefficients (in correlations), the calculated p-values (in correlations.pval) and the optimal correlations for a given plot size and field data estimate (in opt.correlations).

cor$correlations$pearson$fixed.area[20:26,1:15]

All mentioned data frames are divided into rows each of which represent a given plot size defined by radius (for circular fixed area plots), k (for k-tree plots) or BAF (for angle-count plots). The columns of the data frames in correlations (shown above) and correlations.pval (shown below) contain the calculated coefficients and p-values respectively for the corresponding correlation. The column names are composed of the two variables (e.g. N and N.tls) separated by . (giving N.N.tls) that were correlated as described for the relative.bias function.

cor$correlations.pval$pearson$fixed.area[20:26,1:15]

The data frames of the opt.correlations list (example shown below) are also divided into rows that represent the different plot sizes. For a given plot size and variable (specified in the argument variables), the best correlating TLS-based estimate and the corresponding correlation coefficient is displayed in this table. The columns named <variable>.metric (with <variable> being here N, G, d, dg, d.0, h and h.0) contain the TLS-based variable or metric that yielded the best correlation with the respective field data-based variable of the column name for a certain plot radius. The columns <variable>.cor display the measures of the respective correlations. That means, in the example shown here, the TLS-based estimate that yielded the best correlation with the field data based variable density (N) for circular fixed area plots with a radius of 4.4 m is ID.rho. And the correlation coefficient is 0.7286.

cor$opt.correlations$pearson$fixed.area[20:26,]

The correlations functions creates different files and saves them (if save.result = TRUE, default setting) to the directory indicated in dir.result. These files are, on the one hand, .csv files of the data frames in the lists correlations and opt.correlations created by means of the write.csv function from the utils package. These .csv files will be named as correlations.<plot design>.<method>.csv and opt.correlations.<plot design>.plot.<method>.csv with <plot design> being fixed.area.plot, k.tree.plot or angle.count.plot and <method> being pearson or spearman. On the other hand, interactive line charts representing the correlation coefficients will be created for each variable (selected in variables) as .html file using the saveWidget function in the htmlwidgets package. As an example, the interactive line chart for the variable height (h) and fixed area plots (pearson measure) is shown (correlations.h.fixed.area.pearson.html).

Visualizing correlations

In order to visualize the optimal correlations, the function optimize.plot.design creates heat maps and is applied as follows:

optimize.plot.design(correlations = cor$opt.correlations,
                     variables = c("N", "G", "d", "dg", "d.0", "h", "h.0"),
                     dir.result = NULL)

The function creates the heat maps based on the optimal correlation list (opt.correlations from the output of the correlations function) introduced in correlations. The introduced list must have the same format and description as the opt.correlation list. Similar to the other functions described above, the variables of interest can be selected in variables (default setting: variables = c("N", "G", "V", "d", "dg", "d.0", "h", "h.0")). This function generates interactive heat maps with the saveWidget function of the htmlwidgets package and saves these graphics to the directory indicated in dir.result (or by default to the working directory). For each plot design and correlation measure a plot is generated and named as opt.correlations.<plot design>.<method>.html where <plot design> can be fixed.area.plot, k.tree.plot or angle.count.plot and <method> either pearson or spearman according to the plot design and correlation measure.

As an example, the heat map of the pearson correlation coefficient for fixed area plots and pearson measure is provided and can be seen when opening the link (opt.correlations.fixed.area.plot.pearson.html).