Skip to contents

Prepare Data Required To Perform A Simulation

Source: R/initialise.R
initialise.Rd

This function generates a sim_data object which contains all the necessary information needed to run a simulation by the sim function. Note that the input maps (n1_map and K_map) must be in the Cartesian coordinate system.

Usage

initialise(
  n1_map,
  K_map,
  K_sd = 0,
  r,
  r_sd = 0,
  growth = "gompertz",
  A = NA,
  dens_dep = c("K2N", "K", "none"),
  border = c("absorbing", "reprising"),
  kernel_fun = "rexp",
  ...,
  max_dist = NA,
  calculate_dist = TRUE,
  dlist = NULL,
  progress_bar = FALSE,
  quiet = TRUE,
  cl = NULL
)

initialize(
  n1_map,
  K_map,
  K_sd = 0,
  r,
  r_sd = 0,
  growth = "gompertz",
  A = NA,
  dens_dep = c("K2N", "K", "none"),
  border = c("absorbing", "reprising"),
  kernel_fun = "rexp",
  ...,
  max_dist = NA,
  calculate_dist = TRUE,
  dlist = NULL,
  progress_bar = FALSE,
  quiet = TRUE,
  cl = NULL
)

Arguments

n1_map

SpatRaster object with one layer; population numbers in every square at the first time step

K_map

SpatRaster object with one layer; carrying capacity map (if K is constant across time) or maps (if K is time-varying)

K_sd

numeric vector of length 1 with value >= 0 (default 0); this parameter can be used if additional environmental stochasticity is required; if K_sd > 0, a random numbers are generated from a log-normal distribution with the mean K_map and standard deviation K_sd

r

numeric vector of length 1; intrinsic population growth rate

r_sd

numeric vector of length 1 with value >= 0 (default 0); if additional demographic stochasticity is required, r_sd > 0 is the standard deviation for a normal distribution around r (defined for each time step)

growth

character vector of length 1; the name of a population growth function, either defined in growth or provided by the user (case-sensitive, default "gompertz")

A

numeric vector of length 1; strength of the Allee effect (see the growth function)

dens_dep

character vector of length 1 specifying if the probability of settling in a target square is (case-sensitive, default "K2N"):

  • "none" - fully random,

  • "K" - proportional to the carrying capacity of a target square,

  • "K2N" - density-dependent, i.e. proportional to the ratio of carrying capacity of a target square to the number of individuals already present in a target square

border

character vector of length 1 defining how to deal with borders (case-sensitive, default "absorbing"):

  • "absorbing" - individuals that disperse outside the study area are removed from the population

  • "reprising" - cells outside the study area are not allowed as targets for dispersal

kernel_fun

character vector of length 1; name of a random number generation function defining a dispersal kernel (case-sensitive, default "rexp")

...

any parameters required by kernel_fun

max_dist

numeric vector of length 1; maximum distance of dispersal to pre-calculate target cells

calculate_dist

logical vector of length 1; determines if target cells will be precalculated

dlist

list; target cells at a specified distance calculated for every cell within the study area

progress_bar

logical vector of length 1; determines if progress bar for calculating distances should be displayed (used only if dlist is NULL)

quiet

logical vector of length 1; determines if messages for calculating distances should be displayed (used only if dlist is NULL)

cl

cluster object created by makeCluster

Value

Object of class sim_data which inherits from list. This object contains all necessary information to perform a simulation using sim function.

Details

The most time-consuming part of computations performed by the sim function is the simulation of dispersal. To speed it up, a list containing indexes of target cells at a specified distance from a focal cell, is calculated in advance and stored in a dlist slot. To speed things up even more, these calculations can be done in parallel, providing that a cluster object created by makeCluster is specified using the cl parameter. The parameter max_dist sets the maximum distance at which this pre-calculation is done. If max_dist is NULL then it is set to 0.9 quantile from the kernel_fun.

NA in input maps stands for cells that are outside the study area.

K_get_interpolation function can be used to prepare K_map that changes in time. This may be useful, when simulating environmental change or exploring the effects of ecological disturbances.

Examples

if (FALSE) {

# input maps
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"))
K_small_changing <- rast(system.file("input_maps/K_small_changing.tif",
                         package = "rangr"))

# basic example
sim_data_1 <- initialise(
  n1_map = n1_small,
  K_map = K_small,
  r = log(2),
  rate = 1 / 1e3
)

# example with changing environment
K_interpolated <- K_get_interpolation(
  K_small_changing,
  K_time_points = c(1, 25, 50)
)

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

# example with progress bar
sim_data_3 <- initialise(
  n1_map = n1_small, K_map = K_small, K_sd = 5, r = log(5),
  r_sd = 4, growth = "ricker", rate = 1 / 200,
  max_dist = 5000, dens_dep = "K2N", progress_bar = TRUE
)

# example with parallelization
library(parallel)
cl <- makeCluster(detectCores())

sim_data_4 <- initialise(
  n1_map = n1_small,
  K_map = K_small,
  r = log(2),
  rate = 1 / 1e3,
  cl = cl,
  progress_bar = TRUE
)
stopCluster(cl)
}