Skip to contents

Load a PRIO-GRID variable

Source: R/build_priogrid.R
load_pgvariable.Rd

Loads a PRIO-GRID variable from disk and returns it as a lazy, file-backed terra SpatRaster (no data is loaded into memory until the raster is explicitly materialized). Supports optional lazy subsetting by layers and spatial windowing, enabling a larger-than-memory workflow.

Usage

load_pgvariable(
  varname,
  config = NULL,
  version = NULL,
  type = "05deg_yearly",
  spatial_hash = NULL,
  temporal_hash = NULL,
  verify_checksums = FALSE,
  extent = NULL,
  layers = NULL
)

Arguments

varname

Character string with the variable name.

config

A pg_config object for custom data, or NULL (default) for the official release.

version

Character string specifying PRIOGRID version (e.g., "3.0.1"). Only used in release mode (config = NULL). Defaults to current package version.

type

Character string specifying release type (e.g., "05deg_yearly"). Only used in release mode. Default: "05deg_yearly".

spatial_hash

Character string with 6-character spatial hash. Requires temporal_hash. Loads from the specified custom folder directly.

temporal_hash

Character string with 6-character temporal hash. Requires spatial_hash.

verify_checksums

Logical. If TRUE, verifies the file's MD5 checksum against stored values. Default FALSE.

extent

Optional spatial window. Either a SpatExtent (used as-is in the raster's CRS) or a length-4 numeric vector c(xmin, xmax, ymin, ymax) in EPSG:4326. Applied lazily via terra::window() — no data is loaded until the raster is materialized. Enables efficient reading of spatial subsets from large COGs (larger-than-memory workflow).

layers

Optional layer selector. A character vector of layer names or an integer vector of layer indices. Applied lazily via terra::subset().

Value

A lazy, file-backed SpatRaster. Data is not loaded into memory until explicitly materialized (e.g., via terra::values() or terra::crop()).

Details

Mode is determined by the config argument:

  • config = NULL (default): loads from the official release (downloads if needed).

  • config = pg_config(...): loads from custom data built with that config.

  • spatial_hash + temporal_hash: loads from a specific custom folder by hash.

Examples

if (FALSE) { # \dontrun{
  # Load from current official release (default)
  r <- load_pgvariable("cshapes_gwcode")

  # Load from specific official release
  r <- load_pgvariable("cshapes_gwcode", version = "3.0.1")

  # Load from custom data
  cfg <- pg_config(nrow = 180, ncol = 360)
  r <- load_pgvariable("cshapes_gwcode", config = cfg)

  # Load from specific custom folder by hash
  r <- load_pgvariable("cshapes_gwcode",
                       spatial_hash = "ecf4dd",
                       temporal_hash = "727cca")

  # Windowed / lazy load (larger-than-memory)
  r <- load_pgvariable("cru_tmp", extent = c(-30, 60, 35, 72), layers = 1:12)
  terra::inMemory(r)  # FALSE
} # }