dispersal_simulationR: Simulation of species dispersal processes

In fmachados/grinnell: Dispersal Simulations Based on Ecological Niches

Simulation of species dispersal processes

Description

multistep simulation of species dispersal to reconstruct areas that have been or could be accessed and/or colonized based on environmental suitability and user-defined dispersal parameters.

Usage

dispersal_simulationR(data, suit_layers, 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, results_by = "scenario",
                      return = "all", set_seed = 1,
                      write_to_directory = FALSE, write_all = FALSE,
                      raster_format = "GTiff", output_directory)

scenario_wise_simulation(data, suit_layers, 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, return = "all",
                         set_seed = 1, write_to_directory = FALSE,
                         write_all = FALSE, raster_format = "GTiff",
                         output_directory)

event_wise_simulation(data, suit_layers, 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, return = "all",
                      set_seed = 1, write_to_directory = FALSE,
                      raster_format = "GTiff", output_directory)

Arguments

data	data.frame containing geographic coordinates of occurrences of the species of interest. Mandatory columns are: "species", "longitude", "latitude", in that order. Optionally, a fourth column "suitability" should be used when sampling_rule = "suitability".
suit_layers	(character) vector of names of suitability layers to be used as distinct scenarios. If more than one, the layer names must be ordered starting from first to last scenario. All layers must have the same extent, resolution, number of cells, and projection. Layer names should include parent directory if needed.
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 scenario or 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.
results_by	(character) how to run replicates and return results. Options are: "scenario" or "event". If "scenario" the replicates are produced for each of the scenarios represented by layers in suit_layers. If "event", replicates are produced per dispersal event. Default = "scenario"
return	(character) the results to be returned or written. Options are: "all", "accessed", "colonized". Default = "all"
set_seed	(numeric) a seed to be used when sampling data according to starting_proportion. Default = 1.
write_to_directory	(logical) whether to write results in output_directory. Default = FALSE.
write_all	(logical) valid if results_by = "scenario" and write_to_directory = TRUE. Whether or not to write results for all scenarios. The default, FALSE, writes only the final results.
raster_format	(character) format to use for raster layers to be written. Options are: "GTiff" and "ascii". Default = "GTiff.
output_directory	(character) name of the output directory where results should be written. If this directory does not exist, it will be created.

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_layers, otherwise, the first element in dispersal_events will be used and a message will be printed.

Value

If return = "all', all elements described below will be returned as a list. If "accessed" or "colonized" are chosen instead, only the elements corresponding to either "accessed" or "colonized" areas will be returned.

Notice that only final results are returned as part of the list. If views of all scenarios are needed use options to write results in a directory, write_to_directory, write_all, raster_format, and output_directory.

The list returned contains:

• Summary: a list with a summary of scenarios and parameters used

• if results_by = "scenario":

  • A: a binary SpatRaster showing accessed = 1 and non-accessed areas = 0

  • A_mean: a SpatRaster representing mean values of accessibility frequency among replicates

  • A_var: a SpatRaster representing variance among values of accessibility frequency of all replicates

  • A_scenarios: a SpatRaster with values representing the number of the scenario when areas where accessed

  • C: a binary SpatRaster showing colonized = 1 and non-colonized areas = 0

  • C_mean: a SpatRaster representing mean values of frequency of colonization among replicates

  • C_var: a SpatRaster representing variance among values of frequency of colonization of all replicates

  • C_scenarios: a SpatRaster with values representing the number of the scenario when areas where colonized

• if results_by = "event":

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

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

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.

If write_to_directory is set to TRUE, the elements described above and raster layers corresponding to all scenarios (if write_all = TRUE), or events per scenario (depending on results_by) will be written in output_directory.

Examples

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

# simulation
d_s <- dispersal_simulationR(data = records, suit_layers = suitability,
                             replicates = 3, dispersal_events = 5,
                             return = "colonized")

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