Awesome
<!-- README.md is generated from README.Rmd. Please edit that file -->geovctrs
<!-- badges: start -->
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)
#> <wk_wkt[6]>
#> [1] <NA>
#> [2] POINT (30 10)
#> [3] POINT EMPTY
#> [4] POINT Z (1 1 5)
#> [5] MULTIPOINT ((10 40), (40 30), (20 20...
#> [6] MULTIPOINT EMPTY
head(as_wkb(geo_example_wkt))
#> <wk_wkb[6]>
#> [1] <NA>
#> [2] <POINT (30 10)>
#> [3] <POINT (nan nan)>
#> [4] <POINT Z (1 1 5)>
#> [5] <MULTIPOINT ((10 40), (40 30), (20 20...>
#> [6] <MULTIPOINT EMPTY>
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
#> <wk_wksxp[2]>
#> [1] <LINESTRING (1 0, 2 1, 5 2...> <LINESTRING (10 0, 20 10, 50 20...>
# destruct to get coordinates
geo_coordinates(linestrings)
#> # A tibble: 6 x 4
#> feature part ring xy
#> <int> <int> <int> <xy>
#> 1 1 1 0 (1 0)
#> 2 1 1 0 (2 1)
#> 3 1 1 0 (5 2)
#> 4 2 2 0 (10 0)
#> 5 2 2 0 (20 10)
#> 6 2 2 0 (50 20)
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")
#> # A tibble: 6 x 5
#> feature part ring x y
#> <int> <int> <int> <dbl> <dbl>
#> 1 1 1 0 1 0
#> 2 1 1 0 2 1
#> 3 1 1 0 5 2
#> 4 2 2 0 10 0
#> 5 2 2 0 20 10
#> 6 2 2 0 50 20
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))
#> # A tibble: 2 x 2
#> feature geometry
#> <int> <wk_wksxp>
#> 1 1 <LINESTRING (1 0, 2 1, 5 2...>
#> 2 2 <LINESTRING (10 0, 20 10, 50 20...>
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)
#> <geovctrs_rect[1]>
#> [1] (-84.32385 33.88199...-75.45698 36.58965)
geo_srid(head(geo_nc))
#> [1] 4267 4267 4267 4267 4267 4267
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)
#> Linking to GEOS 3.7.2, GDAL 2.4.2, PROJ 5.2.0
sf_nc <- read_sf(system.file("shape/nc.shp", package = "sf"))
geo_envelope(sf_nc)
#> Simple feature collection with 100 features and 14 fields
#> geometry type: POLYGON
#> dimension: XY
#> bbox: xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
#> CRS: NA
#> # A tibble: 100 x 15
#> AREA PERIMETER CNTY_ CNTY_ID NAME FIPS FIPSNO CRESS_ID BIR74 SID74 NWBIR74
#> <dbl> <dbl> <dbl> <dbl> <chr> <chr> <dbl> <int> <dbl> <dbl> <dbl>
#> 1 0.114 1.44 1825 1825 Ashe 37009 37009 5 1091 1 10
#> 2 0.061 1.23 1827 1827 Alle… 37005 37005 3 487 0 10
#> 3 0.143 1.63 1828 1828 Surry 37171 37171 86 3188 5 208
#> 4 0.07 2.97 1831 1831 Curr… 37053 37053 27 508 1 123
#> 5 0.153 2.21 1832 1832 Nort… 37131 37131 66 1421 9 1066
#> 6 0.097 1.67 1833 1833 Hert… 37091 37091 46 1452 7 954
#> 7 0.062 1.55 1834 1834 Camd… 37029 37029 15 286 0 115
#> 8 0.091 1.28 1835 1835 Gates 37073 37073 37 420 0 254
#> 9 0.118 1.42 1836 1836 Warr… 37185 37185 93 968 4 748
#> 10 0.124 1.43 1837 1837 Stok… 37169 37169 85 1612 1 160
#> # … with 90 more rows, and 4 more variables: BIR79 <dbl>, SID79 <dbl>,
#> # NWBIR79 <dbl>, geometry <POLYGON>
See vignette("extending-geovctrs", package = "geovctrs") for
instructions on how to create a class that works with the geovctrs
framework.