a5R: A5 Pentagonal Geospatial Index for R

Description

R bindings for the A5 pentagonal geospatial index / discrete global grid system, powered by the a5 Rust crate via extendr.

Indexing

• a5_lonlat_to_cell() — coordinates to cell IDs

• a5_cell_to_lonlat() — cell IDs to centre coordinates

• a5_is_cell() — validate cell IDs

Geometry

• a5_cell_to_boundary() — cell boundary polygons (WKB or WKT)

• a5_cell_area() — cell area at a given resolution

• a5_cell_distance() — distance between cell centroids

• a5_get_num_cells() — total cell count at a resolution

• a5_get_num_children() — child count between resolutions

Hierarchy

• a5_get_resolution() — extract resolution from cell IDs

• a5_cell_to_parent() — navigate to coarser cells

• a5_cell_to_children() — navigate to finer cells

• a5_get_res0_cells() — the 12 root cells

• a5_compact() / a5_uncompact() — compress and expand cell sets

Traversal

• a5_grid_disk() — neighbours by hop count

• a5_spherical_cap() — neighbours by great-circle distance

Grid generation

• a5_grid() — fill a bbox or geometry with cells

Configuration

• a5_set_threads() / a5_get_threads() — multi-threading control

Vignettes

• vignette("a5R") — getting started

• vignette("multithreading") — parallel processing

Author(s)

Maintainer: Hugh Graham hugh@belian.earth

Other contributors:

• belian.earth [copyright holder]

See Also

Useful links:

• https://github.com/belian-earth/a5R

• https://belian-earth.github.io/a5R/

• Report bugs at https://github.com/belian-earth/a5R/issues

A5 Cell Index Vector

Description

Create, test, and coerce A5 cell index vectors. Cells are stored as hex-encoded character strings.

Usage

a5_cell(x = character())

is_a5_cell(x)

as_a5_cell(x)

a5_is_cell(x)

Arguments

Value

An a5_cell vector (a5_cell, as_a5_cell), a logical scalar (is_a5_cell), or a logical vector (a5_is_cell).

Examples

cells <- a5_cell(c("0800000000000006", "0800000000000016"))
cells
a5_is_cell(c("0800000000000006", "not_a_cell", NA))

Cell area at a given resolution

Description

Returns the area of a single cell in square metres at the given resolution(s). Because A5 is an equal-area DGGS, all cells at the same resolution have identical area.

Usage

a5_cell_area(resolution, units = "m^2")

Arguments

Value

A units::units vector of areas.

Examples

a5_cell_area(0:5)
a5_cell_area(5, units = "km^2")

Distance between cell centroids

Description

Computes the distance between the centroids of pairs of A5 cells using the specified method.

Usage

a5_cell_distance(
  from,
  to,
  units = "m",
  method = c("haversine", "geodesic", "rhumb")
)

Arguments

Value

A units::units vector of distances.

See Also

a5_cell_to_lonlat() for cell centroids, a5_cell_area() for cell areas.

Examples

a <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 24)
b <- a5_lonlat_to_cell(-3.10, 55.90, resolution = 24)
a5_cell_distance(a, b)
a5_cell_distance(a, b, units = "km")
a5_cell_distance(a, b, method = "geodesic")

Get cell boundary polygons

Description

Returns the boundary of each cell as a wk::wkt() or wk::wkb() polygon geometry. Boundaries are pentagonal polygons on the WGS 84 ellipsoid.

Usage

a5_cell_to_boundary(
  cell,
  format = c("wkb", "wkt"),
  closed = TRUE,
  segments = NULL
)

Arguments

Value

A wk_wkt or wk_wkb vector of polygon geometries with wk::wk_crs_longlat() CRS.

See Also

a5_cell_to_lonlat() for cell centroids.

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)
a5_cell_to_boundary(cell)
a5_cell_to_boundary(cell, format = "wkt")

Get child cells

Description

Returns the child cells of a single cell. By default returns the 4 immediate children (one resolution finer). Optionally target a specific finer resolution.

Usage

a5_cell_to_children(cell, resolution = NULL)

Arguments

Value

An a5_cell vector of child cells.

See Also

a5_cell_to_parent(), a5_get_resolution()

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)
a5_cell_to_children(cell)

Convert A5 cell indices to coordinates

Description

Returns the centre-point longitude and latitude of each cell.

Usage

a5_cell_to_lonlat(cell, normalise = TRUE)

Arguments

Value

A wk::xy() vector (if normalise = TRUE) or a data frame with columns lon and lat.

See Also

a5_lonlat_to_cell() for the inverse operation, a5_cell_to_boundary() for full cell polygons.

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)
a5_cell_to_lonlat(cell)

# Raw unwrapped coordinates
cell2 <- a5_lonlat_to_cell(114.8, 4.1, resolution = 5)
a5_cell_to_lonlat(cell2, normalise = FALSE)

Navigate to parent cell(s)

Description

Returns the parent cell of each input cell. By default returns the immediate parent (one resolution coarser). Optionally target a specific coarser resolution.

Usage

a5_cell_to_parent(cell, resolution = NULL)

Arguments

Value

An a5_cell vector of parent cells.

See Also

a5_cell_to_children(), a5_get_resolution()

Examples

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

Compact a set of A5 cells

Description

Merges complete sibling groups into their common parent, reducing the number of cells while preserving coverage.

