terra: sample – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

sample

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 signature 'SpatRaster'
spatSample(x, size, method="random", replace=FALSE, na.rm=FALSE, as.raster=FALSE,
	as.points=FALSE, values=TRUE, cells=FALSE, xy=FALSE, ext=NULL, warn=TRUE)

## S4 method for signature 'SpatVector'
spatSample(x, size, method="random", strata=NULL, chess="")

## S4 method for signature '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
`as.points`	logical. If `TRUE`, a SpatVector of points is returned
`values`	logical. If `TRUE` cell values are returned
`cells`	logical. If `TRUE`, cell numbers are returned
`xy`	logical. If `TRUE`, cell coordinates are returned
`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

Examples

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, values=FALSE)
cells <- as.vector(cells)

v <- r[cells]
xy <- xyFromCell(r, cells)
cbind(xy, v)

# regular 
cells <- spatSample(r, 6, "regular", cells=TRUE, values=FALSE)
cells <- as.vector(cells)
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,]

terra

Spatial Data Analysis

v1.2-10

GPL (>= 3)

Authors

Robert J. Hijmans [cre, aut] (<https://orcid.org/0000-0001-5872-2872>), Roger Bivand [ctb] (<https://orcid.org/0000-0003-2392-6140>), Karl Forner [ctb], Jeroen Ooms [ctb] (<https://orcid.org/0000-0002-4035-0289>), Edzer Pebesma [ctb] (<https://orcid.org/0000-0001-8049-7069>)

Initial release

2021-05-12