Skip to contents

Create candidate surfaces from a raster stack

Source: R/input-converters.R
surfaces_from_raster_stack.Rd

surfaces_from_raster_stack() converts each layer of a multi-layer raster into a named popmaps_surface object. This is a convenience helper for comparing several user-supplied candidate surfaces with compare_popmaps_surfaces().

Usage

surfaces_from_raster_stack(
  input_raster,
  surface = "C",
  surface_values = "suitability",
  names = NULL,
  include_geographic = FALSE,
  geographic_name = "geographic",
  mask = NULL,
  barrier = NULL,
  rescale_conductance = FALSE,
  resistance_epsilon = sqrt(.Machine$double.eps)
)

Arguments

input_raster

A multi-layer terra::SpatRaster, legacy raster stack or brick, or raster file path.

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

names

Optional candidate surface names. Defaults to raster layer names when available.

include_geographic

Logical. If TRUE, add a geographic surface using the first layer's geometry.

geographic_name

Name for the optional geographic surface.

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 named list of popmaps_surface objects.

Examples

r1 <- terra::rast(nrows = 2, ncols = 2, xmin = 0, xmax = 2, ymin = 0, ymax = 2)
terra::values(r1) <- c(0.2, 0.4, 0.6, 0.8)
r2 <- r1 * 2
names(r1) <- "suitability"
names(r2) <- "resistance"
candidates <- surfaces_from_raster_stack(
  c(r1, r2),
  surface = "C",
  surface_values = c("suitability", "resistance"),
  include_geographic = TRUE
)
names(candidates)
#> [1] "geographic"  "suitability" "resistance"