add ac_to_ha() and ha_to_ac()

Author: ctoney

NAMESPACE

@@ -3,6 +3,7 @@
 export(.get_fia_plot_geom)
 export(.get_tree_list_xy)
 export(DEFAULT_TREE_COLUMNS)
+export(ac_to_ha)
 export(calc_crown_overlay)
 export(calc_crwidth)
 export(calc_ht_metrics)
@@ -11,6 +12,7 @@ export(cm_to_in)
 export(create_fia_owin)
 export(create_fia_ppp)
 export(ft_to_m)
+export(ha_to_ac)
 export(in_to_cm)
 export(load_tree_data)
 export(m_to_ft)

R/convert_units.R

@@ -1,7 +1,7 @@
-#' Convenience functions for length unit conversion
+#' Convenience functions for common unit conversions
 #'
 #' Functions to convert between US customary units and SI units for
-#' measurements of length used with tree data.
+#' measurements of length and area commonly used with tree data.
 #'
 #' @name convert_units
 #' @details
@@ -13,10 +13,18 @@
 #'
 #' `cm_to_in(x)` converts centimeters to inches.
 #'
+#' `ac_to_ha()` converts acres to hectares.
+#'
+#' `ha_to_ac()` converts hectares to acres.
+#'
 #' @param x Numeric vector of values to convert.
 #' @return
 #' A numeric vector of the converted values.
 #'
+#' @note
+#' The hectare (ha) is technically a non-SI unit of area that is [accepted for
+#' use with SI](https://en.wikipedia.org/wiki/International_System_of_Units#Non-SI_units_accepted_for_use_with_SI).
+#'
 #' @examples
 #' ft_to_m(1)
 #'
@@ -25,6 +33,10 @@
 #' in_to_cm(1)
 #'
 #' cm_to_in(1)
