terra (version 1.1-4)

spatSample: Take a regular sample

Description

Take a spatial sample from a SpatRaster, SpatVector or SpatExtent. Sampling a SpatVector or SpatExtent always returns a SpatVector of points.

With a SpatRaster, you can get cell values, cell numbers (cells=TRUE), coordinates (xy=TRUE) or (when type="regular" and as.raster=TRUE) get a new SpatRaster with the same extent, but fewer cells.

In order to assure regularity when requesting a regular sample, the number of cells or points returned may not be exactly the same as the size requested.

Usage

# S4 method for SpatRaster
spatSample(x, size, method="random", replace=FALSE, 
       na.rm=FALSE, as.raster=FALSE, cells=FALSE, xy=FALSE, ext=NULL, warn=TRUE)
# S4 method for SpatVector
spatSample(x, size, method="random", strata=NULL, chess="")
# S4 method for SpatExtent
spatSample(x, size, method="random", lonlat)

Arguments

x

SpatRaster

size

numeric. The sample size. If x is a SpatVector, you can also provide a vector of the same length as x in wich case sampling is done seperately for each geometry

method

character. Should be "regular" or "random". It can also be "stratified" if x is a SpatVector

replace

logical. If TRUE, sampling is with replacement (if method="random"

na.rm

logical. If TRUE, codeNAs are removed. Only used with random sampling of cell values. That is with method="random", as.raster=FALSE, cells=FALSE

as.raster

logical. If TRUE, a SpatRaster is returned

cells

logical. If TRUE and xy=FALSE, cellnumbers are returned instead of values

xy

logical. If TRUE, coordinates are returned instead of values

ext

SpatExtent or NULL to restrict sampling to a a subset of the area of x

warn

logical. Give a warning if the sample size returned is smaller than requested

strata

if not NULL, stratified random sampling is done, taking size samples from each stratum. If x has polygon geometry, strata must be a field name (or index) in x. If x has point geometry, strata can be a SpatVector of polygons or a SpatRaster

chess

character. One of "", "white", or "black". For stratified sampling if strata is a SpatRaster. If not "", samples are only taken from alternate cells, organized like the "white" or "black" fields on a chessboard

lonlat

logical. If TRUE, sampling of a SpatExtent is weighted by cos(latitude). For SpatRaster and SpatVector this done based on the crs, but it is ignored if as.raster=TRUE

Value

numeric or SpatRaster

Details

In stead of spatSample(x, size, method="random") you can also use the equivalent base method sample(x, size). The base method also works for sampling the geometries of SpatVector (you can take a sample from the number of geometries and use that as an index).

Examples

# NOT RUN {
f <- system.file("ex/elev.tif", package="terra")
r <- rast(f)
s <- spatSample(r, 10, as.raster=TRUE)
spatSample(r, 10)
spatSample(r, 10, "random")

## if you require cell numbers and/or coordinates
size <- 6
# random cells 
cells <- spatSample(r, 6, "random", cells=TRUE)
v <- r[cells]
xy <- xyFromCell(r, cells)
cbind(xy, v)

# regular 
cells <- spatSample(r, 6, "regular", cells=TRUE)
v <- r[cells]
xy <- xyFromCell(r, cells)
cbind(xy, v)

## SpatExtent 
e <- ext(r)
spatSample(e, 10, "random", lonlat=TRUE)


## SpatVector
f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)
#sample geometries 
i <- sample(nrow(v), 5)
vv <- v[i,]

# }