M_simulationR: Simulation of species accessible areas (M) R version

In fmachados/grinnell: Dispersal Simulations Based on Ecological Niches

Simulation of species accessible areas (M) R version

Description

M_simulationR generates an area that has been potentially accessible to a species based on simulations of dispersal events determined by environmental suitability and user-defined parameters.

Usage

M_simulationR(data, current_variables, starting_proportion = 0.5,
              sampling_rule = "random", barriers = NULL, scale = TRUE,
              center = TRUE, project = FALSE, projection_variables = NULL,
              dispersal_kernel = "normal", kernel_spread = 1,
              max_dispersers = 4, suitability_threshold = 5,
              replicates = 10, dispersal_events = 25,
              access_threshold = 5, simulation_period = 50,
              stable_lgm = 7, transition_to_lgm = 100,
              lgm_to_current = 7, stable_current = 13,
              scenario_span = 1, out_format = "GTiff", set_seed = 1,
              write_all_scenarios = FALSE, output_directory,
              overwrite = FALSE)

Arguments

data	data.frame with occurrence records for the species of interest to be used to run the simulation; columns must be: species, longitude, latitude.
current_variables	SpatRaster of environmental variables representing "current" conditions (interglacial). Recommended projection WGS84 (EPSG:4326).
starting_proportion	(numeric) proportion of data located in suitable areas to be used as starting points for the simulation. Default = 0.5. All data is used if a value of 1 is defined.
sampling_rule	(character) rule to be used to sample a starting_proportion of points to run dispersal simulation steps. Options are: "random" and "suitability". Using the option "suitability" prioritizes records with higher suitability values. Default = "random".
barriers	SpatRaster representing dispersal barriers for the species. This layer must have the same extent and projection than current_variables. The only values allowed in this layer are 1 and NA; 1 = barrier. Default = NULL.
scale	(logical) whether or not to scale variables while performing principal component analyses.
center	(logical) whether or not to center variables while performing principal component analyses.
project	(logical) whether or not to project environmental suitability to past scenarios. The projection is done to the scenario defined by projection_variables and to any other scenario resulting from interpolations between current and past conditions. If TRUE, arguments projection_variables, simulation_period, stable_current, stable_lgm, transition_to_lgm, lgm_to_current, and scenario_span need to be defined. Default = FALSE.
projection_variables	SpatRaster of environmental variables representing the "Last Glacial Maximum" scenario. Variable names, projection, and extent of these layers must be the same than those in current_variables.
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 = 2.
max_dispersers	(numeric) maximum number of dispersers that depart from each colonized pixel. Depending on suitability this number will decrease in less suitable areas.
suitability_threshold	value (percentage) to be used as threshold for suitability; default = 5. Below this value environments are considered unsuitable.
replicates	(numeric) number of times to repeat the simulation per scenario. Default = 10.
dispersal_events	(numeric) number of dispersal events to happen per scenario. Default = 25.
access_threshold	(numeric) percentage of frequency values to be considered as highly unlikely to have been visited during process of dispersal. Default = 5.
simulation_period	(numeric) time in thousands of years for the complete period of simulation.
stable_lgm	(numeric) time in thousands of years for the period when glacial (LGM) conditions are assumed to be relatively stable.
transition_to_lgm	(numeric) time in thousands of years for the transition period from current-like (interglacial) to glacial (LGM) climatic conditions.
lgm_to_current	(numeric) time in thousands of years for the transition period from glacial (LGM) to current-like (interglacial) climatic conditions.
stable_current	(numeric) time in thousands of years for the period when current-like (interglacial) conditions are assumed to be relatively stable.
scenario_span	(numeric) time in thousands of years that have to pass for changing the scenario. Default = 1 (one thousand years).
out_format	(character) format of raster layers to be written in output_directory. Options are "ascii", "GTiff", and "EHdr" = bil. Default = "GTiff".
set_seed	(numeric) a seed to be used when sampling data according to starting_proportion. Default = 1.
write_all_scenarios	(logical) whether or not to write results for all scenarios. The default, FALSE, writes only the final results.
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

A principal component analysis is performed with current_variables. Then the three first principal components are used to calculate the suitability layer used in dispersal simulations. Values of suitability are derived from an ellipsoid envelope model created based on occurrence records and principal components. The ellipsoid model is used because it is a simple yet reliable representation of a species ecological niche that does not require a background or pseudo-absences.

If barriers are used, suitability values in the areas where barriers exist become zero. This is, populations cannot establish there and dispersal will be truncated unless dispersal abilities defined by arguments dispersal_kernel and kernel_spread, allow the species to overpass the barriers.

If project = TRUE, the simulation will run on a set of scenarios representing glacial-interglacial climate conditions. This set of scenarios are constructed based on interpolations between environmental conditions in current_variables and projection_variables. The later set of variables must represent Last Glacial Maximum conditions. Interpolations are linear and depend on the distance between the two initial set of conditions and other parameter defined in simulation_period, stable_current, stable_lgm, transition_to_lgm, lgm_to_current, and scenario_span.

Value

A list containing:

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

• all and ordered scenarios considered for the simulation

• a list with the parameters used during the simulation

• accessible areas as a SpatRaster (value 1 = accessed)

• accessible areas as a SpatVector object (only accessed areas)

• a SpatRaster representing mean values of accessibility frequency among replicates

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

• 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:

• a folder containing results from the PCA performed

• a folder containing results from the preparation of suitability layer(s)

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

• a plot representing the accessible areas and the occurrences

• a simple report from the simulation process

Examples

# data
data("records", package = "grinnell")
variables <- terra::rast(system.file("extdata/variables.tif",
                                     package = "grinnell"))
# example in current scenario
m <- M_simulationR(data = records, current_variables = variables,
                   max_dispersers = 2, replicates = 3, dispersal_events = 5,
                   output_directory = file.path(tempdir(), "eg_Msim1"))

# example under changing climatic conditions (starting from the past)

variables_lgm <- terra::rast(system.file("extdata/variables_lgm.tif",
                                         package = "grinnell"))

m_p <- M_simulationR(data = records, current_variables = variables,
                     project = TRUE, projection_variables = variables_lgm,
                     kernel_spread = 2, max_dispersers = 2,
                     replicates = 3, dispersal_events = 25,
                     simulation_period = 25, stable_lgm = 7,
                     transition_to_lgm = 3, lgm_to_current = 3,
                     stable_current = 7, scenario_span = 3,
                     output_directory = file.path(tempdir(), "eg_Msim1_p"))

# example under changing conditions, considering dispersal barriers
barrier <- terra::rast(system.file("extdata/barrier.tif",
                                   package = "grinnell"))

m_pb <- M_simulationR(data = records, current_variables = variables,
                      barriers = barrier, project = TRUE,
                      projection_variables = variables_lgm,
                      kernel_spread = 2, max_dispersers = 2,
                      replicates = 3, dispersal_events = 25,
                      simulation_period = 25, stable_lgm = 7,
                      transition_to_lgm = 3, lgm_to_current = 3,
                      stable_current = 7, scenario_span = 3,
                      output_directory = file.path(tempdir(), "eg_Msim1_pb"))

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