Documents and tests find_snap() fun. Closes #168

r-package/NEWS.md

@@ -3,6 +3,10 @@
 -------------------------------------------------------
 # r5r v0.4-1 (dev)
 
+**Major changes**
+- New function `find_snap()` to help the used identify where in the street network
+the input of origin and destination points are snapped to. Closes [168](https://github.com/ipeaGIT/r5r/issues/168).
+
 **Bug fixes**
 - Fixed bug that prevented r5r from running without internet connection. Closes [#163](https://github.com/ipeaGIT/r5r/issues/163).
 

r-package/R/find_snap.R

@@ -1,14 +1,46 @@
 #' Find snapped locations of input points on street network
 #'
+#' @description R5 tries to snap origin and destination points to the street
+#' network in two rounds. First, it uses a search radius of 300 meters. If the
+#' first round is unsuccessful, then R5 expands the search radius to 1.6 km.
+#' Points that aren't linked to the street network after those two rounds are
+#' returned with `NA` coordinates and `found = FALSE`. Please note that the
+#' location of the snapped points depend on the transport mode set by the user.
+#'
+#'
 #' @param r5r_core a rJava object to connect with R5 routing engine
 #' @param points a spatial sf POINT object, or a data.frame
 #'               containing the columns 'id', 'lon', 'lat'
 #' @param mode string. Defaults to "WALK", also allows "BICYCLE", and "CAR".
 #'
 #' @return A data.table with the original points as well as their respective
-#'         snapped coordinates on the street network.
+#'         snapped coordinates on the street network and the Euclidean distance
+#'         between original points and their respective snapped location. Points
+#'         that could not be snapped show `NA` coordinates and `found = FALSE`.
+#'
+#' @family support functions
+#'
 #' @export
 #'
+#' @examples if (interactive()) {
+#'
+#' library(r5r)
+#'
+#' # build transport network
+#' path <- system.file("extdata/spo", package = "r5r")
+#' r5r_core <- setup_r5(data_path = path)
+#'
+#' # load origin/destination points
+#' points <- read.csv(file.path(path, "spo_hexgrid.csv"))
+#'
+#' # find where origin or destination points are snapped
+#' street_net <- find_snap(r5r_core,
+#'                         points = points,
+#'                         mode = 'CAR')
+#'
+#' stop_r5(r5r_core)
+#' }
+
 find_snap <- function(r5r_core,
                       points,
                       mode = "WALK") {

r-package/tests/testthat/test-find_snap.R

@@ -0,0 +1,43 @@
+context("find_snap function")
+
+# skips tests on CRAN since they require a specific version of java
+testthat::skip_on_cran()
+
+# load required data and setup r5r_core
+
+data_path <- system.file("extdata/spo", package = "r5r")
+r5r_core <- setup_r5(data_path, verbose = FALSE)
+points <- read.csv(file.path(data_path, "spo_hexgrid.csv"))
+
+
+
+
+
+# errors and warnings -----------------------------------------------------
+
+
+test_that("adequately raises errors", {
+
+  # invalid mode
+  expect_error( find_snap(r5r_core, points = points, mode = 'AAA') )
+
+  # invalid r5r_core
+  expect_error( find_snap(r5r_core='a', points = points, mode = 'WALK') )
+
+  # invalid r5r_core
+  expect_error( find_snap(r5r_core=r5r_core, points = 'a', mode = 'WALK') )
+
+})
+
+
+# adequate behavior ------------------------------------------------------
+
+
+test_that("output is correct", {
+
+  # expected behavior
+  expect_s3_class( find_snap(r5r_core, points = points, mode = 'WALK'), 'data.table' )
+
+})
+
+stop_r5(r5r_core)

r-package/tests_rafa/test_rafa.R

@@ -326,6 +326,8 @@ covr::function_coverage(fun=r5r::set_max_walk_distance, test_file("tests/testtha
 covr::function_coverage(fun=r5r::posix_to_string, test_file("tests/testthat/test-utils.R"))
 covr::function_coverage(fun=r5r::assert_points_input, test_file("tests/testthat/test-utils.R"))
 
+covr::function_coverage(fun=r5r::find_snap, test_file("tests/testthat/test-find_snap.R"))
+
 
 covr::function_coverage(fun=r5r::select_mode, test_file("tests/testthat/test-utils.R"))
 covr::function_coverage(fun=r5r::set_verbose, test_file("tests/testthat/test-utils.R"))