| Type: | Package |
| Title: | a Keep It Simple Species Migration Model |
| Version: | 2.0-0 |
| Date: | 2025-05-05 |
| Depends: | R (≥ 3.5.0), Rcpp, terra |
| Description: | Simulating species migration and range dynamics under stable or changing environmental conditions based on a simple, raster-based, deterministic or stochastic migration model. Kissmig runs on binary or quantitative suitability maps, which are pre-calculated with niche-based habitat suitability models (also called ecological niche models (ENMs) or species distribution models (SDMs)). Nobis & Normand (2014), <doi:10.1111/ecog.00930>. |
| License: | GPL (≥ 3) |
| URL: | https://purl.oclc.org/wsl/kissmig |
| Encoding: | UTF-8 |
| LazyData: | true |
| Imports: | methods, stats |
| LinkingTo: | Rcpp |
| RoxygenNote: | 7.3.2 |
| NeedsCompilation: | yes |
| Packaged: | 2025-05-05 15:28:02 UTC; work |
| Author: | Michael P. Nobis [cre, aut], Signe Normand [ctb], Dominik F. Landolt [ctb] |
| Maintainer: | Michael P. Nobis <michael.nobis@wsl.ch> |
| Repository: | CRAN |
| Date/Publication: | 2025-05-05 16:20:02 UTC |
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 |
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
|
signed |
bool. If |
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 |
pcor |
probability [0,1] that corner cells are considered in the 3x3 cell neighborhood.
Default setting is |
seed |
integer used to set the seed of the random number generator.
Default setting is |
n_threads |
integer of the number of threads for parallel computing.
Default setting is |
n_random |
integer defining the amount of random numbers for the simulation.
Default setting is |
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, 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. doi:10.1111/ecog.00930
KISSMig homepage https://purl.oclc.org/wsl/kissmig.
See Also
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
Get accessiblity map from kissmig output
Description
kissmigAccess calculates an accessibility map from a kissmig output of first occurrence (type="FOC").
These maps allows the integration of limited migration in species distribution models and macroecological analyses.
Usage
kissmigAccess(grd, rel = FALSE)
Arguments
grd |
SpatRaster with one layer as first occurrence generated by kissmig. |
rel |
bool. If |
Details
kissmig maps of first occurrences show values of the first iteration step a raster cell was colonized. Early
colonized cells have low values, late colonized cells high values. These values are the opposite of accessibility,
which is high for early colonized, and low for late colonized cells. kissmigAccess simply calculates for each
cell the accessibility as the difference between the cell value and max(grd)+1. Cells which have never been
colonized remain unchanged (value 0).
See Also
Get a simple suitability map
Description
kissmigDummyS is a support function to generate simple climate suitability maps
for example code.
Usage
kissmigDummyS(mean, sd)
Arguments
mean |
number of the mean temperature (degree celsius) of the suitability distribution. |
sd |
number of the temperature standard deviation (degree celsius) of the suitability distribution. |
Details
kissmigDummyS returns a SpatRaster of a simple climate suitability map for Europe based on mean annual temperature. It uses
data of WorldClim and calculates suitability as a normal distribution defined by mean and sd
of mean annual temperature. The density function is linearly rescaled to a maximum of 1, the maximum suitability
used in kissmig.
References
See Also
Define a geographic origin
Description
kissmigOrigin is a support function to define a rectangular origin for a kissmig call.
Usage
kissmigOrigin(grd, x, y, size)
Arguments
grd |
SpatRaster with one layer as reference. |
x |
integer as lower left x-coordinate of geographic origin. |
y |
integer as lower left y-coordinate of geographic origin. |
size |
number as size of the quadratic origin. |
Details
kissmigOrigin returns a SpatRaster with one layer characterized by the reference
grd. Cell values are set to 0, except for cells of the origin defined by
ext(x, x+size, y, y+size) which are set to 1.
See Also
Map of annual mean temperature covering Europe
Description
Map of the bioclimatic variable BIO1 (annual mean temperature in °C) covering Europe.
Usage
wcl_bio1_europe
Format
A PackedSpatRaster object generated by terra::wrap(); use 'terra::rast()'
to unpack and load it as SpatRaster.
Details
The map is based on WorldClim version 2.1 climate data for 1970-2000 and has a spatial resolution of five minutes.
Source
https://geodata.ucdavis.edu/climate/worldclim/2_1/base/wc2.1_5m_bio.zip