calc_tcc_metrics() [WIP]

Author: ctoney

R/calc_tcc_metrics.R

@@ -1,39 +1,40 @@
 #' Predict plot-level canopy cover from individual tree measurements
 #'
 #' `calc_tcc_metrics()` computes plot-level predicted tree canopy cover (TCC)
-#' from tree list data. A full set of stand structure components used to derive
-#' the plot-level prediction are included in the output by default (see
+#' from tree list data. By default, a full set of stand structure components
+#' used to derive the plot-level TCC prediction are included in the output (see
 #' Details).
 #'
 #' @details
-#' This function supports two alternative methods for predicting plot-level TCC.
-#'
-#' The default method requires individual tree coordinates to be provided in the
-#' input, as distance and azimuth from subplot centers for trees with diameter
-#' \verb{>= 5 in.} (12.7 cm), or from microplot centers for "sapling" trees with
-#' diameter \verb{>= 1 in.} (2.54 cm) but \verb{< 5 in.} (12.7 cm). This method
-#' involves spatially explicit stem-mapping to account for crown overlap of the
-#' mature trees, along with empirical modeling of the understory sapling
-#' contribution to total canopy cover (Toney et al. 2009). The empirical model
-#' for the sapling component also uses overstory tree point pattern as one of
-#' its predictor variables (based on Ripley's K function, Ripley 1977).
+#' This function provides two methods for predicting plot-level TCC.
+#'
+#' The default "stem-map" method requires individual tree coordinates to be
+#' included in the input as distance and azimuth from subplot centers for trees
+#' with diameter \verb{>= 5 in.} (12.7 cm), and from microplot centers for
+#' "saplings" having diameter \verb{>= 1 in.} (2.54 cm) but \verb{< 5 in.}
+#' (12.7 cm). This method involves mapping trees spatially to account for crown
+#' overlap, along with empirical modeling of the understory sapling contribution
+#' to total canopy cover (Toney et al. 2009). The empirical model for the
+#' sapling component also uses the overstory tree point pattern as a predictor
+#' variable (based on Ripley's K function, Ripley 1977).
 #'
 #' Alternatively, plot-level TCC can be predicted using a simplified approach
 #' that does not include exact stem placement (`stem_map = FALSE`). A random
 #' arrangement of stems is assumed in that case. This is the method used to
-#' estimate percent canopy cover in the Forest Vegetation Simulator (Crookston
-#' and Stage 1999).
+#' estimate tree canopy cover in the Forest Vegetation Simulator (Crookston and
+#' Stage 1999).
 #'
-#' The stem-map method requires computation of several stand structure metrics
-#' which are components of the overall model used to derive the plot-level TCC
-#' estimate. These include:
+#' Both methods require estimates of individual tree crown width, which are
+#' computed with `calc_crwidth()` if not provided in the input tree list.
+#'
+#' The stem-map method also requires computation of several stand structure
+#' metrics, which are components of the overall model used to derive a
+#' plot-level TCC estimate. These additional variables include:
 #'
-#' * individual tree crown widths via `calc_crwidth()` (if not provided in the
-#' input tree list)
 #' * individual subplot and microplot crown overlays via `calc_crown_overlay()`
 #' * a stand height metric (`meanTreeHtBAW`) via `calc_ht_metrics()`
 #' * plot-level counts of mature trees and saplings
-#' * descriptive statistics for the tree spatial point pattern via
+#' * descriptive spatial statistics for the overstory tree point pattern via
 #' `create_fia_ppp() |> spatstat.explore::Lest()`
 #'
 #'
@@ -46,7 +47,10 @@
 #' the input data frame will have the columns specified in
 #' [DEFAULT_TREE_COLUMNS] (see `?DEFAULT_TREE_COLUMNS`). Potentially, only a
 #' subset of those columns will be needed depending on values given for the
-#' arguments `stem_map`, `full_output` and `crwidth_col` described below.
+#' arguments `stem_map` and `full_output` described below. If the input data
+#' frame has a column named `"CRWIDTH"` it will be used for tree crown width
+#' values, otherwise, crown widths will be calculated with a call to
+#' `calc_crwidth()`.
 #' @param stem_map A logical value indicating whether to map individual trees
 #' explicitly using coordinates specified in terms of distance and azimuth from
 #' subplot/microplot centers. The default is `TRUE`, in which case the input
@@ -59,11 +63,6 @@
 #' output list includes subplot-level TCC estimates, live tree and sapling
 #' counts, stand height metrics, and point pattern statistics, depending on the
 #' value given for `stem_map` (see Details).
-#' @param crwidth_col The name of a column in `tree_list` containing the
-#' individual tree crown widths (case-sensitive). Defaults to `"CRWIDTH"`. If
-#' the given column name does not exist in the input data frame, or this
-#' argument is set to `NULL`, then crown widths will be computed with a call to
-#' `calc_crwidth()`.
 #' @param digits Optional integer indicating the number of digits to keep in the
 #' return values (defaults to `1`). May be passed to `calc_crwidth()` and
 #' `calc_ht_metrics()`.
@@ -85,7 +84,7 @@
 #' Statistical Society: Series B (Methodological)_, 39(2): 172–192.
 #' \url{https://doi.org/10.1111/j.2517-6161.1977.tb01615.x}.
 #'
-#' Toney, C, J.D. Shaw and M.D. Nelson. 2009. A stem-map model for predicting
+#' Toney, C., J.D. Shaw and M.D. Nelson. 2009. A stem-map model for predicting
 #' tree canopy cover of Forest Inventory and Analysis (FIA) plots. In:
 #' McWilliams, Will; Moisen, Gretchen; Czaplewski, Ray, comps. _Forest Inventory
 #' and Analysis (FIA) Symposium 2008_; October 21-23, 2008; Park City, UT. Proc.
@@ -98,10 +97,36 @@
 #' [create_fia_ppp()]
 #'
 calc_tcc_metrics <- function(tree_list, stem_map = TRUE, full_output = TRUE,
-                             crwidth_col = "CRWIDTH", digits = 1) {
+                             digits = 1) {
+
+    if (!(is.logical(stem_map) && length(stem_map) == 1))
+        stop("'stem_map' must be a single logical value", call. = FALSE)
+
+    if (!(is.logical(full_output) && length(full_output) == 1))
+        stop("'full_output' must be a single logical value", call. = FALSE)
+
+    X <- NULL  # spatstat point pattern object
+    if (stem_map) {
+        # validate the input tree list for stem-mapping and get X
+        X <- create_fia_ppp(tree_list)
+    }
 
+    ht_metrics <- NULL
+    if (stem_map || full_output) {
+        # validate the input tree list for stand height calc and get metrics
+        ht_metrics <- calc_ht_metrics()
+    }
 
+    if (!("CRWIDTH" %in% colnames(tree_list)))
+        tree_list$CRWIDTH <- calc_crwidth(tree_list)
 
 
+    # estimate of the L-function (Besag's transformation of Ripley's K) for
+    # r = 0:12 feet
+    if (stem_map) {
+        L <- spatstat.explore::Lest(X, r = 0:12)
+        # mean of L at r = 6, 8, 10, 12 ft (Ripley's isotropic edge correction)
+        L_mean <- mean(L$iso[c(7, 9, 11, 13)])
+    }
 
 }