Skip to contents

Robustly transform any raster to PRIO-GRID format

Source: R/utility.R
robust_transformation.Rd

This function performs a comprehensive transformation of input rasters to match the PRIO-GRID specification. It handles rasters with different projections, extents, and resolutions through an intelligent workflow that includes reprojection, cropping, aggregation, disaggregation, and final resampling as needed.

Usage

robust_transformation(r, agg_fun, disagg_method = "near", ...)

Arguments

r

SpatRaster object to transform. Can have any projection, extent, or resolution.

agg_fun

Character string or function for aggregating high-resolution data. Common options include "mean", "sum", "max", "min", "median", "modal". See aggregate for all options.

disagg_method

Character string specifying disaggregation method for low-resolution data. Options are "near" (nearest neighbor, default), "bilinear", or "cubic". See disagg for details.

...

Additional arguments passed to aggregate. Useful for controlling aggregation behavior (e.g., na.rm = TRUE).

cores

Integer specifying number of CPU cores to use for aggregation operations. Defaults to 1. Higher values can speed up processing of large datasets.

Value

SpatRaster object conforming to PRIO-GRID specifications:

  • CRS: As specified in global options (default: EPSG:4326)

  • Extent: As specified in global options (default: global extent)

  • Resolution: Calculated from nrow/ncol in global options

  • Grid alignment: Exactly matched to PRIO-GRID cell boundaries

Details

The transformation workflow automatically detects and handles:

  • Projection differences: Reprojects to PRIO-GRID CRS if needed

  • Extent mismatches: Crops input if larger than PRIO-GRID extent

  • Resolution differences:

    • Aggregates high-resolution data using specified aggregation function

    • Disaggregates low-resolution data using specified method

  • Final alignment: Uses nearest-neighbor resampling for exact grid matching

All intermediate files are written to temporary storage to handle large datasets efficiently and are automatically cleaned up after processing.

Performance Notes

For large datasets, consider:

  • Increasing cores parameter for faster aggregation

  • Ensuring adequate disk space in the raw data folder for temporary files

  • Pre-cropping input data to region of interest before transformation

Global Options

This function uses global PRIO-GRID options set via PGOptionsManager:

  • pgoptions$get_rawfolder(): Location for temporary file storage

  • pgoptions$get_ncol(), pgoptions$get_nrow(): Output grid dimensions

  • pgoptions$get_extent(): Output spatial extent

  • pgoptions$get_crs(): Output coordinate reference system

See also

prio_blank_grid for creating empty PRIO-GRID templates, PGOptionsManager for setting global options, aggregate, disagg, resample

Examples

if (FALSE) { # \dontrun{
# Downloads and transfomrs GHSL to PRIO-GRID resolution
download_pg_rawdata(pg_rawfiles() |> dplyr::filter(id == "ae6a7612-4bef-452f-acd6-d2212cf9a7c5"))
r <- read_ghsl_population_grid()
res <- robust_transformation(r, agg_fun = "sum")
} # }