Skip to contents

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.


  nQuant = 10,
  nSamp = NULL,
  threshold = 0.9,
  tolerance = 0,
  matrices = NULL,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE



spatRaster. ALS metrics raster.


sf 'POINT'. Existing plot network.


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.


Numeric. Maximum number of new samples to allocate.


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.


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.


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.


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


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.


Character. Path to write output samples.


Logical. Choice to overwrite existing filename if it exists.


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


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.


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


Tristan R.H. Goodbody


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)

  mraster = mr,
  existing = e,
  plot = TRUE

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

  mraster = mr,
  existing = e,
  matrices = mat,
  nSamp = 300