Skip to contents

Suggest a POPMAPS tuning grid from a candidate surface

Source: R/tune_popmaps.R
suggest_surface_tuning_grid.Rd

suggest_surface_tuning_grid() is the surface-aware companion to suggest_tuning_grid(). It derives empirical_pt_dist and popmod from empirical sampling-site distances measured over the selected surface. For surface = "G" those distances are geographic kilometers. For surface = "C" they are least-cost distances through a suitability, conductance, or resistance surface.

Usage

suggest_surface_tuning_grid(
  input_raster,
  input_locs,
  surface = "G",
  surface_values = c("suitability", "conductance", "resistance"),
  num_sites = NULL,
  num_tested = NULL,
  empirical_pt_dist_probs = c(0.05, 0.1, 0.25),
  distance_weights = c(0.95, 0.75, 0.5, 0.25, 0.1, 0.05),
  distance_reference = c("median", "mean"),
  max_num_tested = 8,
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps)
)

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.

num_sites

Integer vector. Candidate pool sizes to evaluate.

num_tested

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

empirical_pt_dist_probs

Distance quantiles used to suggest empirical_pt_dist, after always including zero.

distance_weights

Desired weights retained at the reference distance; converted to popmod values with log(weight) / reference_distance.

distance_reference

Which site-distance summary to use as the reference distance for popmod.

max_num_tested

Maximum automatically suggested num_tested value.

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".

Value

A popmaps_tuning_grid list.

Examples

ex_raster <- terra::rast(raster::aggregate(hija_raster, fact = 240))
grid <- suggest_surface_tuning_grid(
  input_raster = ex_raster,
  input_locs = hija_struc,
  surface = "G"
)
grid$distance_units
#> [1] "km"