Skip to contents

Summarise raster cell values

Source: R/raster_stats.R
raster_stats.Rd

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, quantiles = NULL, maxcell = 1e+06, verbose = TRUE)

Arguments

x

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

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), a definition of each column is 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. 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. All-NA layers 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.

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

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)
r   <- rast(nrows = 10, ncols = 10)
r[] <- c(rep(NA, 10), 11:100)
raster_stats(r)

# With the quantiles used to stretch a plot's colour scale
raster_stats(r, 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, verbose = FALSE)
} # }