Create and cache grid polygons over a boundary
Source:R/stable-ids-cache.R
create_grid_polygons_cached.RdBuilds a grid with create_grid_polygons(), gives it stable IDs with
ensure_stable_poly_id(), and keeps it, so a repeat call with the same
arguments returns the kept grid.
Usage
create_grid_polygons_cached(
boundary,
target_cells = NULL,
type = c("square", "hex"),
...,
cache_env = .gmt_cache,
max_entries = 50L
)Arguments
- boundary
An sf or sfc polygonal object. One that mixes XY and XYZ (or XYM) geometries, or whose geometries carry M (XYM or XYZM), is read without Z and M, as in
create_grid_polygons(), and shares its cache entry with the same boundary in XY. Its rows without a location, and those the repair leaves without a polygon, are left out, and a boundary with none left, or in a geographic CRS with a latitude beyond 90 degrees, is refused, as increate_grid_polygons(); a boundary shares its cache entry with its rows that have a location.- target_cells
Approximate desired number of cells, or what
target_cellsofcreate_grid_polygons()accepts besides a number (a selection, a profile or ranked levels, read as a count first). DefaultNULL, as increate_grid_polygons(), so the grid can be sized bycellsizeornpassed through...instead.- type
Grid type:
"square"(the default) or"hex", matchingcreate_grid_polygons().- ...
Further arguments to
create_grid_polygons(), such ascellsize,norcrs.- cache_env
Environment the grids are kept in. The default is the package's own cache, which
clear_grid_cache()empties; pass a new environment to keep a separate cache.- max_entries
Maximum number of grids the cache holds. Default 50. Once full, adding a grid evicts the one added earliest, so a loop over many boundaries holds at most this many grids (about 2 MB per 2,500-cell grid) rather than every grid it ever built for the life of the session.
clear_grid_cacheempties it outright.
Value
An sf data frame with a stable poly_id column. The rows are
re-ordered and re-numbered by ensure_stable_poly_id(), which
create_grid_polygons() does not do: the same cell therefore carries a
different poly_id depending on which of the two builders produced
it. Use one builder throughout an analysis; joining a
summary keyed on IDs from one onto geometries from the other draws the
values on the wrong polygons.
Details
A grid returned in degrees (a geographic crs passed through ...) is
cached once per sf::sf_use_s2() setting: a grid laid in degrees is
clipped by s2 with the setting on and by GEOS with it off, and
ensure_stable_poly_id() rebuilds the cells s2 or GEOS calls invalid
with s2's rebuild with the setting on and repairs every cell with GEOS with it off,
so the grid differs between the two settings. A call is handed the grid
of the session's setting. A grid laid and returned in a
projected CRS is clipped and repaired by GEOS under either setting and is
cached once.
See also
clear_grid_cache() to empty the cache.
Other cell building:
build_tessellation(),
clip_target_for(),
create_grid_polygons(),
create_voronoi_polygons(),
ensure_stable_poly_id(),
get_voronoi_seeds(),
plot_tessellation_map(),
voronoi_seeds_kmeans(),
voronoi_seeds_random()
Examples
library(sf)
bnd <- st_sf(geometry = st_sfc(st_polygon(list(rbind(
c(0, 0), c(100, 0), c(100, 100), c(0, 100), c(0, 0)
))), crs = 32632))
g <- create_grid_polygons_cached(bnd, target_cells = 16, type = "hex")
# 27, not 16: clipping keeps every hexagon that overhangs the boundary,
# which adds more at a small target (see ?create_grid_polygons)
nrow(g)
#> [1] 27
# The IDs come from ensure_stable_poly_id(), so they follow the geometry:
# the same request with the boundary's vertices in another order gives the
# same ID to the same cell.
bnd2 <- st_sf(geometry = st_sfc(st_polygon(list(rbind(
c(100, 100), c(0, 100), c(0, 0), c(100, 0), c(100, 100)
))), crs = 32632))
g2 <- create_grid_polygons_cached(bnd2, target_cells = 16, type = "hex")
same_cell <- match(st_as_text(st_geometry(g2)), st_as_text(st_geometry(g)))
all(g2$poly_id == g$poly_id[same_cell])
#> [1] TRUE