plot_crowns() [WIP]

Author: ctoney

R/plot_crowns.R

@@ -1,21 +1,21 @@
-#' Display modeled tree crowns vertically projected on subplot boundaries
+#' Display modeled tree crowns projected vertically on subplot boundaries
 #'
 #' `plot_crowns()` draws vertically projected tree crowns as discs overlaid on
 #' subplot or microplot boundaries. The full four-subplot cluster, or
 #' individual subplots, can be displayed with trees `>= 5.0` in. (`12.7` cm)
-#' diameter, or individual microplots can be display with saplings (i.e., trees
-#' `< 5` in. diameter).
+#' diameter. Individual microplots can also be displayed with saplings (i.e.,
+#' trees `< 5` in. diameter).
 #'
 #' @param tree_list A data frame with tree records for one FIA plot.  Must have
 #' columns `SUBP` (FIA subplot number), `STATUSCD` (FIA integer tree status,
 #' `1` = live), `DIA` (tree diameter), `HT` (tree height), `ACTUALHT` (tree
 #' actual height, `ACTUALHT < HT` indicating a broken top), `DIST` (stem
 #' distance from subplot/microplot center), `AZIMUTH` (horizontal angle from
-#' subplot/microplot center to the stem location, in the range `0:359`), and
+#' subplot/microplot center to the stem location, in range `0:359`), and
 #' `CRWIDTH` (tree crown width).
 #' @param subplot Optional integer subplot number in the range `1:4` indicating
-#' a specific subplot for display. May be `NULL` or `NA` to display the full
-#' four-point cluster.
+#' a specific subplot for display. May be `NULL` or `NA` to display the whole
+#' four-point cluster plot.
 #' @param microplot A logical value, `TRUE` to display the modeled crowns of
 #' saplings overlaid of the microplot boundary of `subplot = n`. The default is
 #' `FALSE`. Ignored if `subplot` is not specified.
@@ -26,6 +26,11 @@
 #' given in meters, and tree diameters are assumed to be given in centimeters.
 #' **TODO: not currently implemented**
 #' @param main Character string giving the main plot title (on top).
+#' @param crown_col The color of tree crowns.
+#' @param stem_col The color of tree stems when plotting an individual subplot
+#' or microplot.
+#' @param subp_border_lwd The line width of subplot boundaries, a _positive_
+#' number, defaulting to `3`.
 #' @return
 #' The input, invisibly.
 #'
@@ -40,7 +45,26 @@
 #'             main = "plantation microplot 4")
 #' @export
 plot_crowns <- function(tree_list, subplot = NULL, microplot = FALSE,
-                        linear_unit = "ft", main = "") {
+                        linear_unit = "ft", main = "", crown_col = "#328e13",
+                        stem_col = "#b85e00", subp_border_lwd = 3){
+
+    if (missing(tree_list) || is.null(tree_list))
+        stop("'tree_list' is required", call. = FALSE)
+
+    if (!is.data.frame(tree_list))
+        stop("'tree_list' must be a data frame", call. = FALSE)
+
+    required_cols <- c("SUBP", "STATUSCD", "DIA", "HT", "ACTUALHT", "AZIMUTH",
+                       "DIST", "CRWIDTH")
+
+    if (!all(required_cols %in% colnames(tree_list)))
+        stop("'tree_list' is missing required columns", call. = FALSE)
+
+    if (!all(unique(tree_list$SUBP) %in% c(1, 2, 3, 4)))
+        stop("'tree_list$SUBP' contains invalid subplot numbers", call. = FALSE)
+
+    if (any(tree_list$AZIMUTH < 0) || any(tree_list$AZIMUTH > 360))
+        stop("'tree_list$AZIMUTH' contains values out of range", call. = FALSE)
 
     if (is.null(linear_unit))
         linear_unit <- "ft"
@@ -113,23 +137,23 @@ plot_crowns <- function(tree_list, subplot = NULL, microplot = FALSE,
                    gdalraster::g_envelope())
     names(rct) <- c("xmin", "xmax", "ymin", "ymax")
 
-    xlab <- paste0("x (", linear_unit, ")")
-    ylab <- paste0("y (", linear_unit, ")")
+    xlab <- sprintf("x (%s)", linear_unit)
+    ylab <- sprintf("y (%s)", linear_unit)
     gdalraster::plot_geom(fia_poly, xlab, ylab, main, border = "gray62",
-                          lwd = 3, bbox = rct)
+                          lwd = subp_border_lwd, bbox = rct)
 
     for (i in seq_len(nrow(trees_in))) {
-        # alternate green: #40c945
-        gdalraster::plot_geom(crowns[[i]], col = "#328e13", border = NA,
+        gdalraster::plot_geom(crowns[[i]], col = crown_col, border = NA,
                               add = TRUE)
         if (subplot) {
-            gdalraster::plot_geom(stems[[i]], col = "#b85e00", border = NA,
+            gdalraster::plot_geom(stems[[i]], col = stem_col, border = NA,
                                   add = TRUE)
         }
     }
 
     border_col <- grDevices::adjustcolor("gray62", alpha.f = 0.2)
-    gdalraster::plot_geom(fia_poly, border = border_col, lwd = 3, add = TRUE)
+    gdalraster::plot_geom(fia_poly, border = border_col, lwd = subp_border_lwd,
+                          add = TRUE)
 
     invisible(tree_list)
 }