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`

## 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

## 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`

.

## Examples

```
# data preparation
library(terra)
#> terra 1.7.83
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)
#> [1] "em" "im"
```