spatSample: Sample random points from a GRaster or GVector

In adamlilith/fasterRaster: Faster Raster and Spatial Vector Processing Using 'GRASS GIS'

Sample random points from a GRaster or GVector

Description

spatSample() randomly locates points across a GRaster or GVector. It can return a GVector, the coordinates, values associated with the points, or all of these. If you want to generate a raster with randomly-sampled cells, see sampleRast().

Usage

## S4 method for signature 'GRaster'
spatSample(
  x,
  size,
  as.points = FALSE,
  values = TRUE,
  cats = TRUE,
  xy = FALSE,
  strata = NULL,
  byStratum = FALSE,
  zlim = NULL,
  seed = NULL,
  verbose = FALSE
)

## S4 method for signature 'GVector'
spatSample(
  x,
  size,
  as.points = FALSE,
  values = TRUE,
  xy = FALSE,
  byStratum = FALSE,
  zlim = NULL,
  seed = NULL
)

Arguments

x	A GRaster or GVector.
size	Numeric value > 0: Number of points to create.
as.points	Logical: If FALSE (default), the output is a data.frame or data.table. If TRUE, the output is a "points" GVector.
values	Logical: If TRUE (default), values of the GRaster at points are returned.
cats	Logical: If TRUE (default) and the GRaster is categorical, then return the category label of each cell. If values is also TRUE, then the cell value will also be returned.
xy	Logical: If TRUE, return the longitude and latitude of each point. Default is FALSE.
strata	Either NULL (default), or a GVector defining strata. If supplied, the size argument will be interpreted as number of points to place per geometry in strata. Note that using strata can dramatically slow the process.
byStratum	Logical: If FALSE (default), then size number of points will be placed within the entire area delineated by strata. If TRUE, then size points will be placed within each subgeometry of strata.
zlim	Either NULL (default), or a vector of two numbers defining the lower and upper altitudinal bounds of coordinates. This cannot be combined with values = TRUE or cats = TRUE.
seed	Either NULL (default) or an integer: Random number seed. If this is NULL, the a seed will be set randomly. Values will be rounded to the nearest integer.
verbose	Logical: If TRUE, display progress. Default is FALSE.

Value

A data.frame, data.table, or GVector.

See Also

sampleRast(), terra::spatSample(), module v.random in GRASS

Examples

if (grassStarted()) {

# Setup
library(sf)
library(terra)

# Example data
madElev <- fastData("madElev") # raster

# Convert to GRasters and GVectors
elev <- fast(madElev)

### spatSample()

# Random points as data.frame or data.table:
randVals <- spatSample(elev, size = 20, values = TRUE)
randVals

# Random points as a points GVector:
randPoints <- spatSample(elev, size = 20, as.points = TRUE)
randPoints
plot(elev)
plot(randPoints, add = TRUE)

# Random points in a select area:
madCoast <- fastData("madCoast4") # vector
coast <- fast(madCoast)
ant <- coast[coast$NAME_4 == "Antanambe"] # subset

restrictedPoints <- spatSample(elev, size = 20, as.points = TRUE,
   strata = ant)

plot(elev)
plot(ant, add = TRUE)
plot(restrictedPoints, add = TRUE) # note 20 points for entire geometry

# Random points, one set per subgeometry:
stratifiedPoints <- spatSample(elev, size = 20, as.points = TRUE,
   strata = ant, byStratum = TRUE)

plot(elev)
plot(ant, add = TRUE)
plot(stratifiedPoints, pch = 21, bg = "red", add = TRUE) # note 20 points per subgeometry

# Random categories:
madCover <- fastData("madCover") # raster
cover <- fast(madCover)

randCover <- spatSample(cover, size = 20, values = TRUE,
     cat = TRUE, xy = TRUE)
randCover

### sampleRast()

# Random cells in non-NA cells:
rand <- sampleRast(elev, 10000)
plot(rand)
nonnacell(rand)

# Use custom values for the mask:
randCustomMask <- sampleRast(elev, 10000, maskvalues = 1:20)
plot(randCustomMask)

# Force selected values to a custom value:
randCustomUpdate <- sampleRast(elev, 10000, updatevalue = 7)
plot(randCustomUpdate)

# Custom values for mask and set selected cells to custom value:
randAll <- sampleRast(elev, 10000, maskvalues = 1:20, updatevalue = 7)
plot(randAll)

}

adamlilith/fasterRaster documentation built on Dec. 21, 2024, 2:04 a.m.