crown_overlay_pct(): make tree_list the first argument and add to documentation

Author: ctoney

R/crown_overlay_pct.R

@@ -1,29 +1,35 @@
 #' Compute fractional tree canopy cover of a subplot/microplot by crown overlay
 #'
-#' @param sample_radius A numeric value giving the radius of the
+#' `crown_overlay_pct()` computes the proportion of a circular polygon covered
+#' by a given set of tree crowns modeled as discs and having spatially explicit
+#' stem locations. The sampled area is generally an FIA subplot with radius 24
+#' ft (7.315 m) for trees with diameter \verb{>= 5 in.} (12.7 cm), or an FIA
+#' microplot with radius 6.8 ft (2.073 m) for trees \verb{>= 1 in.} (2.54 cm)
+#' but \verb{< 5 in.} (12.7 cm) diameter (denoted as "saplings"). Stem locations
+#' are specified as distance and azimuth from subplot/microplot center.
+#'
+#' @param tree_list A data frame containing tree records for a
+#' subplot/microplot. Must have columns `DIST` (stem distance from
+#' subplot/microplot center in the same units as `sample_radius`), `AZIMUTH`
+#' (horizontal angle from subplot/microplot center to the stem location, in the
+#' range `0:359`) and `CRWIDTH` (tree crown width in the same units as
+#' `sample_radius` and `DIST`).
+#' @param sample_radius A numeric value giving the radius of the circular
 #' subplot/microplot.
-#' @param tree_list A data frame containing tree records for the
-#' subplot/microplot. Must have columns `DIST` (stem distance from subplot
-#' center in same units as `sample_radius`), `AZIMUTH` (horizontal angle from
-#' subplot/microplot center to the stem location, in the range `0:359`) and
-#' `CRWIDTH` (tree crown width in the same units as `sample_radius` and `DIST`).
-#' @param digits Optional integer number of digits to keep in the result
-#' (defaults to `1`, will be passed to `round()`).
+#' @param digits Optional integer indicating the number of digits to keep in the
+#' return value (defaults to `1`, will be passed to `round()`).
 #' @return
-#' An numeric value for tree canopy cover as percent of the subplot/microplot
-#' covered by a vertical projection of circular crowns.
+#' Estimated tree canopy cover as percent of the area specified by
+#' `sample_radius` that is covered by a vertical projection of circular
+#' crowns.
 #'
 #' @examples
-#' crown_overlay_pct(24, plantation[plantation$SUBP == 1 &
-#'                                  plantation$DIA >= 5, ])
+#' # subplot 1 of the `plantation` plot
+#' subp1_trees <- plantation[plantation$SUBP == 1 &
+#'                           plantation$DIA >= 5, ]
+#' crown_overlay_pct(subp1_trees, 24)
 #' @export
-crown_overlay_pct <- function(sample_radius, tree_list, digits = 1) {
-    if (missing(sample_radius) || is.null(sample_radius))
-        stop("'sample_radius' is required", call. = FALSE)
-
-    if (!(is.numeric(sample_radius) && length(sample_radius) == 1))
-        stop("'sample_radius' must be a single numeric value", call. = FALSE)
-
+crown_overlay_pct <- function(tree_list, sample_radius, digits = 1) {
     if (missing(tree_list) || is.null(tree_list))
         stop("'tree_list' is required", call. = FALSE)
 
@@ -33,6 +39,12 @@ crown_overlay_pct <- function(sample_radius, tree_list, digits = 1) {
     if (any(tree_list$AZIMUTH < 0) || any(tree_list$AZIMUTH > 360))
         stop("'tree_list$AZIMUTH' contains values out of range", call. = FALSE)
 
+    if (missing(sample_radius) || is.null(sample_radius))
+        stop("'sample_radius' is required", call. = FALSE)
+
+    if (!(is.numeric(sample_radius) && length(sample_radius) == 1))
+        stop("'sample_radius' must be a single numeric value", call. = FALSE)
+
     if (is.null(digits))
         digits <- 1
 
@@ -51,6 +63,6 @@ crown_overlay_pct <- function(sample_radius, tree_list, digits = 1) {
 
     tcc <- gdalraster::g_intersection(plot_poly, crowns_poly) |>
       gdalraster::g_area() / gdalraster::g_area(plot_poly) * 100
-    
+
     round(tcc, digits)
 }

man/crown_overlay_pct.Rd

@@ -4,5 +4,5 @@ test_that("crown_overlay_pct works", {
         matrix(nrow = 4, ncol = 3, byrow = TRUE) |>
         as.data.frame()
     colnames(trees) <- c("AZIMUTH", "DIST", "CRWIDTH")
-    expect_equal(round(crown_overlay_pct(24, trees)), 20)
+    expect_equal(round(crown_overlay_pct(trees, 24)), 20)
 })