kissmig: Run a simple dynamic species distribution model

In kissmig: a Keep It Simple Species Migration Model

Run a simple dynamic species distribution model

Description

kissmig runs a simple, raster-based, stochastic model to simulate species distribution dynamics driven by environmental suitability and the migration ability of the species.

Usage

kissmig(
  O,
  S = NULL,
  it,
  type = "FOC",
  signed = FALSE,
  pext = 1,
  pcor = 0.2,
  seed = NULL,
  n_threads = 1,
  n_random = 10000
)

Arguments

O	SpatRaster with a single layer of the initial species distribution as the geographic origin.
S	SpatRaster with a single or multiple suitability layers. For the default setting NULL the suitability of all cells is set to 1.0 (maximum).
it	integer of the number of iteration steps representing the species' migration ability and applied to each suitability layer of S.
type	string defining the type of resulting map. Default setting is "FOC". "DIS" final species distribution after the last iteration step "FOC" number of the iteration step of the first occurrence "LOC" number of the iteration step of the last occurrence "NOC" number of the iteration steps with occurrence
signed	bool. If TRUE, the sign indicates whether the cells was colonized (positive) or uncolonized (negative) after the last iteration step. Used in combination with "FOC", "LOC", or "NOC". Default setting is FALSE.
pext	probability [0,1] that a colonized cell becomes uncolonized between iteration steps, i.e., without recolonization the species gets locally extinct. Default setting is 1.0.
pcor	probability [0,1] that corner cells are considered in the 3x3 cell neighborhood. Default setting is 0.2.
seed	integer used to set the seed of the random number generator. Default setting is NULL.
n_threads	integer of the number of threads for parallel computing. Default setting is 1 (i.e., no parallel computing).
n_random	integer defining the amount of random numbers for the simulation. Default setting is 10000.

Details

Starting from an initial species distribution O as the geographic origin, kissmig simulates species distributions in an environment characterized by a single or multiple (time series) suitability layers S. The simulation uses a simple 3x3 cell algorithm, applied it iteration steps. Colonized cells have value 1, uncolonized cells value 0, and environmental suitability values vary binary or continuously between 0 (unsuitable) and 1 (suitability maximum). In case S consists of multiple suitability layers, it is applied to each layer.

Between iteration steps, colonized cells become extinct with the probability pext, and for a recolonization or new colonization event corner cells within the 3x3 neighborhood are considered with probability pcor (pcor=0.2 produces more realistic circular spread patterns in homogeneous environments - see Nobis and Normand 2014, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/ecog.00930")}).

To get reproducible results, the seed of the R random number generator can be set using the seed parameter. In addition, for reproducibility the value of n_random needs to stay the same between simulations. Changing one of these parameters will generate stochastically different results - even with binary suitability due to the probability pcor of the corner events.

Signed results with signed=TRUE can be generated to get in addition to the result type "FOC", "LCO", or "NOC" with the same call the final distribution ("DIS") with positive values being colonized and negative values being previously colonized but uncolonized after the last iteration step.

Runtime optimization by parallel computing can be initialized by increasing n_threads. Depending on the hardware used, it is advantageous to set n_threads significantly higher than the number of available CPU cores. To figure out optimal settings compare execution time with n_threads set to 2^x (e.g. 4, 8, 16, 32, ...). The implementation uses the OpenMP specification for parallel programming, https://www.openmp.org/.

References

• Nobis, M.P. and Normand, S. 2014. KISSMig - a simple model for R to account for limited migration in analyses of species distributions. Ecography 37: 1282-1287. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/ecog.00930")}

• KISSMig homepage https://purl.oclc.org/wsl/kissmig.

See Also

kissmigAccess, kissmigOrigin

Examples

# generate some SpatRaster data to run kissmig

s <- kissmigDummyS(mean = 12, sd = 3) # suitability map
o <- kissmigOrigin(s, 8.0, 44.5, 0.5) # geographic origin
l <- s >= 0 # land mask used for visualization below
plot(s, asp = 1.0, main = "Climate suitability & origin (in red)")
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

# run kissmig with different types of output

k <- kissmig(o, s, it = 150, type = "DIS")
plot(k*l, asp = 1.0, main = "Final distribution (DIS)")
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

sb <- s>0.5 # binary suitability for an arbitrary threshold of 0.5
k <- kissmig(o, sb, it = 150, type = "DIS")
plot(k*l, asp = 1.0, main = "Final distribution (DIS) using binary suitability")
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

k <- kissmig(o, s, it = 150, type = "FOC")
plot(k*l, asp = 1.0, main = "First iteration step of occurrence (FOC)",
     col = c("lightgrey", map.pal("viridis", n = max(values(k))+1)))
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

a <- kissmigAccess(k, rel = TRUE)
plot(a*l, asp = 1.0, main = "Accessibility based on 'FOC', relative values",
     col = c("lightgrey", map.pal("viridis", n = max(values(k))+1)))
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

k <- kissmig(o, s, it = 150, type = "NOC")
plot(k*l, asp = 1.0, main = "Number of iteration steps with occurrences (NOC)",
     col = c("lightgrey", map.pal("viridis", n = max(values(k))+1)))
plot(o, col = c(rgb(0,0,0,0), "red"), legend = FALSE, add = TRUE) # add origin

kissmig documentation built on June 8, 2025, 11 a.m.