adaptive_tune_popmaps() samples parameter combinations from a
data-adaptive search space, evaluates them with the same leave-one-site-out
scoring used by tune_popmaps(), then optionally refines sampling around
the best-performing region.
Usage
adaptive_tune_popmaps(
input_raster = "",
input_locs = "",
surface = "G",
empirical_pt_dist = NULL,
num_sites = NULL,
num_tested = NULL,
popmod = NULL,
n_initial = 50,
n_refine = 50,
method = c("latin_hypercube", "random"),
seed = NULL,
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)
},
quiet = TRUE
)Arguments
- input_raster
A
terra::SpatRaster,raster::RasterLayer, or path to a raster file defining the interpolation surface.- input_locs
A data frame or matrix with sampling location name, longitude, latitude, and one or more ancestry coefficient columns.
- surface
Character. Currently only
"G"is supported.- empirical_pt_dist
Optional numeric vector or range for the rarefaction distance search space. If
NULL, values are suggested from site distances.- num_sites
Optional integer candidate site-pool sizes.
- num_tested
Optional integer candidate numbers of sites used in each prediction.
- popmod
Optional numeric vector or range for the distance-decay search space. If
NULL, values are suggested from site distances.- n_initial
Number of initial parameter combinations to sample.
- n_refine
Number of additional combinations to sample around the best initial region.
- method
Search method.
"latin_hypercube"stratifies samples across each parameter range;"random"samples independently.- seed
Optional random seed for reproducibility.
- 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"andblock_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"andblock_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.
- quiet
Logical. If
FALSE, print a short completion message.
Value
A popmaps_adaptive_tuning object. It has the same results,
folds, and best elements as tune_popmaps(), plus a search element
describing the sampled search.
Examples
ex_raster <- raster::aggregate(hija_raster, fact = 240)
adaptive <- adaptive_tune_popmaps(
input_raster = ex_raster,
input_locs = hija_struc,
n_initial = 6,
n_refine = 4,
seed = 1,
quiet = TRUE
)
adaptive$best
#> combo_id validation num_sites num_tested popmod half_distance
#> 3 3 loo 15 3 -0.0148358 46.72127
#> ten_pct_distance half_distance_km ten_pct_distance_km distance_units
#> 3 155.2047 46.72127 155.2047 km
#> empirical_pt_dist n_validation_repeats n_validation_folds n_folds n_scored
#> 3 92.43295 1 16 16 16
#> n_training_min failed_folds mae rmse hellinger dominant_accuracy
#> 3 15 0 0.1085993 0.1210316 0.1648731 0.8125
#> dominant_probability mae_repeat_sd rmse_repeat_sd hellinger_repeat_sd
#> 3 0.6842342 NA NA NA
#> dominant_accuracy_repeat_sd dominant_probability_repeat_sd
#> 3 NA NA