R: Take a regular sample

spatSample {terra} | 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 `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,]

[Package terra version 1.2-10 Index]