+#'
+#' ac_to_ha(1)
+#'
+#' ha_to_ac(1)
 #' @export
 ft_to_m <- function(x) {
     if (!is.numeric(x)) {
@@ -71,3 +83,27 @@ cm_to_in <- function(x) {
 
     x * 0.393701
 }
+
+#' @name convert_units
+#' @export
+ac_to_ha <- function(x) {
+    if (!is.numeric(x)) {
+        stop(cli::format_error(c(
+            "{.var x} must be a numeric vector",
+        "x" = "Invalid input type: {.cls {class(x)}}")))
+    }
+
+    x * 4046.8564224 / 10000
+}
+
+#' @name convert_units
+#' @export
+ha_to_ac <- function(x) {
+    if (!is.numeric(x)) {
+        stop(cli::format_error(c(
+            "{.var x} must be a numeric vector",
+        "x" = "Invalid input type: {.cls {class(x)}}")))
+    }
+
+    x * 10000 / 4046.8564224
+}

README.Rmd

@@ -49,7 +49,7 @@ pak::pak("firelab/FIAstemmap")
 
 ### Predict tree crown width
 
-The data frame `cw_coef` contains a curated set of linear regression coefficients for predicting crown width from stem diameter of tree species in the conterminous US (see `?cw_coef`). The method for crown width prediction attempts to avoid extrapolation beyond the range of the model fitting data by providing reasonable fall backs for the obvious cases. Details are given in the documentation for `calc_crwidth()`. The input is a data frame of tree records which must have columns `SPCD` (FIA species code), `STATUSCD` (FIA tree status code, `1` = live) and `DIA` (FIA tree diameter). FIA distribute data using US customary units with `DIA` given in inches, tree height in feet, etc. Convenience functions are provided for converting to and from SI units (`in_to_cm()`, `cm_to_in()`, `ft_to_m()`, `m_to_ft()`).
+The data frame `cw_coef` contains a curated set of linear regression coefficients for predicting crown width from stem diameter of tree species in the conterminous US (see `?cw_coef`). The method for crown width prediction attempts to avoid extrapolation beyond the range of the model fitting data by providing reasonable fall backs for the obvious cases. Details are given in the documentation for `calc_crwidth()`. The input is a data frame of tree records which must have columns `SPCD` (FIA species code), `STATUSCD` (FIA tree status code, `1` = live) and `DIA` (FIA tree diameter). FIA distribute data in [United States customary units](https://en.wikipedia.org/wiki/United_States_customary_units) with tree diameter given in inches, height in feet, and area in acres. Convenience functions are provided for converting to and from SI units[^1^](#footnotes) (`in_to_cm()`, `cm_to_in()`, `ft_to_m()`, `m_to_ft()`, `ac_to_ha()`, `ha_to_ac()`).
 
 The `plantation` dataset used here is an example tree list included in the package.
 
@@ -196,3 +196,7 @@ _Ecological Indicators_, Volume 142, 109271, https://doi.org/10.1016/j.ecolind.2
 [14] Burrill, Elizabeth A.; DiTommaso, Andrea M.; Turner, Jeffery A.; Pugh, Scott A.; Christensen, Glenn; Kralicek, Karin M.; Perry, Carol J.; Lepine, Lucie C.; Walker, David M.; Conkling, Barbara L. 2024. The Forest Inventory and Analysis Database, FIADB user guides, volume: database description (version 9.4), nationwide forest inventory (NFI). U.S. Department of Agriculture, Forest Service. 1016 p. [Online]. Available at: https://research.fs.usda.gov/understory/forest-inventory-and-analysis-database-user-guide-nfi.
 
 [15] Crookston, N.L. and A.R. Stage. (1999). Percent canopy cover and stand structure statistics from the Forest Vegetation Simulator. Gen. Tech. Rep. RMRS-GTR-24. Ogden, UT: U. S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 11 p. Available: https://research.fs.usda.gov/treesearch/6261.
+
+## Footnotes
+
+^1^ The hectare (ha) is technically a non-SI unit of area that is [accepted for use with SI](https://en.wikipedia.org/wiki/International_System_of_Units#Non-SI_units_accepted_for_use_with_SI).

README.md

@@ -71,10 +71,13 @@ model fitting data by providing reasonable fall backs for the obvious
 cases. Details are given in the documentation for `calc_crwidth()`. The
 input is a data frame of tree records which must have columns `SPCD`
 (FIA species code), `STATUSCD` (FIA tree status code, `1` = live) and
-`DIA` (FIA tree diameter). FIA distribute data using US customary units
-with `DIA` given in inches, tree height in feet, etc. Convenience
-functions are provided for converting to and from SI units
-(`in_to_cm()`, `cm_to_in()`, `ft_to_m()`, `m_to_ft()`).
+`DIA` (FIA tree diameter). FIA distribute data in [United States
+customary
+units](https://en.wikipedia.org/wiki/United_States_customary_units) with
+tree diameter given in inches, height in feet, and area in acres.
+Convenience functions are provided for converting to and from SI
+units[<sup>1</sup>](#footnotes) (`in_to_cm()`, `cm_to_in()`,
+`ft_to_m()`, `m_to_ft()`, `ac_to_ha()`, `ha_to_ac()`).
 
 The `plantation` dataset used here is an example tree list included in
 the package.
@@ -353,7 +356,7 @@ f <- system.file("extdata/mt_lnf_2022_1cond_tree.csv", package="FIAstemmap")
 tree_table <- load_tree_data(f)
 #> ! The data source does not have DIST and/or AZIMUTH.
 #> ℹ Fetching tree data
-#> ✔ Fetching tree data [17ms]
+#> ✔ Fetching tree data [14ms]
 #> 
 #> ℹ 910 tree records returned.
 
@@ -517,3 +520,9 @@ stand structure statistics from the Forest Vegetation Simulator.
 Gen. Tech. Rep. RMRS-GTR-24. Ogden, UT: U. S. Department of Agriculture,
 Forest Service, Rocky Mountain Research Station. 11 p. Available:
 <https://research.fs.usda.gov/treesearch/6261>.
+
+## Footnotes
+
+<sup>1</sup> The hectare (ha) is technically a non-SI unit of area that
+is [accepted for use with
+SI](https://en.wikipedia.org/wiki/International_System_of_Units#Non-SI_units_accepted_for_use_with_SI).

man/convert_units.Rd

@@ -11,6 +11,10 @@ test_that("convert_units works", {
     expect_equal(cm_to_in(1), 0.393701)
     expect_equal(cm_to_in(c(1, 10)), c(0.393701, 3.93701))
 
+    expect_equal(ac_to_ha(1), 0.404685642, tolerance = 1e-6)
+    expect_equal(ac_to_ha(c(1, 10)), c(0.404685642, 4.04685642),
+                 tolerance = 1e-6)
+
     x_ft <- 24
     x_m <- ft_to_m(x_ft)
     expect_equal(m_to_ft(x_m), x_ft, tolerance = 1e-4)
@@ -19,9 +23,15 @@ test_that("convert_units works", {
     x_cm <- in_to_cm(x_in)
     expect_equal(cm_to_in(x_cm), x_in, tolerance = 1e-4)
 
-    x <- "char"
+    x_ac <- 6.018046
+    x_ha <- ac_to_ha(x_ac)
+    expect_equal(ha_to_ac(x_ha), x_ac, tolerance = 1e-4)
+
+    x <- "non-numeric"
     expect_error(ft_to_m(x), "numeric vector")
     expect_error(m_to_ft(x), "numeric vector")
     expect_error(in_to_cm(x), "numeric vector")
     expect_error(cm_to_in(x), "numeric vector")
+    expect_error(ac_to_ha(x), "numeric vector")
+    expect_error(ha_to_ac(x), "numeric vector")
 })