Create a POPMAPS surface from coordinates — surface_from

surface_from_points() builds a simple prediction grid around sampling coordinates, then returns a prepare_popmaps_surface() object. This helper is primarily for geographic interpolation (surface = "G") or template creation when users have empirical ancestry locations but have not supplied a raster yet. A constant conductance surface can also be created with surface = "C", but that is a neutral grid rather than a biologically informed landscape surface.

Usage

surface_from_points(
  points,
  coordinate_cols = NULL,
  resolution = NULL,
  buffer = NULL,
  target_cells = 100,
  crs = "",
  values = 1,
  surface = "G",
  surface_values = c("suitability", "conductance", "resistance"),
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps)
)

Arguments

points: A data frame, matrix, sf object, or terra::SpatVector containing point coordinates. Data frames may be raw x/y coordinates or POPMAPS-style location tables where columns 2 and 3 are longitude and latitude.
coordinate_cols: Optional coordinate column names or integer positions for data frame or matrix inputs. If NULL, common coordinate names are detected first; otherwise POPMAPS-style columns 2 and 3 are used when the first column is non-numeric, and columns 1 and 2 are used as a final fallback.
resolution: Raster cell size in coordinate units. If NULL, a resolution is chosen so the longest coordinate span has about target_cells cells.
buffer: Extra distance added around the coordinate bounding box. If NULL, the larger of one cell or five percent of the longest coordinate span is used.
target_cells: Approximate number of cells along the longest coordinate axis when resolution = NULL.
crs: Coordinate reference system assigned to the created raster. The default "" leaves the CRS unset; pass a CRS string when the generated grid should carry projection metadata.
values: Numeric scalar or vector of raster values. A scalar fills the grid. A vector must have one value per raster cell.
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".
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.

Examples

coords <- data.frame(
  site = paste0("s", 1:3),
  lon = c(0, 1, 2),
  lat = c(0, 1, 0),
  axis1 = c(0.9, 0.5, 0.1),
  axis2 = c(0.1, 0.5, 0.9)
)
geographic <- surface_from_points(coords, resolution = 1, buffer = 0)
geographic
#> <popmaps_surface>
#>   surface: G
#>   raster values: ignored for distances
#>   mask: none
#>   barrier: none