Merge pull request #155 from ITSLeeds/oe_search

Add function for #154

R/download.R

@@ -5,19 +5,19 @@
 #' the package. The url is specified through the parameter `file_url`.
 #'
 #' @details This function runs several checks before actually downloading a new
-#'   file, to avoid overloading the OSM providers. The first step is the
+#'   file to avoid overloading the OSM providers. The first step is the
 #'   definition of the file's path associated to the input `file_url`. The path
 #'   is created by pasting together the `download_directory`, the name of chosen
 #'   provider (which may be inferred from the url) and the `basename()` of the
-#'   url. For example, if `file_url =
-#'   "https://download.geofabrik.de/europe/italy-latest.osm.pbf"`, and
+#'   url. For example, if `file_url` is equal to
+#'   `"https://download.geofabrik.de/europe/italy-latest.osm.pbf"`, and
 #'   `download_directory = "/tmp"`, then the path is built as
-#'   `"/tmp/geofabrik_italy-latest.osm.pbf"`. Then, the function checks the
-#'   existence of a file with the same file's path and, in that case, it returns
+#'   `"/tmp/geofabrik_italy-latest.osm.pbf"`. Thereafter, the function checks
+#'   the existence of a file in that path and, if that's the case, it returns
 #'   the path. The parameter `force_download` is used to modify this behaviour.
-#'   If there is no file associated with the file's path, then the function
-#'   downloads a new file using [download.file()] with `mode = "wb"`, and it
-#'   returns the path.
+#'   If there is no file associated with the new path, then the function
+#'   downloads a new file using [download.file()] with `mode = "wb"`, and,
+#'   again, it returns the path.
 #'
 #' @inheritParams oe_get
 #' @param file_url A url pointing to a `.osm.pbf` file that should be
@@ -36,10 +36,10 @@
 #' @export
 #'
 #' @examples
-#' its_match = oe_match("ITS Leeds", provider = "test")
+#' its_match = oe_match("ITS Leeds", provider = "test", quiet = TRUE)
 #' # ITS Leeds data are stored on github, which is not a standard provider.
-#' # So we need to specify the provider parameter.
-#' # See oe_providers() for a list of all available providers.
+#' # So we need to specify the provider parameter. See oe_providers() for a
+#' # list of all available providers.
 #' oe_download(
 #'   file_url = its_match$url,
 #'   file_size = its_match$file_size,

R/get.R

@@ -5,15 +5,15 @@
 #' Check the introductory vignette, the examples and the help pages of the
 #' wrapped functions to understand the details behind all parameters.
 #'
-#' To learn how to use the `query` argument, for example, see the
+#' To learn how to use the `query` argument see, for example, the
 #' [query section of the osmextract vignette](https://itsleeds.github.io/osmextract/articles/osmextract.html#query).
 #'
 #' @param place Description of the geographical area that should be matched with
 #'   a `.osm.pbf` file through the chosen `provider`. Can be either a length-1
 #'   character vector, a length-1 `sfc_POINT` object or a numeric vector of
 #'   coordinates with length 2. In the latter case it is assumed that the EPSG
-#'   code is 4326 specified as c(LON, LAT), while you can use any EPSG code with
-#'   an `sfc_POINT` object. See Details and examples in [oe_match()].
+#'   code is 4326 specified as c(LON, LAT), while you can use any CRS with an
+#'   `sfc_POINT` object. See Details and examples in [oe_match()].
 #' @param layer Which `layer` should be read in? Typically `points`, `lines`
 #' (the default), `multilinestrings`, `multipolygons` or `other_relations`.
 #' @param provider Which provider should be used to download the data? Available
@@ -22,24 +22,19 @@
 #'   `provider` is set equal to `test`. This is just for simple examples and
 #'   internal testings.
 #' @param match_by Which column of the provider's database should be used for
-#'   matching the input `place` with a `.osm.pbf` file? The default is "name".
+#'   matching the input `place` with a `.osm.pbf` file? The default is `"name"`.
 #'   Check Details and Examples in [oe_match()] to understand how this parameter
 #'   works. Ignored if `place` is not a character vector since the matching is
 #'   performed through a spatial operation.
 #' @param max_string_dist Numerical value greater or equal than 0. What is the
 #'   maximum distance in fuzzy matching (i.e. Approximate String Distance, see
 #'   [adist()]) between input `place` and `match_by` column to tolerate before
-#'   asking the user to select which zone to download? This parameter is set
-#'   equal to 0 if `match_by` is equal to `iso3166_1_alpha2` or `iso3166_2`.
-#'   Check Details and Examples in [oe_match()] to understand why this parameter
-#'   is important. Ignored if `place` is not a character vector since the
-#'   matching is performed through a spatial operation.
-#' @param interactive_ask Boolean. If `TRUE` the function creates an interactive
-#'   menu in case the best match is further than `max_string_dist`, otherwise it
-#'   fails with `stop()`. Check details and examples in [oe_match()] to
-#'   understand why this parameter is important. Ignored if `place` is not a
-#'   character vector since the matching is performed through a spatial
-#'   operation.
+#'   testing alternative providers or looking for geographical matching with
+#'   Nominatim API? This parameter is set equal to 0 if `match_by` is equal to
+#'   `iso3166_1_alpha2` or `iso3166_2`. Check Details and Examples in
+#'   [oe_match()] to understand why this parameter is important. Ignored if
+#'   `place` is not a character vector since the matching is performed through a
+#'   spatial operation.
 #' @param download_directory Where to download the file containing the OSM data?
 #'   By default this is equal to [oe_download_directory()], which is equal to
 #'   [`tempdir()`] and it changes each time you restart R. You can set a
