a5R provides R bindings for the A5 pentagonal geospatial index, powered by the a5 Rust crate via extendr.
A5 partitions the Earth’s surface into pentagonal cells across 31 resolution levels. Cells are equal-area and encoded as 64-bit integers; at the finest resolution each covers about 30 mm².
a5R 1.0 uses the A5 1.0 cell index, which numbers cells differently from earlier versions. Convert ids stored by a5R 0.x with a5_migrate().
Installation
install.packages("a5R")Or install the development version from GitHub:
# install.packages("pak")
pak::pak("belian-earth/a5R")Building from source needs a Rust toolchain (cargo and rustc).
Quick example
library(a5R)
# Index a point to a cell
cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 10)
cell
#> <a5_cell[1]>
#> [1] 63bb948000000000
# Get the boundary polygon
a5_cell_to_boundary(cell)
#> <wk_wkb[1] with CRS=OGC:CRS84>
#> [1] <POLYGON ((-3.175718 55.93546, -3.145905 55.97569, -3.151641 56.01921, -3.219413 56.00818, -3.226037 55.96443, -3.175718 55.93546...>
# Navigate the hierarchy
a5_cell_to_parent(cell)
#> <a5_cell[1]>
#> [1] 63bb960000000000
a5_cell_to_children(cell)
#> <a5_cell[4]>
#> [1] 63bb942000000000 63bb946000000000 63bb94a000000000 63bb94e000000000Polygons become coverings, one per feature. Here North Carolina’s counties are filled with cells, coloured by their distance from Wake County’s centroid:
nc <- sf::read_sf(system.file("shape/nc.shp", package = "sf")) |>
sf::st_transform(4326)
nc$a5 <- a5_polygon_to_cells(nc, resolution = 9, containment = "overlapping")
cells <- unique(a5_uncompact(nc$a5))
wake <- sf::st_coordinates(sf::st_centroid(nc$geometry[nc$NAME == "Wake"]))
centre <- a5_lonlat_to_cell(wake[, 1], wake[, 2], resolution = 9)
dist <- a5_cell_distance(centre, cells, units = "km")
plot(a5_cell_to_boundary(cells), col = hcl.colors(50)[cut(as.numeric(dist), 50)], border = "grey50", lwd = 0.5)
plot(nc$geometry, border = "white", lwd = 0.5, add = TRUE)
See vignette("a5R") for a full walkthrough of indexing, boundaries, hierarchy, traversal, and geometry-to-cell conversion.
Features
- Vectorised Rust core: all operations implemented in Rust and called from R via extendr. A benchmark suite mirroring the TypeScript, Python and Rust ports runs on every pull request and fails on regressions above 15%.
-
vctrs + wk integration: cell indices use an
a5_celltype with tibble support; geometries return aswk_wkb/wk_wktvectors compatible with sf and terra. -
Coverings: polygons, disks and caps become
a5_coveringvectors, one compacted cell set per feature, that combine (a5_union(),a5_intersect(),a5_difference()), test (a5_contains()) and measure (a5_area()) without expanding to millions of cells. Seevignette("coverings"). -
Geometry indexing:
a5_polygon_to_cells()anda5_line_string_to_cells()map polygons and great-circle lines to cells. -
Traversal:
a5_grid_disk()anda5_spherical_cap()select neighbours by hop count or great-circle distance. -
Spatial hierarchy:
a5_cell_to_supercell()anda5_cell_to_subcells()move between resolutions by location, so aggregation counts each fine cell inside the coarse cell it lies in. -
Arrow and Parquet: cells and coverings convert to Arrow
uint64columns and back exactly, with the A5 index recorded in the schema. Seevignette("arrow-parquet"). -
Multi-threading: opt-in parallel processing via rayon for vectorised operations. See
vignette("multithreading").
Acknowledgements
A5 was created by Felix Palmer. This package is a thin R wrapper around his work and would not exist without it. The Query-farm team maintain the DuckDB A5 extension, which wraps the same Rust crate and provided a valuable reference for this project.
