sample: Take a regular sample
In terra: Spatial Data Analysis

spatSample

R Documentation

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 method="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.df=TRUE, as.points=FALSE, values=TRUE, cells=FALSE, 
    xy=FALSE, ext=NULL, warn=TRUE, weights=NULL, exp=5, exhaustive=FALSE)

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

## S4 method for signature 'SpatExtent'
spatSample(x, size, method="random", lonlat, as.points=FALSE)

Arguments

`x`	SpatRaster, SpatVector or SpatExtent
`size`	numeric. The sample size. If `x` is a SpatVector, you can also provide a vector of the same length as `x` in which case sampling is done separately for each geometry. If `x` is a SpatRaster, and you are using `method="regular"` you can specify the size as two numbers (number of rows and columns)
`method`	character. Should be "regular" or "random", If `x` is a `SpatRaster`, it can also be "stratified" (each value in `x` is a stratum) or "weights" (each value in `x` is a probability weight)
`replace`	logical. If `TRUE`, sampling is with replacement (if `method="random"`)
`na.rm`	logical. If `TRUE`, `NAs` 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.df`	logical. If `TRUE`, a data.frame is returned instead of a matrix
`as.points`	logical. If `TRUE`, a SpatVector of points is returned
`values`	logical. If `TRUE` raster cell values are returned
`cells`	logical. If `TRUE`, cell numbers are returned. If `method="stratified"` this is always set to `TRUE` if `xy=FALSE`
`xy`	logical. If `TRUE`, cell coordinates are returned
`ext`	SpatExtent or NULL to restrict sampling to a subset of the area of `x`
`warn`	logical. Give a warning if the sample size returned is smaller than requested
`weights`	SpatRaster. Used to provide weights when `method="stratified"`
`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`
`exp`	numeric >= 1. "Expansion factor" that is multiplied with `size` to get an initial sample used for stratified samples and random samples with `na.rm=TRUE` to try to get at least `size` samples
`exhaustive`	logical. If `TRUE` and `na.rm=TRUE` first all cells that are not `NA` are determined and a sample is taked from these cells. This is useful when you are dealing with a very large raster that is sparse (most cells are NA). Otherwise, the default approach may not find enough samples. This should not be used in other cases, especially not with large rasters that mostly have values

Value

numeric matrix, data.frame, SpatRaster or SpatVector

Examples

f <- system.file("ex/elev.tif", package="terra")
r <- rast(f)
s <- spatSample(r, 10, as.raster=TRUE)
spatSample(r, 5)
spatSample(r, 5, na.rm=TRUE)
spatSample(r, 5, "regular")

## if you require cell numbers and/or coordinates
size <- 6
spatSample(r, 6, "random", cells=TRUE, xy=TRUE, values=FALSE)

# regular, with values 
spatSample(r, 6, "regular", cells=TRUE, xy=TRUE)

# stratified
rr <- rast(ncol=10, nrow=10, names="stratum")
set.seed(1)
values(rr) <- round(runif(ncell(rr), 1, 3))
spatSample(rr, 2, "stratified", xy=TRUE)

s <- spatSample(rr, 5, "stratified", as.points=TRUE)
plot(rr, plg=list(title="raster"))
plot(s, 1, add=TRUE, plg=list(x=185, y=1, title="points"))
 
## SpatExtent 
e <- ext(r)
spatSample(e, 10, "random", lonlat=TRUE)

## SpatVector
f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)

# sample the geometries 
i <- sample(v, 3)

# sample points in geometries
p <- spatSample(v, 3)

terra documentation built on Oct. 14, 2024, 5:07 p.m.