Getting started with a5R
In a5R: 'A5' Discrete Global Grid System

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(a5R)

Index a point

Map a longitude/latitude coordinate to a cell at a given resolution (0--30). Higher resolutions produce smaller cells.

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 10)
cell

Convert back to the cell centre point:

a5_cell_to_lonlat(cell)

Cell boundaries

Get the boundary polygon for one or more cells:

boundary <- a5_cell_to_boundary(cell)
boundary

plot(boundary, col = "#206ead20", border = "#206ead", asp = 1)

Boundaries are returned as wk_wkb vectors by default (set format = "wkt" for WKT). Both integrate directly with sf, terra, and other spatial tooling via the wk package.

Hierarchy and compaction

A5 is a hierarchical grid: every cell has a parent at a coarser resolution and 4 children at the next finer resolution.

parent <- a5_cell_to_parent(cell)
parent

children <- a5_cell_to_children(cell)
children

We can visualise the relationship - the parent (dark outline) contains our cell (blue fill), which in turn contains its 4 children (orange):

plot(NULL, xlim = c(-3.23, -3),  ylim = c(55.98, 55.99),               
       xlab = "", ylab = "", asp = 1
       )
plot(a5_cell_to_boundary(a5_cell_to_children(cell)),
     col = "#ad6e2020", border = "#ad6e20", add = TRUE)
plot(a5_cell_to_boundary(cell), col = "#206ead40", border = "#206ead",
     lwd = 2, add = TRUE)
plot(a5_cell_to_boundary(parent), border = "#333333", lwd = 2, add = TRUE)

Cell area decreases geometrically --- each level is roughly 4x smaller:

a5_cell_area(0:5)

Compact and uncompact

When a complete set of siblings is present, a5_compact() merges them back into their shared parent. This is the inverse of a5_cell_to_children() and is useful for reducing the size of large cell sets without losing coverage.

children
a5_compact(children)

# round-trips back to the original
a5_uncompact(a5_compact(children), resolution = 11)

Many a5R functions return compacted output automatically. For example, a5_grid_disk() and a5_spherical_cap() compact their results --- use a5_uncompact() when you need a uniform-resolution grid (see Traversal below).

Traversal

Find neighbouring cells by hop count with a5_grid_disk(), or by great-circle distance with a5_spherical_cap():

disk <- a5_grid_disk(cell, k = 10)
cap <- a5_spherical_cap(cell, radius = 50000)

plot(a5_cell_to_boundary(cap), col = "#6ead2020", border = "#6ead20", asp = 1)
plot(a5_cell_to_boundary(disk), col = "#206ead20", border = "#206ead", asp = 1)

Both functions return a compacted cell vector --- sibling groups are merged into coarser parent cells to save space. To recover a uniform grid at the original resolution, pass the result through a5_uncompact():

disk_grid <- a5_uncompact(disk, resolution = a5_get_resolution(cell))

plot(a5_cell_to_boundary(disk_grid), col = "#206ead20", border = "#206ead", asp = 1)

Grid generation

a5_grid() is a convenience function provided by a5R (not part of the underlying a5 Rust crate) that returns all cells at a target resolution covering a given area --- handy for binning, zonal statistics, and other spatial analysis workflows common in R.

Pass a bounding box as a numeric vector:

cells <- a5_grid(c(-3.3, 55.9, -3.1, 56.0), resolution = 12)
length(cells)

plot(a5_cell_to_boundary(cells), col = "#206ead20", border = "#206ead", asp = 1)

Any geometry that wk can handle works too --- polygons, sf objects, or even a5_cell vectors:

library(sf)
demo(nc, ask = FALSE, echo = FALSE)
nca5 <- a5_grid(nc, resolution = 9)
plot(a5_cell_to_boundary(nca5), col = "#6d20ad20", border = "#6d20adff", asp = 1)