sample_strat: Stratified sampling

In tgoodbody/sgsR: Structurally Guided Sampling

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
)

tgoodbody/sgsR documentation built on March 7, 2024, 2:20 a.m.