Skip to contents

Builds 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 in create_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_cells of create_grid_polygons() accepts besides a number (a selection, a profile or ranked levels, read as a count first). Default NULL, as in create_grid_polygons(), so the grid can be sized by cellsize or n passed through ... instead.

type

Grid type: "square" (the default) or "hex", matching create_grid_polygons().

...

Further arguments to create_grid_polygons(), such as cellsize, n or crs.

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_cache empties 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.

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