Skip to contents

Create a standard-compliant spatial grid with INSPIRE IDs

Source: R/create_grid.R
create_grid.Rd

This function generates a regular spatial grid aligned to the CRS origin. It combines high performance for large areas (using sfheaders) with a flexible and robust set of features for input handling and output formatting, including INSPIRE-compliant grid IDs and automatic parallel processing with mirai and future backends.

Usage

create_grid(
  grid_extent,
  cellsize_m,
  crs = NULL,
  output_type = "sf_polygons",
  clip_to_input = FALSE,
  use_convex_hull = FALSE,
  buffer_m = 0,
  id_format = "both",
  include_llc = TRUE,
  point_type = "centroid",
  parallel = "auto",
  quiet = FALSE
)

Arguments

grid_extent

A spatial object to define the grid's extent. Can be an sf or sfc object, a 2x2 bbox matrix, or a numeric vector of c(xmin, ymin, xmax, ymax).

cellsize_m

A single integer representing the grid cell size in metres (e.g., 1000 for a 1 km grid).

crs

The coordinate reference system (CRS) for the output grid. Accepts various formats handled by sf::st_crs(): an integer or numeric EPSG code (e.g., 3035), a string representation like "epsg:3035", or a crs object. If NULL (default), the CRS is inherited from grid_extent. If grid_extent also lacks a CRS, the function will stop with an error.

output_type

The class of the output object: "sf_polygons" (default) creates a spatial object with polygon geometries, "sf_points" creates an sf object with point geometries, and "dataframe" creates a data frame with grid cell centroid coordinates (X_centroid, Y_centroid).

clip_to_input

A logical value. If TRUE, the grid is filtered to include only cells that intersect the grid_extent. This does not cut cell geometries.

use_convex_hull

A logical value. If TRUE and clip_to_input is TRUE, the grid is clipped to the convex hull of the input geometry, which can be faster and simpler than using a complex polygon.

buffer_m

A numeric value. If clip_to_input is TRUE, this specifies a buffer distance in metres to apply to the grid_extent geometry before clipping. Defaults to 0 (no buffer).

id_format

A character string specifying which grid cell IDs to generate. Options are "both" (default), "long", "short", or "none".

include_llc

A logical value. If TRUE (default), columns for the lower-left corner coordinates (X_LLC, Y_LLC) of each cell are included in the output.

point_type

A character string, used only when output_type = "sf_points". Determines the location of the points: "centroid" (default) for the center of the cell, or "llc" for the lower-left corner.

parallel

Controls parallel execution. Options are:

  • 'auto' (default): Automatically detects and uses a configured mirai or future backend if one is available. If both are set, it prefers the one with more available workers and issues a warning. If neither is configured, it runs sequentially.

  • TRUE: Forces the function to attempt parallel execution. It will raise an error if a valid parallel backend (with >1 worker) is not configured.

  • FALSE: Forces the function to run in single-threaded sequential mode.

For parallelism, you must configure a backend before calling this function, for example: mirai::daemons(4) or future::plan("multisession").

quiet

logical value. If ‘TRUE’, all progress messages and progress bars are suppressed. Defaults to ‘FALSE’.

Value

An sf object (with polygon or point geometries) or a data.frame representing the grid, with optional columns for coordinates and INSPIRE-compliant grid IDs.

Examples

library(sf)
#> Linking to GEOS 3.12.1, GDAL 3.8.4, PROJ 9.4.0; sf_use_s2() is TRUE
# Load the sample data from the sf package
nc_raw <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

# Define target projected CRS and cell size
target_crs <- 5070 # NAD83 / Conus Albers
cellsize_m <- 10000 # 10 km

# Project the data
nc <- st_transform(nc_raw, target_crs)

# Create a grid covering the data
nc_grid <- create_grid(
  grid_extent = nc,
  cellsize_m = cellsize_m,
  output_type = "sf_polygons",
  clip_to_input = TRUE
)
#> No parallel backend detected. Running in sequential mode. See ?create_grid for details how to enable parallel processing to speed up large jobs.

head(nc_grid, 3)
#> Simple feature collection with 3 features and 5 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 1570000 ymin: 1340000 xmax: 1600000 ymax: 1360000
#> Projected CRS: NAD83 / Conus Albers
#>      id   X_LLC   Y_LLC                      GRD_ID_LONG GRD_ID_SHORT
#> 54   54 1580000 1340000 CRS5070RES10000mN1340000E1580000 10kmN134E158
#> 55   55 1590000 1340000 CRS5070RES10000mN1340000E1590000 10kmN134E159
#> 132 132 1570000 1350000 CRS5070RES10000mN1350000E1570000 10kmN135E157
#>                           geometry
#> 54  POLYGON ((1580000 1340000, ...
#> 55  POLYGON ((1590000 1340000, ...
#> 132 POLYGON ((1570000 1350000, ...