Prepare a POPMAPS interpolation surface

prepare_popmaps_surface() records the scientific meaning of a raster before it is used for POPMAPS interpolation or surface comparison. Geographic surfaces (surface = "G") use only the raster geometry. Suitability- or conductance-weighted surfaces (surface = "C") use raster values to define relative movement or gene-flow connectivity.

This helper creates a validated surface object for modern least-cost interpolation, tuning, and candidate-surface comparison workflows.

Usage

prepare_popmaps_surface(
  input_raster,
  surface = c("G", "C"),
  surface_values = c("suitability", "conductance", "resistance"),
  mask = NULL,
  barrier = NULL,
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps)
)

Arguments

input_raster

A terra::SpatRaster, legacy raster::RasterLayer, or path to a raster file.

surface

Character. "G" uses raster geometry only. "C" uses raster values as a conductance-like landscape surface.

surface_values

Character. Meaning of raster values when surface = "C". "suitability" and "conductance" use values directly; "resistance" converts values to conductance using an inverse transform. Ignored when surface = "G".

mask

Optional raster with the same geometry as input_raster. Non-zero, non-NA cells mark cells eligible for prediction. This is kept separate from conductance because a prediction mask is not necessarily a movement barrier.

barrier

Optional raster with the same geometry as input_raster. Non-zero, non-NA cells mark cells that should be treated as non-traversable in modern least-cost workflows.

rescale_conductance

Logical. If TRUE, divide conductance by the largest non-missing conductance value after any resistance conversion. This preserves zero-valued barriers while putting the maximum conductance on a 0-1 scale. The default is FALSE to preserve legacy POPMAPS behavior for MaxEnt logistic suitability rasters.

resistance_epsilon

Positive numeric scalar added to resistance values before inversion to avoid infinite conductance when resistance is zero.

Value

A popmaps_surface object containing the original grid, optional conductance raster, optional mask and barrier rasters, and transformation metadata.

Examples

geographic <- prepare_popmaps_surface(hija_raster, surface = "G")
suitability <- prepare_popmaps_surface(
  hija_raster,
  surface = "C",
  surface_values = "suitability"
)