In paleolimbot/geovctrs: Efficient Data Structures for Geometry Vectors

knitr::opts_chunk$set(
  collapse = TRUE,
  dpi =  300,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

geovctrs

The goal of geovctrs is to provide a common set of classes and data structures to ensure that processing functions in the rapidly expanding R geospatial ecosystem are interchangeable.

Installation

You can install the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("paleolimbot/geovctrs")

If you can load the package, you're good to go!

library(geovctrs)

Geometry vectors

This package provides vctrs class definitions several simple geometries that can be efficiently stored using column vectors (geo_xy(), geo_xyz(), geo_segment(), and geo_rect()). Well-known geometry (well-known binary and well-known text) vectors from the wk package are used for generic geometries. These classes are designed to work with dplyr, tidyr, and other tidyverse packages that use vctrs. In addition to providing default implementations of generics, they have print, plot, and coercion methods so that they "just work" when you need them to.

head(geo_example_wkt)
head(as_wkb(geo_example_wkt))

Constructing and destructing geometries

The geovctrs package provides functions to construct geometries from coordinates, and destruct geometries to extract their coordinates.

# construct linestrings
linestrings <- c(
  geo_linestring(geo_xy(c(1, 2, 5), c(0, 1, 2))),
  geo_linestring(geo_xy(c(10, 20, 50), c(0, 10, 20)))
)

linestrings

# destruct to get coordinates
geo_coordinates(linestrings)

You can use separate_xy() get the actual x and y values (and unite_xy() to create a geo_xy() column).

separate_xy(geo_coordinates(linestrings), "xy")

In the newest version of dplyr, this is useful in conjunction with group_by() and summarise().

library(dplyr)
geo_coordinates(linestrings) %>% 
  group_by(feature) %>% 
  summarise(geometry = geo_linestring(xy))

Generics

There are several concepts that show up on repeat in geometry packages. The geovctrs package provides these as generics with reasonable implementations for the bundled geometry vector classes. Notably, geo_bbox()/geo_envelope() (return a geo_rect()), geo_srid(), and geo_z(). These generics work on anything that can be interpreted as a geometry vector, including character vectors (interpreted as well-known text), data frames with exactly one geometry column (interpreted as the geometry column), and anything that implements as_geovctr() (e.g., sf objects).

geo_bbox(geo_nc)
geo_srid(head(geo_nc))

The geovctrs package also provides a framework for transformers, or functions that accept a vector of geometries and return a vector of geometries. These always return the same type as the input, as dictated by the implementations of as_geovctr() and restore_geovctr(). This enables transforming functions to work on a wide variety of input types, including sf objects:

library(sf)
sf_nc <- read_sf(system.file("shape/nc.shp", package = "sf"))
geo_envelope(sf_nc)

See vignette("extending-geovctrs", package = "geovctrs") for instructions on how to create a class that works with the geovctrs framework.

paleolimbot/geovctrs documentation built on July 30, 2020, 3:41 p.m.