extract() documentation and tests

Author: dhersz

NAMESPACE

@@ -1,3 +1,4 @@
 # Generated by roxygen2: do not edit by hand
 
 export(assert_osmium_is_installed)
+export(extract)

R/extract.R

@@ -1,9 +1,60 @@
+#' Create geographical extracts from an OSM file
+#'
+#' Creates geographical extracts from an OSM data file or an OSM history file.
+#' The geographical extent can be given either as a bounding box or as a
+#' (multi)polygon.
+#'
+#' @param input_path A string. The path to the OSM data/history file whose
+#'   extent should be extracted from. Please see [file_formats] for a list of
+#'   supported file formats.
+#' @param extent Either a `POLYGON` or a `MULTIPOLYGON` `sf` object with only
+#'   one feature or a `bbox` object, created by [sf::st_bbox].
+#' @param output_path A string. The path to the file where the output should be
+#'   written to. Please see [file_formats] for a list of supported file formats.
+#' @param overwrite A logical. Whether existing files should be overwritten by
+#'   the output. Defaults to `FALSE`.
+#' @param echo_cmd A logical. Whether to print the Osmium command generated by
+#'   the function call to the screen. Defaults to `FALSE`.
+#' @param echo A logical. Whether to print the standard output and error
+#'   generated by the Osmium call to the screen. Defaults to `TRUE`.
+#' @param spinner A logical. Whether to show a reassuring spinner while the
+#'   Osmium call is being executed. Defaults to `TRUE`.
+#'
+#' @return The normalized path to the output file.
+#'
+#' @examplesIf identical(tolower(Sys.getenv("NOT_CRAN")), "true")
+#' pbf_path <- system.file("extdata/cur.osm.pbf", package = "rosmium")
+#'
+#' file.size(pbf_path)
+#'
+#' # buffering the pbf bounding box 4000 meters inward and using the result
+#' # extent to extract the osm data inside it. transforming the crs because
+#' # inward buffers only work with project crs
+#'
+#' lines <- sf::st_read(pbf_path, layer = "lines", quiet = TRUE)
+#' bbox <- sf::st_bbox(lines)
+#' bbox_polygon <- sf::st_as_sf(sf::st_as_sfc(bbox))
+#' smaller_bbox_poly <- sf::st_buffer(
+#'   sf::st_transform(bbox_polygon, 5880),
+#'   -4000
+#' )
+#' smaller_bbox_poly <- sf::st_transform(smaller_bbox_poly, 4326)
+#'
+#' output_path <- extract(
+#'   pbf_path,
+#'   smaller_bbox_poly,
+#'   tempfile(fileext = ".osm.pbf")
+#' )
+#'
+#' file.size(output_path)
+#'
+#' @export
 extract <- function(input_path,
-                    borders,
+                    extent,
                     output_path,
                     overwrite = FALSE,
-                    echo = TRUE,
                     echo_cmd = FALSE,
+                    echo = TRUE,
                     spinner = TRUE) {
   assert_osmium_is_installed()
 
@@ -12,10 +63,10 @@ extract <- function(input_path,
   checkmate::assert_logical(echo, any.missing = FALSE, len = 1)
   checkmate::assert_logical(echo_cmd, any.missing = FALSE, len = 1)
   checkmate::assert_logical(spinner, any.missing = FALSE, len = 1)
-  assert_borders(borders)
+  assert_extent(extent)
   assert_output_path_multi_ext(output_path, overwrite)
 
-  border_arg <- create_border_input(borders)
+  border_arg <- create_border_input(extent)
   output_arg <- paste0("--output=", output_path)
   overwrite_arg <- if (overwrite) "--overwrite" else character()
 
@@ -71,20 +122,20 @@ border_input_from_polygon <- function(x) {
   return(input)
 }
 
-check_borders <- function(borders) {
-  multi_class_res <- checkmate::check_multi_class(borders, c("sf", "bbox"))
+check_extent <- function(extent) {
+  multi_class_res <- checkmate::check_multi_class(extent, c("sf", "bbox"))
   if (!isTRUE(multi_class_res)) return(multi_class_res)
 
-  if (inherits(borders, "bbox")) {
+  if (inherits(extent, "bbox")) {
     is_numeric_len_4 <- checkmate::test_numeric(
-      borders,
+      extent,
       finite = TRUE,
       any.missing = FALSE,
       len = 4
     )
 
     is_correctly_named <- checkmate::test_subset(
-      names(borders),
+      names(extent),
       choices = c("xmin", "ymin", "xmax", "ymax")
     )
 
@@ -97,7 +148,7 @@ check_borders <- function(borders) {
       )
     }
   } else {
-    if (nrow(borders) > 1) {
+    if (nrow(extent) > 1) {
       return(
         paste0(
           "sf object must contain only one feature. Hint: try using ",
@@ -106,7 +157,7 @@ check_borders <- function(borders) {
       )
     }
 
-    geometry_type <- as.character(sf::st_geometry_type(borders))
+    geometry_type <- as.character(sf::st_geometry_type(extent))
     if (! geometry_type %in% c("POLYGON", "MULTIPOLYGON")) {
       msg <- paste0(
         "Geometry type of sf object must be either POLYGON or MULTIPOLYGON. ",
@@ -128,4 +179,4 @@ check_borders <- function(borders) {
   return(TRUE)
 }
 
-assert_borders <- checkmate::makeAssertionFunction(check_borders)
+assert_extent <- checkmate::makeAssertionFunction(check_extent)

man/extract.Rd

@@ -13,36 +13,36 @@ geomcollection <- sf::st_as_sf(
 )
 
 tester <- function(input_path = pbf_path,
-                   borders = smaller_bbox_poly,
+                   extent = smaller_bbox_poly,
                    output_path = tempfile(fileext = ".osm.pbf"),
                    overwrite = FALSE,
-                   echo = TRUE,
                    echo_cmd = FALSE,
+                   echo = TRUE,
                    spinner = TRUE) {
-  extract(input_path, borders, output_path, overwrite, echo, echo_cmd, spinner)
+  extract(input_path, extent, output_path, overwrite, echo_cmd, echo, spinner)
 }
 
 test_that("input should be correct", {
   expect_error(tester(1))
   expect_error(tester("a.osm.pbf"))
 
-  expect_error(tester(borders = unclass(bbox)))
+  expect_error(tester(extent = unclass(bbox)))
 
   bad_bbox <- bbox
   bad_bbox[4] <- Inf
-  expect_error(tester(borders = bad_bbox))
+  expect_error(tester(extent = bad_bbox))
   bad_bbox[4] <- NA
-  expect_error(tester(borders = bad_bbox))
+  expect_error(tester(extent = bad_bbox))
   bad_bbox[4] <- 25
   names(bad_bbox)[4] <- "oi"
-  expect_error(tester(borders = bad_bbox))
+  expect_error(tester(extent = bad_bbox))
   names(bad_bbox)[4] <- "ymax"
   bad_bbox[5] <- 12
-  expect_error(tester(borders = bad_bbox))
+  expect_error(tester(extent = bad_bbox))
 
-  expect_error(tester(borders = rbind(bbox_polygon, bbox_polygon)))
-  expect_error(tester(borders = linestring))
-  expect_error(tester(borders = geomcollection))
+  expect_error(tester(extent = rbind(bbox_polygon, bbox_polygon)))
+  expect_error(tester(extent = linestring))
+  expect_error(tester(extent = geomcollection))
 
   tmpfile <- tempfile(fileext = ".osm.pbf")
   file.create(tmpfile)
@@ -79,9 +79,33 @@ test_that("works with bbox and results in same output as with equiv poly", {
   tmpfile <- tempfile(fileext = ".osm.pbf")
   smaller_bbox <- sf::st_bbox(smaller_bbox_poly)
 
-  result <- tester(borders = smaller_bbox, output_path = tmpfile)
+  result <- tester(extent = smaller_bbox, output_path = tmpfile)
   expect_identical(result, normalizePath(tmpfile))
 
   # same snapshot as the above test, which was generated with the polygon
   expect_snapshot_file(tmpfile, name = "tester_default_output")
 })
+
+test_that("overwrite arguments works", {
+  tmpfile <- tempfile(fileext = ".osm.pbf")
+
+  result <- tester(output_path = tmpfile)
+
+  expect_error(tester(output_path = tmpfile, overwrite = FALSE))
+  expect_no_error(tester(output_path = tmpfile, overwrite = TRUE))
+})
+
+test_that("echo_cmd argument works", {
+  # using spinner = FALSE to make sure it doesn't mess up with the test
+  expect_output(
+    a <- tester(echo_cmd = TRUE, spinner = FALSE),
+    regexp = "^Running osmium extract"
+  )
+
+  output <- capture.output(a <- tester(echo_cmd = FALSE, spinner = FALSE))
+  expect_identical(output, character(0))
+})
+
+# spinner doesn't work on non-interactive sessions and none of the queries calls
+# we have generated output anything to stdout/stderr, so we're skipping the
+# 'spinner' and 'echo' argument tests