aggregate_raster_to_polygons: Aggregate a raster to polygons

In mbg: Model-Based Geostatistics

Aggregate a raster to polygons

Description

Aggregate raster values to polygons using an aggregation table

Usage

aggregate_raster_to_polygons(
  data_raster,
  aggregation_table,
  aggregation_cols = "polygon_id",
  method = "mean",
  aggregated_field = "data",
  z_dimension = NULL,
  z_dimension_name = "z",
  weighting_raster = NULL,
  na.rm = TRUE
)

Arguments

data_raster	terra::SpatRaster containing data to be aggregated to polygons.
aggregation_table	data.table::data.table Aggregation table linking pixels to polygon identifiers, created using build_aggregation_table()
aggregation_cols	(character vector, default 'polygon_id') Polygon identifiers to use for aggregation. Must be field names within aggregation_table.
method	(character, default 'mean') Aggregation method: one of 'mean', 'sum', 'weighted.mean', or 'weighted.sum'. The latter two methods require a weighting_raster.
aggregated_field	(character, default 'data') Name of the aggregated raster values in the output table.
z_dimension	(vector, default NULL) If passing a data_raster with multiple layers, how should each layer be identified? Should be a vector with length equal to the number of layers in data_raster. If left as NULL, the default, and data_raster has 1 layer, no z dimension will be added. If left as NULL and data_raster has more than 1 layer, will default to (1, 2, ..., N layers).
z_dimension_name	(default 'z') The field name for the "z" dimension corresponding to each layer of the data_raster. This field is only added if z_dimension is passed or if data_raster has more than one layer.
weighting_raster	(terra::SpatRaster, default NULL) The relative weighting of each whole pixel to the overall polygon value, for example, if calculating a population-weighted mean. Required for methods 'weighted.mean' and 'weighted.sum', ignored for the other methods.
na.rm	(bool, default TRUE) How to handle NA pixels in data_raster and weighting_raster. If set to TRUE but ALL pixels in a polygon are NA, will still return an NA value for the polygon.

Details

This is a more efficient and feature-rich alternative to terra's zonal statistics functions. Features include:

• Always fractionally aggregate, weighting by area of the pixel in a polygon

• Optionally weight by both area fraction and a weighting raster (e.g. population)

• Means or sums of raster values across polygons

• Optionally aggregate multiple years of raster data at once

Value

data.table containing polygon identifiers, (optionally) layer identifiers in the z_dimension_name column, and data values aggregated by polygon.

See Also

build_aggregation_table

Examples

## Not run: 
  polygons <- sf::st_read(system.file('extdata/Benin_communes.gpkg', package = 'mbg'))
  id_raster <- build_id_raster(polygons)
  n_data_pixels <- sum(!is.na(terra::values(id_raster)))
  # Example ID raster filled with data
  # This is an example of pixel-level covariate data or model estimates
  data_raster <- mbg::values_to_raster(stats::rnorm(n_data_pixels), id_raster)
  # Build aggregation table, which can be used across many aggregations
  aggregation_table <- build_aggregation_table(
    polygons, id_raster, polygon_id_field = 'commune_code'
  )
  # Aggregate the raster to the polygons
   aggregated <- aggregate_raster_to_polygons(
     data_raster = data_raster,
     aggregation_table = aggregation_table,
     aggregation_cols = 'commune_code',
     method = 'mean'
   )
   head(aggregated)

## End(Not run)

mbg documentation built on April 4, 2025, 2:06 a.m.