Skip to contents

Tune POPMAPS parameters with cross-validation

Source: R/tune_popmaps.R
tune_popmaps.Rd

tune_popmaps() compares POPMAPS parameter combinations by withholding empirical sampling sites, predicting ancestry coefficients from the remaining sites, and summarizing prediction error. It supports geographic-distance tuning and modern least-cost tuning for prepared suitability, conductance, or resistance surfaces.

Usage

tune_popmaps(
  input_raster = "",
  input_locs = "",
  surface = "G",
  surface_values = c("suitability", "conductance", "resistance"),
  empirical_pt_dist = 5,
  num_sites = 10,
  num_tested = c(2, 3, 4, 5, 6, 7, 8),
  popmod = c(-0.001, -0.01, -0.05, -0.1, -0.15),
  threshold = 0,
  validation = c("loo", "spatial_block"),
  n_blocks = 4,
  block_assignments = NULL,
  spatial_block_repeats = 1,
  spatial_block_seed = NULL,
  primary_metric = c("rmse", "mae", "hellinger", "dominant_accuracy",
    "dominant_probability"),
  dist_prob_func = function(popmod_temp, distance) {
     exp(popmod_temp * distance)
 },
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps),
  quiet = TRUE
)

Arguments

input_raster

A terra::SpatRaster, raster::RasterLayer, or path to a raster file defining the interpolation surface. It may also be a popmaps_surface object returned by prepare_popmaps_surface().

input_locs

A data frame or matrix with sampling location name, longitude, latitude, and one or more ancestry coefficient columns.

surface

Character. "G" tunes geographic-distance interpolation. "C" tunes suitability- or conductance-weighted least-cost interpolation using the modern internal distance helper.

surface_values

Character. Meaning of raster values when surface = "C". "suitability" and "conductance" use values directly; "resistance" converts values to conductance before distances are calculated. Ignored when input_raster is already a popmaps_surface object.

empirical_pt_dist

Numeric vector. Minimum distances required between empirical sites selected for a prediction. Values are kilometers for surface = "G" and least-cost distance units for surface = "C".

num_sites

Integer vector. Candidate pool sizes to evaluate.

num_tested

Integer vector. Numbers of empirical sites used to estimate ancestry coefficients.

popmod

Numeric vector. Distance-decay parameter values to evaluate.

threshold

Numeric scalar. Raster values below this threshold are not scored.

validation

Cross-validation design. "loo" withholds one site at a time. "spatial_block" withholds spatially grouped sites, which is a stricter test of prediction into undersampled regions.

n_blocks

Target number of spatial blocks when validation = "spatial_block" and block_assignments = NULL.

block_assignments

Optional vector assigning each empirical site to a spatial block. If supplied, it must have one value per row in input_locs.

spatial_block_repeats

Number of spatial-block layouts to evaluate when validation = "spatial_block" and block_assignments = NULL. Values greater than one repeat the spatial-block validation with rotated spatial partitions and report repeat-level uncertainty.

spatial_block_seed

Optional random seed for repeated spatial-block layouts. The first repeat uses the deterministic default partition; later repeats use random spatial rotations.

primary_metric

Metric used to select the best parameter combination.

dist_prob_func

Function defining the relationship between distance and empirical-site contribution.

rescale_conductance

Logical. If TRUE, scale conductance values by the largest non-missing conductance value before least-cost distances are calculated for surface = "C".

resistance_epsilon

Positive numeric scalar added to resistance values before inversion when surface_values = "resistance".

quiet

Logical. If FALSE, print a short completion message.

Value

A popmaps_tuning object with:

results

One row per parameter combination with average validation metrics.

folds

One row per withheld site and parameter combination.

best

The best row from results according to primary_metric.

References

Massatti R & Winkler DE. (2022) Spatially explicit management of genetic diversity using ancestry probability surfaces. Methods in Ecology and Evolution. http://dx.doi.org/10.1111/2041-210X.13902

Examples

ex_raster <- raster::aggregate(hija_raster, fact = 64)
tuning <- tune_popmaps(
  input_raster = ex_raster,
  input_locs = hija_struc,
  num_sites = c(8, 10),
  num_tested = c(3, 4),
  popmod = c(-0.01, -0.05),
  quiet = TRUE
)
tuning$best
#>   combo_id validation num_sites num_tested popmod half_distance
#> 3        3        loo         8          4  -0.05      13.86294
#>   ten_pct_distance half_distance_km ten_pct_distance_km distance_units
#> 3          46.0517         13.86294             46.0517             km
#>   empirical_pt_dist n_validation_repeats n_validation_folds n_folds n_scored
#> 3                 5                    1                 16      16       16
#>   n_training_min failed_folds       mae      rmse hellinger dominant_accuracy
#> 3             15            0 0.1008275 0.1139513 0.1481097            0.8125
#>   dominant_probability mae_repeat_sd rmse_repeat_sd hellinger_repeat_sd
#> 3            0.7131003            NA             NA                  NA
#>   dominant_accuracy_repeat_sd dominant_probability_repeat_sd
#> 3                          NA                             NA