disp: Simulating Dispersal

In rangr: Mechanistic Simulation of Species Range Dynamics

Simulating Dispersal

Description

This function simulates dispersal for each grid cell by calculating the number of individuals dispersing out of the cell and the number of individuals dispersing into the cell.

Usage

disp(
  N_t,
  id,
  id_matrix,
  data_table,
  kernel,
  dens_dep,
  dlist,
  id_within,
  within_mask,
  border,
  planar,
  dist_resolution,
  max_dist,
  dist_bin,
  ncells_in_circle,
  cl = NULL
)

Arguments

N_t	integer matrix representing population numbers at a single time step; NA indicates cells outside the study area
id	SpatRaster object (of the same size as N_t) with cell identifiers
id_matrix	id in matrix format
data_table	matrix that contains information about all cells in current time points
kernel	function defining dispersal kernel
dens_dep	character vector of length 1 specifying if the probability of settling in a target grid cell is (case-sensitive, default "K2N"): "none" - fully random, "K" - proportional to the carrying capacity of a target cell, "K2N" - density-dependent, i.e. proportional to the ratio of carrying capacity of a target cell to the number of individuals already present in a target cell
dlist	list with identifiers of target cells at a specified distance from a focal cell
id_within	integer vector with identifiers of cells inside the study area
within_mask	logical matrix that specifies boundaries of the study area
border	character vector of length 1 defining how to deal with borders (case-sensitive, default "absorbing"): "reprising" - cells outside the study area are not allowed as targets for dispersal "absorbing" - individuals that disperse outside the study area are removed from the population
planar	logical vector of length 1; TRUE if input maps are planar rasters, FALSE if input maps are lon/lat rasters
dist_resolution	integer vector of length 1; dimension of one side of one cell of id; in case of an irregular grid or lon/lat raster it is calculated during initialisation
max_dist	distance (in the same units as used in the raster id) specifying the maximum range at which identifiers of target dispersal cells are determined in advance (see initialise)
dist_bin	numeric vector of length 1 with value ⁠>= 0⁠; in case of an irregular grid or lon/lat raster it is calculated during initialisation
ncells_in_circle	numeric vector; number of cells on each distance
cl	if simulation is done in parallel, the name of a cluster object created by makeCluster

Details

The function is used by sim internally and is not intended to be called by the user. The parameters for this function are passed from a sim_data object created by initialise.

Dispersal distance is expressed in original spatial units of the SpatRaster provided to the sim function (n1_map and K_map). However, it is internally converted to units of the simulation (i.e. the size of a single cell) by calculating round(distance/resolution). If the selected dispersal distance is smaller than resolution/2, the individual does not disperse effectively and remains in the same cell. The dispersal rate (proportion of dispersing individuals) can be estimated from the dispersal kernel probability function by calculating the probability that the dispersal distance is greater than resolution/2.

Value

The function returns a list that contains two matrices:

em - emigration matrix with the number of individuals that dispersed from each cell

im - immigration matrix with the number of individuals that dispersed to each cell

Examples

# data preparation
library(terra)

n1_small <- rast(system.file("input_maps/n1_small.tif", package = "rangr"))
K_small <- rast(system.file("input_maps/K_small.tif", package = "rangr"))

sim_data <- initialise(
  n1_map = n1_small,
  K_map = K_small,
  r = log(2),
  rate = 1 / 1e3
)

# disp
disp_output <- disp(
  N_t = sim_data$n1_map,
  id = unwrap(sim_data$id),
  id_matrix = as.matrix(unwrap(sim_data$id), wide = TRUE),
  data_table = sim_data$data_table,
  kernel = sim_data$kernel,
  dens_dep = sim_data$dens_dep,
  dlist = sim_data$dlist,
  id_within = sim_data$id_within,
  within_mask = sim_data$within_mask,
  border = sim_data$border,
  planar = sim_data$planar,
  dist_resolution = sim_data$dist_resolution,
  max_dist = sim_data$max_dist,
  dist_bin = sim_data$dist_bin,
  ncells_in_circle = sim_data$ncells_in_circle
)

# immigration and emigration matrices
names(disp_output)

rangr documentation built on April 12, 2025, 1:40 a.m.