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, Minansy 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()`

## 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
)
}
```