Convert EEMS output to a POPMAPS conductance surface

surface_from_eems() converts raster-like EEMS outputs or coordinate/value tables to a surface = "C" POPMAPS surface. Tables must contain x/y coordinates plus one numeric surface-value column. High migration values should usually be treated as conductance; effective resistance-style outputs can be passed with surface_values = "resistance".

Usage

surface_from_eems(
  input,
  value_col = NULL,
  coordinate_cols = NULL,
  template = NULL,
  resolution = NULL,
  buffer = NULL,
  target_cells = 100,
  crs = "",
  surface_values = c("conductance", "resistance", "suitability"),
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps)
)

Arguments

input

A raster-like object/path, data frame, or matrix. Tabular inputs are rasterized using template or a grid derived from their coordinates.

value_col

Surface-value column for tabular inputs. If NULL, common names such as conductance, migration, value, mean, m, or w are detected.

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.

template

Optional raster defining output geometry for tabular inputs.

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.

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

eems_table <- expand.grid(x = 1:3, y = 1:3)
eems_table$migration <- seq(0.2, 1, length.out = nrow(eems_table))
eems_surface <- surface_from_eems(
  eems_table,
  value_col = "migration",
  resolution = 1
)
eems_surface
#> <popmaps_surface>
#>   surface: C
#>   surface values: conductance
#>   transform: identity
#>   rescaled: FALSE
#>   mask: none
#>   barrier: none