Usage

a5_compact(cells)

Arguments

Value

An a5_cell vector of compacted cells.

See Also

a5_uncompact()

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)
children <- a5_cell_to_children(cell)
a5_compact(children) # back to the parent

Total number of cells at a given resolution

Description

Total number of cells at a given resolution

Usage

a5_get_num_cells(resolution)

Arguments

Value

A numeric scalar (double) giving the total count. Returned as double because the count can exceed R's integer range.

Examples

a5_get_num_cells(0)
a5_get_num_cells(10)

Number of children between two resolutions

Description

Returns the number of child cells each parent cell contains when expanding from one resolution to another.

Usage

a5_get_num_children(parent_resolution, child_resolution)

Arguments

Value

A numeric scalar. Returned as double because the count can exceed R's integer range at large resolution deltas.

See Also

a5_get_num_cells(), a5_cell_to_children(), a5_uncompact()

Examples

a5_get_num_children(5, 8)   # 4^3 = 64
a5_get_num_children(0, 5)

Get all resolution-0 root cells

Description

Returns the 12 root cells corresponding to the 12 faces of the dodecahedron.

Usage

a5_get_res0_cells()

Value

An a5_cell vector of length 12.

Examples

a5_get_res0_cells()

Get the resolution of A5 cell indices

Description

Extracts the resolution level (0–30) encoded in each cell index.

Usage

a5_get_resolution(cell)

Arguments

Value

An integer vector of resolutions.

See Also

a5_cell_to_parent(), a5_cell_to_children()

Examples

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

Generate a grid of A5 cells covering an area

Description

Returns all cells at the target resolution that intersect the given geometry. Uses hierarchical flood-fill: starting from the 12 resolution-0 root cells, the algorithm repeatedly expands and prunes by spatial intersection until the target resolution is reached.

Usage

a5_grid(x, resolution)

Arguments

Details

Grid generation runs entirely in Rust via hierarchical flood-fill with bounding-box pruning. For non-bbox geometry inputs, an exact intersection filter removes cells that fall outside the target shape. No cell count limit is imposed — high resolutions over large areas can consume significant memory.

Input geometries must use WGS 84 coordinates; projected geometries are not reprojected and will produce incorrect results. Multiple geometries are collected into a GEOMETRYCOLLECTION automatically. Antimeridian-crossing bounding boxes are supported: when xmin > xmax (e.g. c(170, -50, -170, -30)), the bbox is split at the antimeridian.

Limitation: spatial filtering uses planar geometry on lon/lat coordinates, which can produce incomplete results very close to the poles (above ~88° latitude) or the antimeridian. Use a larger target geometry to ensure complete coverage in these areas.

Value

An a5_cell vector of cells at resolution that intersect x.

See Also

a5_cell_to_boundary() to convert result cells to geometries.

Examples

# Grid from a bounding box
cells <- a5_grid(c(-3.3, 55.9, -3.1, 56.0), resolution = 5)
cells

# Grid from a WKT polygon
poly <- wk::wkt("POLYGON ((-3.3 55.9, -3.1 55.9, -3.1 56, -3.3 56, -3.3 55.9))")
cells <- a5_grid(poly, resolution = 5)

Cells within k hops of a cell

Description

Returns all cells reachable within k edge hops of a centre cell, including the centre cell itself.

Usage

a5_grid_disk(cell, k, vertex = FALSE)

Arguments

Value

A compacted a5_cell vector.

See Also

a5_spherical_cap() for distance-based selection.

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 8)
a5_grid_disk(cell, k = 1)

Convert coordinates to A5 cell indices

Description

Maps longitude/latitude coordinates to A5 cell indices at the specified resolution.

Usage

a5_lonlat_to_cell(lon, lat, resolution)

Arguments

Value

An a5_cell vector of cell indices.

See Also

a5_cell_to_lonlat() for the inverse operation.

Examples

a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)

Set the number of threads used by a5R

Description

Controls the number of threads used for parallel processing in vectorised functions. Set to 1 (the default) for sequential processing with zero overhead, or higher for parallel execution via rayon.

Usage

a5_set_threads(n = 1L)

a5_get_threads()

Arguments

Value

Invisibly returns the previous thread count.

Integer scalar.

Cells within a great-circle radius

Description

Returns all cells whose centres fall within a great-circle distance of a given cell's centre.

Usage

a5_spherical_cap(cell, radius)

Arguments

Value

A compacted a5_cell vector.

See Also

a5_grid_disk() for hop-based selection.

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 8)
a5_spherical_cap(cell, radius = 1000)

Uncompact a set of A5 cells to a target resolution

Description

Expands each cell to its descendants at the target resolution.

Usage

a5_uncompact(cells, resolution)

Arguments

Value

An a5_cell vector of uncompacted cells.

See Also

a5_compact()

Examples

cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 5)
a5_uncompact(cell, resolution = 7)

wk methods for a5_cell

Description

Integration with the wk geometry framework. Allows a5_cell vectors to be handled as geometry (via their boundary polygons) and to report their CRS.

Usage

## S3 method for class 'a5_cell'
wk_handle(handleable, handler, ...)

## S3 method for class 'a5_cell'
wk_crs(x)

Arguments

Value

• wk_handle(): the result of the handler.

• wk_crs(): a wk::wk_crs object (WGS 84 lon/lat).