oe_get_keys: Return keys and (optionally) values stored in "other_tags" column

Description

This function returns the OSM keys and (optionally) the values stored in the other_tags field. See Details. In both cases, the keys are sorted according to the number of occurrences, which means that the most common keys are stored first.

Usage

oe_get_keys(
  zone,
  layer = "lines",
  values = FALSE,
  which_keys = NULL,
  download_directory = oe_download_directory()
)
# S3 method for default
oe_get_keys(
  zone,
  layer = "lines",
  values = FALSE,
  which_keys = NULL,
  download_directory = oe_download_directory()
)
# S3 method for character
oe_get_keys(
  zone,
  layer = "lines",
  values = FALSE,
  which_keys = NULL,
  download_directory = oe_download_directory()
)
# S3 method for sf
oe_get_keys(
  zone,
  layer = "lines",
  values = FALSE,
  which_keys = NULL,
  download_directory = oe_download_directory()
)
# S3 method for oe_key_values_list
print(x, n = getOption("oe_max_print_keys", 10L), ...)

Value

If the argument values is FALSE (the default), then the function returns a character vector with the names of all keys stored in the other_tags field. If values is TRUE, then the function returns named list which stores all keys and the corresponding values. In the latter case, the returned object has class oe_key_values_list and we defined an ad-hoc printing method. See Details.

Arguments

zone: An sf object with an other_tags field or a character vector (of length 1) that can be linked to or pointing to a .osm.pbf or .gpkg file with an other_tags field. Character vectors are linked to .osm.pbf files using oe_find().
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 argument. See also #122.
values: Logical. If TRUE, then function returns the keys and the corresponding values, otherwise only the keys. Defaults to FALSE.
which_keys: Character vector used to subset only some keys and corresponding values. Ignored if values is FALSE. See examples.
download_directory: Path of the directory that stores the .osm.pbf files. Only relevant when zone is as a character vector that must be matched to a file via oe_find(). Ignored unless zone is a character vector.
x: object of class oe_key_values_list
n: Maximum number of keys (and corresponding values) to print; can be set globally by options(oe_max_print_keys=...). Default value is 10.
...: Ignored.

Details

OSM data are typically documented using several tags, i.e. pairs of two items, namely a key and a value. The conversion between .osm.pbf and .gpkg formats is governed by a CONFIG file that lists which tags must be explicitly added to the .gpkg file. All the other keys are automatically stored using an other_tags field with a syntax compatible with the PostgreSQL HSTORE type. See here for more details.

When the argument values is TRUE, then the function returns a named list of class oe_key_values_list that, for each key, summarises the corresponding values. The key-value pairs are stored using the following format: list(key1 = c("value1", "value1", "value2", ...), key2 = c("value1", ...) ...). We decided to implement an ad-hoc method for printing objects of class oe_key_values_list using the following structure:

key1 = {#value1 = n1; #value2 = n2; #value3 = n3,
  ...} key2 = {#value1 = n1; #value2 = n2; ...} key3 = {#value1 = n1} ...

where n1 denotes the number of times that value1 is repeated, n2 denotes the number of times that value2 is repeated and so on. Also the values are listed according to the number of occurrences in decreasing order. By default, the function prints only the ten most common keys, but the number can be adjusted using the option oe_max_print_keys.

Finally, the hstore_get_value() function can be used inside the query argument in oe_get() to extract one particular tag from an existing file. Check the introductory vignette and see examples.

Examples

Run this code

# Copy the ITS file to tempdir() to make sure that the examples do not
# require internet connection. You can skip the next 4 lines (and start
# directly with oe_get_keys) when running the examples locally.

its_pbf = file.path(tempdir(), "test_its-example.osm.pbf")
file.copy(
  from = system.file("its-example.osm.pbf", package = "osmextract"),
  to = its_pbf,
  overwrite = TRUE
)

# Get keys
oe_get_keys("ITS Leeds", download_directory = tempdir())

# Get keys and values
oe_get_keys("ITS Leeds", values = TRUE, download_directory = tempdir())

# Subset some keys
oe_get_keys(
  "ITS Leeds", values = TRUE, which_keys = c("surface", "lanes"),
  download_directory = tempdir()
)

# Print all (non-NA) values for a given set of keys
res = oe_get_keys("ITS Leeds", values = TRUE, download_directory = tempdir())
res["surface"]

# Get keys from an existing sf object
its = oe_get("ITS Leeds", download_directory = tempdir())
oe_get_keys(its, values = TRUE)

# Get keys from a character vector pointing to a file (might be faster than
# reading the complete file and then filter it)
its_path = oe_get(
  "ITS Leeds", download_only = TRUE,
  download_directory = tempdir(), quiet = TRUE
)
oe_get_keys(its_path, values = TRUE)

# Add a key to an existing .gpkg file without repeating the
# vectortranslate operations
its = oe_get("ITS Leeds", download_directory = tempdir())
colnames(its)
its_extra = oe_read(
  its_path,
  query = "SELECT *, hstore_get_value(other_tags, 'oneway') AS oneway FROM lines",
  quiet = TRUE
)
colnames(its_extra)

# The following fails since there is no points layer in the .gpkg file
if (FALSE) {
oe_get_keys(its_path, layer = "points")}

# Add layer and read keys
its_path = oe_get(
  "ITS Leeds", layer = "points", download_only = TRUE,
  download_directory = tempdir(), quiet = TRUE
)
oe_get_keys(its_path, layer = "points")

# Remove .pbf and .gpkg files in tempdir
rm(its_pbf, res, its_path, its, its_extra)
oe_clean(tempdir())