Summarise raster cell values

Computes per-layer pixel statistics for one or more rasters: total cells, missing cells, and the range, mean, and standard deviation of the valid values. Useful as a QA pass over harmonized or newly exported layers before they are used as covariates.

Usage

raster_stats(
  x,
  aoi = "alberta",
  quantiles = NULL,
  maxcell = 1e+06,
  verbose = TRUE
)

Arguments

x

A SpatRaster, or a character vector of raster file paths and/or directories containing GeoTIFFs.

aoi

Area of interest the statistics are restricted to: a SpatVector, an sf polygon, or the character shortcut "alberta" accepted by mask_to_boundary(). Defaults to "alberta", the packaged provincial boundary also returned by ab_boundary() and covered by ab_grid(). NULL summarises every cell of the layer.

quantiles

Optional numeric vector of probabilities in [0, 1]. Each adds a column named for the percentile, e.g. c(0.02, 0.98) gives q2 and q98. Default NULL, no quantile columns.

maxcell

Numeric; layers with more cells than this are sampled when computing quantiles. Default 1e6.

verbose

Logical; if TRUE (default), the area the statistics cover and a definition of each column are printed above the returned table. Set to FALSE when calling from a script or another function.

Value

A data.frame with one row per layer and columns layer, source, n_total, n_na, pct_na, n_valid, min, max, mean, and sd, plus one column per requested quantile. Every count and summary describes the cells inside aoi. source is the file the layer was read from, or NA for a raster held in memory; layers of a file that carry no band name are named for the file. Layers with no valid cell in the aoi return NA for the value summaries. Unless verbose = FALSE, a definition of each column is printed first.

Details

x may be a SpatRaster, the path to a raster file, or a directory of GeoTIFFs, so a folder of exports can be checked in one call. Every layer of every raster contributes one row.

Only cells inside aoi are summarised. The default is the Alberta provincial boundary the reference grid covers, so the counts describe the area a covariate is needed for rather than the rectangular extent an export happens to carry. n_total is the number of cells the aoi covers, counted from the aoi itself, so n_na and pct_na report how much of the study area the layer leaves empty. Pass aoi = NULL to summarise every cell of the layer instead.

Counts and summaries are computed with terra::global(), which streams the raster from disk. Quantiles are computed from the values themselves; layers with more than maxcell cells are sampled on a regular lattice, making those columns approximate for large rasters.

See also

mask_to_boundary() to clip a layer to the same boundary; check_alignment() to test a layer's geometry against the reference grid; plot_hist() and plot_raster() to inspect the same values visually.

Examples

if (FALSE) { # \dontrun{
library(terra)

# Cells inside the Alberta boundary only, the default
raster_stats(ab_grid())

# Or inside any other polygon
raster_stats(ab_grid(), aoi = my_study_area)

# A layer that is not an Alberta layer: summarise every cell
r   <- rast(nrows = 10, ncols = 10)
r[] <- c(rep(NA, 10), 11:100)
raster_stats(r, aoi = NULL)

# With the quantiles used to stretch a plot's colour scale
raster_stats(r, aoi = NULL, quantiles = c(0.02, 0.98))

# Every GeoTIFF in a folder of exports
raster_stats("2_pipeline/gee_exports")

# Just the table, for use downstream
raster_stats(r, aoi = NULL, verbose = FALSE)
} # }