@@ -51,23 +46,24 @@
 #'   `.osm.pbf` files.
 #' @param max_file_size The maximum file size to download without asking in
 #'   interactive mode. Default: `5e+8`, half a gigabyte.
-#' @param vectortranslate_options Options to pass to the [`sf::gdal_utils()`]
-#'   argument `options`. Set by default. Check Details in the introductory
-#'   vignette and in [oe_vectortranslate()].
-#' @param osmconf_ini The configuration file specifying which columns should be
-#'   in the resulting data frame. See documentation at
-#'   [gdal.org](https://gdal.org/drivers/vector/osm.html). Check Details in
-#'   [oe_vectortranslate()].
+#' @param vectortranslate_options Options passed to the [`sf::gdal_utils()`]
+#'   argument `options`. Set by default. Check details in the introductory
+#'   vignette and the help page of [oe_vectortranslate()].
+#' @param osmconf_ini The configuration file. See documentation at
+#'   [gdal.org](https://gdal.org/drivers/vector/osm.html). Check details in the
+#'   introductory vignette and the help page of [oe_vectortranslate()]. Set by
+#'   default.
 #' @param extra_tags Which additional columns, corresponding to OSM tags, should
-#'   be in the resulting dataset? `FALSE` by default. Check Details at
-#'   [oe_vectortranslate()] and [oe_get_keys()]. Ignored when `osmconf_ini` is
-#'   not `NULL`.
+#'   be in the resulting dataset? `NULL` by default. Check the introductory
+#'   vignette and the help pages of [oe_vectortranslate()] and [oe_get_keys()].
+#'   Ignored when `osmconf_ini` is not `NULL`.
 #' @param force_vectortranslate Boolean. Force the original `.pbf` file to be
 #'   translated into a `.gpkg` file, even if a `.gpkg` with the same name
-#'   already exists? Check Details at [oe_vectortranslate()] .
-#' @param skip_vectortranslate Boolean. If `TRUE` then the function skips all
-#'   vectortranslate operations and it reads (or simply returns the path) of
-#'   the `.osm.pbf` file. `FALSE` by default.
+#'   already exists? Check the introductory vignette and the help page of
+#'   [oe_vectortranslate()].
+#' @param skip_vectortranslate Boolean. If `TRUE`, then the function skips all
+#'   vectortranslate operations and it reads (or simply returns the path) of the
+#'   `.osm.pbf` file. `FALSE` by default.
 #' @param never_skip_vectortranslate Boolean. This is used in case the user
 #'   passed its own `.ini` file or vectortranslate options (since, in those case,
 #'   it's too difficult to determine if an existing `.gpkg` file was generated
@@ -88,7 +84,7 @@
 #' @export
 #'
 #' @details The algorithm that we use for importing an OSM extract data into R
-#'   is divided into 4 steps: 1) Matching the input `place` with the url of a
+#'   is divided into 4 steps: 1) match the input `place` with the url of a
 #'   `.pbf` file; 2) download the `.pbf` file; 3) convert it into `.gpkg` format
 #'   and 4) read-in the `.gpkg` file. The function `oe_match()` is used to
 #'   perform the first operation and the function `oe_read()` (which is a
@@ -116,18 +112,24 @@
 #' # Add additional tags
 #' its_with_oneway = oe_get("ITS Leeds", extra_tags = "oneway", quiet = FALSE)
 #' names(its_with_oneway)
-#' table(its_with_oneway$oneway)
+#' table(its_with_oneway$oneway, useNA = "ifany")
 #'
 #' # Use the query argument to get only oneway streets:
 #' q = "SELECT * FROM 'lines' WHERE oneway IN ('yes')"
-#' its_residential = oe_get("ITS Leeds", query = q)
-#' its_residential
+#' its_oneway = oe_get("ITS Leeds", query = q)
+#' its_oneway
 #'
 #' \dontrun{
 #' # A more complex example
 #' west_yorkshire = oe_get("West Yorkshire", quiet = FALSE)
-#' # If you run it again, the function will not download the file or convert it
+#' # If you run it again, the function will not download the file
+#' # or convert it again
 #' west_yorkshire = oe_get("West Yorkshire", quiet = FALSE)
+#' # Match with place name
+#' oe_get("Milan") # Warning: the .pbf file is 400MB
+#' oe_get("Vatican City")
+#' oe_get("Zurich")
+#'
 #' # Match with coordinates (any EPSG)
 #' milan_duomo = sf::st_sfc(sf::st_point(c(1514924, 5034552)), crs = 3003)
 #' oe_get(milan_duomo, quiet = FALSE) # Warning: the .pbf file is 400MB
@@ -147,7 +149,6 @@ oe_get = function(
   provider = "geofabrik",
   match_by = "name",
   max_string_dist = 1,
-  interactive_ask = FALSE,
   download_directory = oe_download_directory(),
   force_download = FALSE,
   max_file_size = 5e+8,
@@ -175,7 +176,6 @@ oe_get = function(
     provider = provider,
     match_by = match_by,
     max_string_dist = max_string_dist,
-    interactive_ask = interactive_ask,
     quiet = quiet
   )