dispersalRate: Constrain Modelled Species Distributions by Dispersal Ability

In brshipley/megaSDM: Integrating Dispersal and Time-step Analyses into Species Distribution Models

Constrain Modelled Species Distributions by Dispersal Ability

Description

This function incorporates the ability of a species to disperse over time into projected habitat suitability models and presence/absence maps. The probability of dispersal per year as a function of distance is modelled using an exponential distribution, and summed together to create a probability of dispersal for the intervals between each provided time step. Dispersal-constrained binary (presence and absence) maps are generated, as well as continuous maps of "invadable suitability" (see https://onlinelibrary.wiley.com/doi/full/10.1111/ecog.05450).

Usage

dispersalRate(
  result_dir,
  dispersaldata,
  time_periods,
  scenarios,
  contiguous = FALSE,
  point_data = NA,
  hindcast = FALSE,
  startpoint = c(NA, NA),
  ncores = 1
)

Arguments

result_dir	the directory where the ensembled and binary maps are placed. Each species should have its own sub-directory, and the forecasted/hindcasted binary maps should be placed into directories like so: Species/Scenario/Time. If MaxEntProj was used to make these maps, this is probably the same as the output argument in that function.
dispersaldata	either a dataframe or the complete path name of a .csv file with two columns: Column 1: species name (same as the name used for modelling). Column 2: average dispersal rate of species in kilometers/year.
time_periods	a vector of the years in which the projection will occur. The first element should be the original year (the year in which the model was generated).
scenarios	a vector of character strings detailing the different climate models used in the forecasted/hindcasted species distribution models.
contiguous	TRUE/FALSE: when constraining by dispersal rate, should only the contiguous areas around each occurrence point be used for the first time step? setting this argument to TRUE will mitigate the effects of overprediction in areas where a species has not been observed. Default is FALSE.
point_data	If contiguous = TRUE, a file path to the directory holding all occurrence data used for the model generation. If previous steps of megaSDM have been run (e.g., MaxEntProj, MaxEntModel, OccurrenceManagement), this will likely be equal to occ_output in the vignette. If not, the occurrence data should have coordinates in "x" and "y" columns.
hindcast	TRUE/FALSE: is this a hindcasted model? If TRUE, dispersal rate calculations will start at the first time period, not the current one.
startpoint	if hindcast is TRUE then startpoint is a vector of length 2 describing a scenario/time combination, with the first argument as the scenario name and the second as the time period desired as a starting point for the dispersal simulations.
ncores	the number of computer cores to parallelize the background point generation on. Default is 1; Using one fewer core than the computer has is usually optimal.

Details

NOTE: dispersal rate analyses are only informative for predicting species distributions into the future (forecasting) rather than predicting past distributions (hindcasting), as range contractions and extirpations are not limited by dispersal rate.

NOTE: Running this function for data in a longlat projection will take somewhat longer than using data in equal area projections. Results are the same, however.

Value

returns rasters and .pdf files of the projected species ranges for future time periods, given different climate scenarios, when the ability of the species to disperse is taken into account. Dispersal-constrained presence/absence maps and "invadable suitability" maps are provided as outputs.

brshipley/megaSDM documentation built on Nov. 26, 2024, 6:08 a.m.