osmextract: oe_read – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

oe_read

Read a .pbf or .gpkg object from file or url

Description

This function is used to read a .pbf or .gpkg object from file or URL. It is a wrapper around oe_download(), oe_vectortranslate(), and sf::st_read(), creating an easy way to download, convert, and read a .pbf or .gpkg file. Check the introductory vignette and the help pages of the wrapped function for more details.

Usage

oe_read(
  file_path,
  layer = "lines",
  ...,
  provider = NULL,
  download_directory = oe_download_directory(),
  file_size = NULL,
  force_download = FALSE,
  max_file_size = 5e+08,
  download_only = FALSE,
  skip_vectortranslate = FALSE,
  vectortranslate_options = NULL,
  osmconf_ini = NULL,
  extra_tags = NULL,
  force_vectortranslate = FALSE,
  never_skip_vectortranslate = FALSE,
  quiet = FALSE
)

Arguments

`file_path`	A URL or the path of a `.pbf` or `.gpkg` file. If a URL, then it must be specified using HTTP/HTTPS protocol.
`layer`	Which `layer` should be read in? Typically `points`, `lines` (the default), `multilinestrings`, `multipolygons` or `other_relations`. If you specify an ad-hoc query using the argument `query` (see introductory vignette and examples), then `oe_get()` and `oe_read()` will read the layer specified in the query and ignore `layer`. See also #122.
`...`	Arguments that will be passed to `sf::st_read()`, like `query`, `wkt_filter` or `stringsAsFactors`. Check the introductory vignette to understand how to create your own (SQL-like) queries.
`provider`	Which provider should be used to download the data? Available providers can be found with the following command: `oe_providers()`. For `oe_get()` and `oe_match()`, if `place` is equal to `ITS Leeds`, then `provider` is set equal to `test`. This is just for simple examples and internal tests.
`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 persistent `download_directory` by adding the following to your `.Renviron` file (e.g. with `edit_r_environ` function in `usethis` package): `OSMEXT_DOWNLOAD_DIRECTORY=/path/to/osm/data`.
`file_size`	How big is the file? Optional. `NA` by default. If it's bigger than `max_file_size` and the function is run in interactive mode, then an interactive menu is displayed, asking for permission to download the file.
`force_download`	Should the `.osm.pbf` file be updated if it has already been downloaded? `FALSE` by default. This parameter is used to update old `.osm.pbf` files.
`max_file_size`	The maximum file size to download without asking in interactive mode. Default: `5e+8`, half a gigabyte.
`download_only`	Boolean. If `TRUE`, then the function only returns the path where the matched file is stored, instead of reading it. `FALSE` by default.
`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.
`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()`.
`osmconf_ini`	The configuration file. See documentation at gdal.org. Check details in the introductory vignette and the help page of `oe_vectortranslate()`. Set by default.
`extra_tags`	Which additional columns, corresponding to OSM tags, should 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`.
`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? `FALSE` by default. If tags in `extra_tags` match data in previously translated `.gpkg` files no translation occurs (see #173 for details). Check the introductory vignette and the help page of `oe_vectortranslate()`.
`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 following the same options.)
`quiet`	Boolean. If `FALSE`, the function prints informative messages. Starting from `sf` version 0.9.6, if `quiet` is equal to `FALSE`, then vectortranslate operations will display a progress bar.

Details

The arguments provider, download_directory, file_size, force_download, and max_file_size are ignored if file_path points to an existing .pbf or .gpkg file.

You cannot add any field or layer to an existing .gpkg file (unless you have the .pbf file and you convert it again with a different configuration), but you can extract some of the tags in other_tags field. Check examples and oe_get_keys() for more details.

Value

An sf object.

Examples

# Read an existing .pbf file. First we need to copy a .pbf file into a
# temporary directory
file.copy(
  from = system.file("its-example.osm.pbf", package = "osmextract"),
  to = file.path(tempdir(), "its-example.osm.pbf")
)
my_pbf = file.path(tempdir(), "its-example.osm.pbf")
oe_read(my_pbf)
oe_read(my_pbf, layer = "points") # Read a new layer
# The following example shows how to add new tags
names(oe_read(my_pbf, extra_tags = c("oneway", "ref"), quiet = FALSE))

# Read an existing .gpkg file. This file was created by oe_read
my_gpkg = file.path(tempdir(), "its-example.gpkg")
oe_read(my_gpkg)
# You cannot add any layer to an existing .gpkg file but you can extract some
# of the tags in other_tags. Check oe_get_keys() for more details.
names(oe_read(my_gpkg, extra_tags = c("maxspeed"))) # doesn't work
# Instead, use the query argument
names(oe_read(
  my_gpkg,
  quiet = TRUE,
  query =
  "SELECT *,
  hstore_get_value(other_tags, 'maxspeed') AS maxspeed
  FROM lines
  "
))

# Read from a URL
my_url = "https://github.com/ropensci/osmextract/raw/master/inst/its-example.osm.pbf"
# Please note that if you read from a URL which is not linked to one of the
# supported providers, you need to specify the provider parameter:
## Not run: 
oe_read(my_url, provider = "test", quiet = FALSE)

## End(Not run)

osmextract

Download and Read OpenStreetMap Data Extracts

v0.2.1

GPL-3

Authors

Andrea Gilardi [aut, cre] (<https://orcid.org/0000-0002-9424-7439>), Robin Lovelace [aut] (<https://orcid.org/0000-0001-5679-6536>), Barry Rowlingson [ctb] (<https://orcid.org/0000-0002-8586-6625>), Salva Fernández [rev] (Salva reviewed the package (v. 0.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/395>), Nicholas Potter [rev] (Nicholas reviewed the package (v. 0.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/395>)

Initial release