terra (version 1.0-10)

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) or (when type="regular" and as.raster=TRUE) get a new SpatRaster with the same extent, but fewer cells. Note that, in order to assure regularity when requesting a regular sample, the number of values returned may not be exactly the same as the size requested.

Usage

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

Arguments

x

SpatRaster

size

numeric. The sample size

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, cellnumbers are returned instead of values

by_geom

logical. If TRUE, sampling is done seperately for each geometry (multi-polygon or multi-line), otherwise, a single sample is taken for all geometries

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

...

additional arguments. None implemented

Value

numeric or SpatRaster

Details

In some cases you may want to know the location of the sampled cells. In that situation you can take a sample of the cell numbers and use extract. See examples.

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,]

# }