sample_strat {sgsR}

Stratified sampling

Description

Sampling based on a stratified raster.

Usage

sample_strat(
  sraster,
  nSamp,
  allocation = "prop",
  method = "Queinnec",
  weights = NULL,
  force = FALSE,
  mraster = NULL,
  mindist = NULL,
  existing = NULL,
  include = FALSE,
  remove = FALSE,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  wrow = 3,
  wcol = 3,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

sraster

spatRaster. Stratification raster to be used for sampling.

nSamp

Numeric. Number of desired samples. existing, include and force influence this value.

allocation

Character. Allocation algorithm to be used. Either prop (default) for proportional allocation, optim for optimal allocation (equal sampling cost), equal for equal number of samples (defined by nSamp) for each strata, or "manual" for user defined strata weights defined using weights.

method

Character. Sampling design approach "Queinnec" (default) or "random". "Queinnec" method is described in notes below. "random" performs traditional stratified random sampling where probability to sample each cell within each stratum is equal assuming default parameters for mindist. existing, include, remove are ignored when method = "random".

weights

Numeric. Only applicable when allocation = "manual". Vector of weights where sum(weights) == 1. Vector length must be equal to the number of unique strata where the first numeric value corresponds to stratum 1, second stratum 2 etc.

force

Logical. Default = FALSE - force nSamp to be exactly the user defined value in cases where nSamp and sraster strata count are not equally divisible. Additional samples often need to be allocated or removed based on rounding differences resulting from proportional differences between nSamp and strata coverages in sraster. In these instances samples are either added to strata with the lowest number of samples or are removed from strata with the highest number of samples. Has no effect when existing is provided.

mraster

spatRaster. ALS metric raster. Required when allocation = optim.

mindist

Numeric. Minimum allowable distance between selected samples. Default = NULL.

existing

sf 'POINT' or data.frame. Existing plot network.

include

Logical. If TRUE include existing plots in nSamp total.

remove

Logical. If TRUE randomly remove samples from over represented strata to meet allocated sample numbers. Used only when existing and include are both TRUE.

access

sf 'LINESTRING' or 'MULTILINESTRING'. Access network.

buff_inner

Numeric. Inner buffer boundary specifying distance from access where plots cannot be sampled.

buff_outer

Numeric. Outer buffer boundary specifying distance from access where plots can be sampled.

wrow

Numeric. Number of row in the focal window (default = 3).

wcol

Numeric. Number of columns in the focal window (default = 3).

plot

Logical. Plots samples of type 'existing' (if provided; croses) and 'new' (circles) along with sraster.

details

Logical. If FALSE (default) output is sf object of stratified samples. If TRUE return a list where $details additional sampling information and $raster is an sf object of stratified samples.

filename

Character. Path to write output samples.

overwrite

Logical. Choice to overwrite existing filename if it exists.

Value

An sf object with nSamp stratified samples.

Note

The sampling is performed in 2 stages when method = "Queinnec":

1. Rule 1 - Sample within grouped stratum pixels defined within the wrow, wcol parameters

2. Rule 2 - If no samples exist to satisfy Rule 1 individual stratum pixels are sampled.

   The rule applied to allocate each sample is defined in the rule attribute of output samples.

existing may contain samples that fall in sraster cells that are 'NA'. If this occurs and include = TRUE, 'NA' samples are separated during sampling and re-appended at the end of the sampling process.

If the sraster provided contains factor values, the algorithm will automatically convert these into the numeric factor levels and perform sampling using those values. The categories (factor values) will be extracted and appended to the algorithm output as the 'category' attribute.

Author(s)

Tristan R.H. Goodbody & Martin Queinnec

References

Queinnec, M., White, J. C., & Coops, N. C. (2021). Comparing airborne and spaceborne photon-counting LiDAR canopy structural estimates across different boreal forest types. Remote Sensing of Environment, 262 (August 2020), 112510. https://doi.org/10.1016/j.rse.2021.112510

See Also

Other sample functions: sample_ahels(), sample_balanced(), sample_clhs(), sample_existing(), sample_nc(), sample_srs(), sample_sys_strat(), sample_systematic()

Examples

#--- Load raster and access files ---#
r <- system.file("extdata", "sraster.tif", package = "sgsR")
sr <- terra::rast(r)


#--- perform stratified sampling random sampling ---#
sraster <- sample_strat(
  sraster = sr,
  nSamp = 50
)