This function generates a `sim_data`

object containing all the necessary
information required to run a simulation by the `sim`

function. The
input maps (`n1_map`

and `K_map`

) can be in the Cartesian or longitude/latitude
coordinate system.

## Arguments

- n1_map
`SpatRaster`

object with one layer; population numbers in every grid cell 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`

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

- 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

- 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

- quiet
logical vector of length 1; determines if messages should be displayed

## 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.
The `max_dist`

parameter sets
the maximum distance at which this pre-calculation is performed. If `max_dist`

is `NULL`

, it is set to 0.99 quantile from the `kernel_fun`

.
All distance calculations are always based on metres if the input maps are
latitude/longitude. For planar input maps, distances are calculated in map
units, which are typically metres, but check the `crs()`

if in doubt.

If the input maps are in the Cartesian coordinate system and the grid cells
are squares, then
the distances between cells are calculated using the `distance`

function from the `terra`

package. These distances are later divided by the
resolution of the input maps.

For input maps with grid cells in shapes other than squares (e.g. with
rectangular cells or longitude/latitude coordinate system), the distance
resolution is calculated by finding the shortest distance between each
"queen" type neighbor. All distances calculated by the `distance`

function are further divided by this distance resolution.
To avoid discontinuities in the distances at which the target cells are located,
an additional parameter `dist_bin`

is calculated as half of the maximum
distance between each "queen" type neighbour. It is used to expand the
distances at which target cells are located from a single number to a range.

NA in the input maps represents cells outside the study area.

The `K_get_interpolation`

function can be used to prepare `K_map`

that changes
over time. This may be useful, when simulating environmental change or
exploring the effects of ecological disturbances.

## References

Hijmans R (2024). terra: Spatial Data Analysis. R package version 1.7-81, https://rspatial.github.io/terra/, https://rspatial.org/

Solymos P, Zawadzki Z (2023). pbapply: Adding Progress Bar to '*apply' Functions. R package version 1.7-2, https://CRAN.R-project.org/package=pbapply.

## Examples

```
if (FALSE) { # \dontrun{
# 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"))
n1_small_lon_lat <- rast(system.file("input_maps/n1_small_lon_lat.tif", package = "rangr"))
K_small_lon_lat <- rast(system.file("input_maps/K_small_lon_lat.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 lon/lat rasters
sim_data_3 <- initialise(
n1_map = n1_small_lon_lat,
K_map = K_small_lon_lat,
r = log(2),
rate = 1 / 1e3
)
# example without progress bar and messages
sim_data_4 <- initialise(
n1_map = n1_small, K_map = K_small, K_sd = 0.1, r = log(5),
r_sd = 4, growth = "ricker", rate = 1 / 200,
max_dist = 5000, dens_dep = "K2N", progress_bar = FALSE, quiet = TRUE
)
} # }
```