forward_simulation: Simulation of species dispersal to future

In fmachados/grinnell: Dispersal Simulations Based on Ecological Niches

Simulation of species dispersal to future

Description

Simulation of species dispersal to identify areas that could be accessed and colonized based on environmental suitability and user-defined dispersal parameters.

Usage

forward_simulation(suit_layer, data = NULL, suit_forward = NULL,
                   barriers = NULL, starting_proportion = 0.5,
                   proportion_to_disperse = 1, sampling_rule = "random",
                   dispersal_kernel = "normal",
                   kernel_spread = 1, max_dispersers = 4,
                   dispersal_events = 25, replicates = 10,
                   threshold = 5, set_seed = 1,
                   out_format = "GTiff", output_directory,
                   overwrite = FALSE)

Arguments

suit_layer	(character) name of (local) raster layer containing values of suitability for the species of interest in the study region over which the simulation will run. The name of the layer name should include parent directory if needed.
data	(optional) data.frame containing geographic coordinates of occurrences of the species of interest. Columns must be: "species", "longitude", "latitude", in that order.
suit_forward	(optional) name of (local) raster layer(s) containing values of suitability for the species of interest in the study region over which the simulation will run. If more than one, layer names must be ordered from first to last scenario. These layers must have the same extent, resolution, number of cells, and projection than suit_layer. Layer names should include parent directory if needed.
barriers	(optional) SpatRaster representing dispersal barriers for the species. This layer must have the same extent and projection than suit_layers. The only values allowed in this layer are 1 and NA; 1 = barrier. Default = NULL.
starting_proportion	(numeric) proportion of data to be used as starting points for the simulation. Default = 0.5. All data is used if a value of 1 is defined.
proportion_to_disperse	(numeric) proportion of colonized cells from which dispersers will start a new dispersal event; default = 1.
sampling_rule	(character) rule to be used to sample a starting_proportion of data and a proportion_to_disperse from colonized cells to run dispersal simulation steps. Options are: "random" and "suitability". Using the option "suitability" prioritizes records in with higher suitability values. Default = "random".
dispersal_kernel	(character) dispersal kernel (dispersal function) used to simulate the movement of the species. Options are: "normal", "log_normal". Default = "normal".
kernel_spread	(numeric) standard deviation for the dispersal_kernel. Default = 1.
max_dispersers	(numeric) maximum number of dispersers that depart from each colonized pixel. Depending on suitability this number will automatically decrease in areas with low suitability values. Default = 4.
dispersal_events	(numeric) number of dispersal events to happen per scenario. A vector of multiple values could be used to define different dispersal events for distinct scenarios. See details; default = 25.
replicates	(numeric) number of times to repeat the simulation per dispersal event, depending on results_by. Default = 10.
threshold	(numeric) percentage to be considered when excluding accessed or colonized cells with lower values. Default = 5.
set_seed	(numeric) a seed to be used when sampling data according to starting_proportion. Default = 1.
out_format	(character) format of raster layers to be written in output_directory. Options are "ascii" and "GTiff". Default = "GTiff".
output_directory	(character) name of the output directory to be created in which all results will be written.
overwrite	(logical) whether or not to overwrite the output_directory if it already exists. Default = FALSE.

Details

Defining a vector of multiple values in dispersal_events could be useful when distinct scenarios represent different periods of time, or if a reduced number of events need to be simulated in the last scenario. If a vector of values is defined in dispersal_events, the length of this vector must match the length of suit_forward + 1, otherwise, the first element in dispersal_events will be used and a warning message will be printed.

Value

A list containing:

• occurrences found in suitable areas in the scenario where the simulation started.

• all scenarios considered for the simulation

• a list with the parameters used during the simulation

• a SpatRaster with values representing the number of the dispersal event when areas where accessed

• a SpatRaster with values representing the number of the dispersal event when areas where colonized

• if defined, the SpatRaster used in barriers, else NULL

The complete set of results derived from data preparation and the simulation is written in output_directory. These results include the ones mentioned above (except barriers), plus:

• if needed, a folder containing results from correcting suitability layer(s) with barriers

• other raster layers representing statistics of accessibility: mean and variance

• a figure representing accessed and colonized areas per dispersal events, and the occurrences used for simulation

• a simple report from the simulation process

The number of dispersal events in results is continuous among scenarios. If 10 dispersal events are defined and multiple scenarios exist in suit_layers, the first dispersal event in the second scenario will be number 11.

Examples

# data
data("records", package = "grinnell")
suitability <- system.file("extdata/suitability.tif", package = "grinnell")

# simulation current
f_s <- forward_simulation(suit_layer = suitability, data = records,
                          dispersal_kernel = "normal",
                          kernel_spread = 2, max_dispersers = 2,
                          dispersal_events = 15, replicates = 3,
                          output_directory = file.path(tempdir(), "eg_fsim"))

# simulation current and future

suitf <- system.file("extdata/suitability_fut.tif", package = "grinnell")

f_s1 <- forward_simulation(suit_layer = suitability, data = records,
                           suit_forward = suitf, dispersal_kernel = "normal",
                           kernel_spread = 2, max_dispersers = 2,
                           dispersal_events = 15, replicates = 3,
                           output_directory = file.path(tempdir(), "eg_fsim1"))

# simulation current and future using dispersal barriers
barrier <- terra::rast(system.file("extdata/barrier.tif",
                                   package = "grinnell"))

f_s2 <- forward_simulation(suit_layer = suitability, data = records,
                           suit_forward = suitf, barriers = barrier,
                           dispersal_kernel = "normal",
                           kernel_spread = 2, max_dispersers = 2,
                           dispersal_events = 15, replicates = 3,
                           output_directory = file.path(tempdir(), "eg_fsim2"))

fmachados/grinnell documentation built on Jan. 29, 2024, 6:48 p.m.