Skip to contents

Adapted Hypercube Evaluation of a Legacy Sample (ahels)

Source: R/sample_ahels.R
sample_ahels.Rd

Perform the adapted Hypercube Evaluation of a Legacy Sample (ahels) algorithm using existing site data and raster metrics. New samples are allocated based on quantile ratios between the existing sample and covariate dataset.

Usage

sample_ahels(
  mraster,
  existing,
  nQuant = 10,
  nSamp = NULL,
  threshold = 0.9,
  tolerance = 0,
  matrices = NULL,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

mraster

spatRaster. ALS metrics raster.

existing

sf 'POINT'. Existing plot network.

nQuant

Numeric. Number of quantiles to divide covariates and samples into. Quantiles that do not cover at least 1 percent of the area of interest will be excluded and be returned as NA.

nSamp

Numeric. Maximum number of new samples to allocate.

threshold

Numeric. Sample quantile ratio threshold. After the threshold default = 0.9 is reached, no additional samples will be added. Values close to 1 can cause the algorithm to continually loop.

tolerance

Numeric. Allowable tolerance (<= 0.1 (10 added until the 1 - tolerance density is reached. If threshold is used, samples will be added until the threshold - tolerance value is reached. This parameter allows the user to define a buffer around desired quantile densities to permit the algorithm to not add additional samples if quantile density is very close to 1, or user-defined threshold.

matrices

List. Quantile and covariance matrices generated from calculate_pop(mraster = mraster, nQuant = nQuant). Both mraster & nQuant inputs must be the same to supply the covariance matrix. Supplying the matrix allows users with very large mrasters to pre-process the covariance matrix to avoid longer sampling processing times. If matrices is provided, the nQuant parameter is ignored and taken from the covariance matrix.

plot

Logical. Plots samples of type existing (if provided; crosses) and new (circles) along with mraster.

details

Logical. If FALSE (default) output is sf object of systematic samples. If TRUE returns a list of sf objects where tessellation is the tessellation grid for sampling, and samples are the systematic samples.

filename

Character. Path to write output samples.

overwrite

Logical. Choice to overwrite existing filename if it exists.

Value

Returns sf point object with existing samples and supplemental samples added by the ahels algorithm.

Note

Messages in the algorithm will state that samples have been added to under-represented quantiles. The number between square brackets that follow represent the matrix row and column respectively that can be printed using details = TRUE.

In some cases, generally when a single metric is used as mraster, sampling ratios all be >= 1 before the nSamp number of samples are allocated. The algorithm will stop in this scenario.

Special thanks to Dr. Brendan Malone for the original implementation of this algorithm.

References

Malone BP, Minasny B, Brungard C. 2019. Some methods to improve the utility of conditioned Latin hypercube sampling. PeerJ 7:e6451 DOI 10.7717/peerj.6451

See also

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

Author

Tristan R.H. Goodbody

Examples

if (FALSE) {
#--- Load raster and existing plots---#
r <- system.file("extdata", "mraster.tif", package = "sgsR")
mr <- terra::rast(r)

e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

sample_ahels(
  mraster = mr,
  existing = e,
  plot = TRUE
)

#--- supply quantile and covariance matrices ---#
mat <- calculate_pop(mraster = mr)

sample_ahels(
  mraster = mr,
  existing = e,
  matrices = mat,
  nSamp = 300
)
}