a5_hierarchy: Index parents and children

In a5R: 'A5' Discrete Global Grid System

Index parents and children

Description

a5_cell_to_parent() returns the ancestor of each cell at a coarser resolution. a5_cell_to_children() returns the descendants of each cell at a finer resolution: 4 per resolution step, or 5 from resolution 0. Both follow the cell index, so they are cheap bit operations.

Usage

a5_cell_to_parent(cell, parent_resolution = NULL, resolution)

a5_cell_to_children(cell, child_resolution = NULL, simplify = TRUE, resolution)

Arguments

cell	An a5_cell vector.
parent_resolution	Integer scalar target resolution for a5_cell_to_parent(), or NULL (default) for the immediate parent. It must not be finer than any cell's resolution; -1 gives the world cell.
resolution	Deprecated: renamed parent_resolution and child_resolution, as in the other A5 libraries.
child_resolution	Integer scalar target resolution for a5_cell_to_children(), or NULL (default) for the immediate children.
simplify	Logical scalar. If TRUE (default), return one flat a5_cell vector with the children of every input concatenated in input order; which child came from which parent is not recorded. If FALSE, return an a5_cell_list: a vctrs::list_of() of a5_cell vectors with one element per input, suitable for a list column.

Value

• a5_cell_to_parent(): an a5_cell vector the same length as cell.

• a5_cell_to_children(): an a5_cell vector, or an a5_cell_list when simplify = FALSE. An NA input contributes no cells (an empty element in the list form).

Index hierarchy is not spatially nested

A5 parents and children are defined by the cell index, not by geometry. A cell's index children do not tile it: their union overlaps the parent's neighbours. Measured over random cells, the index parent is not the coarse cell containing a fine cell's centre for about half of fine cells one resolution apart, falling to about 35 percent at four or more resolutions apart. Use these functions for operations on ids (compaction, id ranges, curve ordering) and a5_spatial_hierarchy when cells must nest by location.

See Also

a5_spatial_hierarchy for parents and children by location, a5_cell_child() for one child at a time, a5_cell_children_range() for the id range of all descendants, 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, parent_resolution = 5)

a5_cell_to_children(cell)
cells <- a5_lonlat_to_cell(c(-3.19, 0), c(55.95, 0), resolution = 5)
a5_cell_to_children(cells, child_resolution = 7)                   # 32 cells
a5_cell_to_children(cells, child_resolution = 7, simplify = FALSE) # list of 2

# children map back to their parent
all(a5_cell_to_parent(a5_cell_to_children(cell, 12), 10) == cell)

a5R documentation built on Oct. 19, 2026, 5:08 p.m.