more input options for h3_to_polygon()

NEWS.md

@@ -2,8 +2,9 @@
 
   * Removed `nearest_neighbour()`, its fundamentally flawed. 
   * Simplified output of `get_local_ij()` to a matrix when simple = TRUE
-  * Improved outputs from `point_to_h3()`
-  * Efficiency improvements to `point_to_h3()` and `polyfill()`
+  * Improved outputs from `h3_to_point()`
+  * Efficiency improvements to `h3_to_point()` and `polyfill()`
+  * `h3_to_point()`, `h3_to_polygon()`, and `polyfill()` now take a wider range of input objects.
 
 # v. 0.6
 

R/core_api.R

@@ -314,22 +314,34 @@ h3_to_point <- function(h3_address = NULL, simple = TRUE) {
 #'
 #' This function takes an H3 address and returns its bounding shape (usually a
 #' hexagon) in WGS84.
-#' @inheritParams is_valid
-#' @return By default, an `sfc_POLYGON` object of `length(h3_address)`.
+#' @param input Character; 15-character address generated by H3, or a
+#'   vector or list of same, or a data frame where the first column contains H3
+#'   addresses.
+#' @param simple Logical; whether to return an `sfc_POLYGON` object or an `sf`
+#'   data frame containing both inputs and outputs.
+#' @return By default, an `sfc_POLYGON` object of `length(input)`. If an
+#'   appropriately formatted data frame is supplied, an `sf` data frame
+#'   containing input attributes and geometry.
 #' @import V8
 #' @examples
 #' # What is the hexagon over the Brisbane Town Hall at resolution 10?
-#' brisbane_hex_10 <- h3_to_polygon(h3_address = '8abe8d12acaffff')
+#' brisbane_hex_10 <- h3_to_polygon(input = '8abe8d12acaffff')
 #'
 #' # Give me some of the hexes over Brisbane Town Hall as an sf object
 #' bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326)
 #' bth_addys <- unlist(point_to_h3(bth, res = seq(10, 15)), use.names = FALSE)
-#' bth_hexes <- h3_to_polygon(h3_address = bth_addys)
+#' bth_hexes <- h3_to_polygon(input = bth_addys)
 #' plot(bth_hexes, axes = TRUE)
 #' @importFrom sf st_polygon st_sfc st_sf
 #' @export
 #'
-h3_to_polygon <- function(h3_address = NULL, simple = TRUE) {
+h3_to_polygon <- function(input = NULL, simple = TRUE) {
+
+  if(inherits(input, 'data.frame')) {
+    h3_address <- as.character(input[[1]])
+  } else {
+    h3_address <- unlist(input, use.names = FALSE)
+  }
 
   if(any(is_valid(h3_address)) == FALSE) {
     stop('Invalid H3 address detected.')
@@ -352,12 +364,16 @@ h3_to_polygon <- function(h3_address = NULL, simple = TRUE) {
   hexes$geometry <- lapply(hexes$geometry, function(hex) {
     sf::st_polygon(list(hex))
   })
-
   hexes$geometry <- sf::st_sfc(hexes$geometry, crs = 4326)
 
   if(simple == TRUE) {
     hexes$geometry
   } else {
-   sf::st_sf(hexes, stringsAsFactors = FALSE)
+    if(inherits(input, 'data.frame')) {
+      sf::st_sf(cbind(input[, c(2:dim(input)[2]), drop = FALSE], hexes),
+                stringsAsFactors = FALSE)
+    } else {
+      sf::st_sf(hexes, stringsAsFactors = FALSE)
   }
 }
+}

tests/testthat/test_core_api.R

@@ -164,7 +164,7 @@ test_that('h3_to_point returns an appropriate dataset',
           ))
 
 # h3_to_geo_boundary
-test_that('h3 to geo boundary returns an appropriate dataset',
+test_that('h3 to polygon returns an appropriate dataset',
           c(
             expect_error(h3_to_polygon(h3_address = 'whereami')),
             val1 <- h3_to_polygon('8abe8d12acaffff'),
@@ -174,7 +174,21 @@ test_that('h3 to geo boundary returns an appropriate dataset',
             expect_equal(val1[[1]][[1]][1,2], -27.46896347),
             expect_is(val1, 'sfc_POLYGON'),
             expect_is(val2, 'sf'),
+            expect_equal(as.character(sf::st_geometry_type(val2)), 'POLYGON'),
             expect_identical(val1, val2$geometry),
             expect_equal(names(val2), c('h3_address', 'h3_resolution', 'geometry')),
-            expect_equal(sf::st_crs(val1)$epsg, 4326)
-          ))
+            expect_equal(sf::st_crs(val1)$epsg, 4326),
+            # data frame inputs
+            df <- data.frame('h3_resolution_7' = c('8abe8d12acaffff',
+                                                   '8abe8d12acaffff',
+                                                   '8abe8d12acaffff'),
+                             'ID' = seq(3)),
+            val3 <- h3_to_polygon(df),
+            expect_is(val3, 'sfc_POLYGON'),
+            expect_equal(as.character(sf::st_geometry_type(val3[[1]])), 'POLYGON'),
+            val4 <- h3_to_polygon(df, simple = FALSE),
+            expect_is(val4, 'sf'),
+            expect_equal(val3, val4$geometry),
+            expect_error(h3_to_polygon(df[ , c(2,1)], simple = FALSE))
+            )
+)

vignettes/intro-to-h3jsr.Rmd

@@ -65,7 +65,7 @@ nc_all_res <- point_to_h3(nc_pts, res = seq(0, 15), simple = FALSE)
 head(nc_all_res[, c(1:5)])
 ```
 
-H3 addresses can be translated back to a point at a given resolution with `point_to_h3()`. A polygon (almost always a hexagon), can be retrieved with `h3_to_polygon()`.
+H3 addresses can be translated back to a point at a given resolution with `h3_to_point()`. A polygon (almost always a hexagon), can be retrieved with `h3_to_polygon()`.
 
 ```{r 'c4'}
 # plot a few
@@ -141,7 +141,7 @@ A 'donut' of addresses at exactly *n* steps is obtained with `get_ring()`.
 get_ring(h3_address = '86be8d12fffffff', ring_size = 2)
 ```
 
-These address lists can all be spatialised with `set_to_multipolygon()`.
+These address lists can all be spatialised with `set_to_multipolygon()`, which returns the polygonised outline of a collection of H3 addresses.
 
 ```{r 'stmp'}
 patch <- get_kring(h3_address = '86be8d12fffffff', ring_size = 2)
@@ -193,7 +193,7 @@ ggplot() +
   coord_sf()
 ```
 
-A representation like this can be 'compacted' with `compact()`
+A representation like this can be 'compacted' with `compact()`.
 
 ```{r 'compact'}
 ashe_comp <- compact(ashe_7$h3_address)