generateRandomSp: Generate a random virtual species distribution from environmental variables

Description

This function generates randomly a virtual species distribution.

Usage

generateRandomSp(
  raster.stack,
  approach = "automatic",
  rescale = TRUE,
  convert.to.PA = TRUE,
  relations = c("gaussian", "linear", "logistic", "quadratic"),
  rescale.each.response = TRUE,
  realistic.sp = TRUE,
  species.type = "multiplicative",
  niche.breadth = "any",
  sample.points = FALSE,
  nb.points = 10000,
  PA.method = "probability",
  alpha = -0.1,
  adjust.alpha = TRUE,
  beta = "random",
  species.prevalence = NULL,
  plot = TRUE
)

Value

a list with 3 to 5 elements (depending if the conversion to presence-absence was performed):

approach: the approach used to generate the species, i.e., "response"
details: the details and parameters used to generate the species
suitab.raster: the virtual species distribution, as a SpatRaster object containing the environmental suitability)
PA.conversion: the parameters used to convert the suitability into presence-absence
pa.raster: the presence-absence map, as a SpatRaster object containing 0 (absence) / 1 (presence) / NA

The structure of the virtualspecies can object be seen using str()

Arguments

raster.stack: a SpatRaster object, in which each layer represent an environmental variable.
approach: "automatic", "random", "response" or "pca". This parameters defines how species will be generated. "automatic": If less than 6 variables in raster.stack, a response approach will be used, otherwise a pca approach will be used. "random": the approach will be randomly picked. Otherwise choose "response" or "pca". See details.
rescale: TRUE or FALSE. If TRUE, the final probability of presence is rescaled between 0 and 1.
convert.to.PA: TRUE or FALSE. If TRUE, the virtual species distribution will also be converted into Presence-Absence.
relations: [response approach] a vector containing the possible types of response function. The implemented type of relations are "gaussian", "linear", "logistic" and "quadratic".
rescale.each.response: TRUE or FALSE. If TRUE, the individual responses to each environmental variable are rescaled between 0 and 1
realistic.sp: [response approach] TRUE or FALSE. If TRUE, the function will try to define responses that can form a viable species. If FALSE, the responses will be randomly generated (may result in environmental conditions that do not co-exist).
species.type: [response approach] "additive" or "multiplicative". Defines how the final probability of presence is calculated: if "additive", responses to each variable are summed; if "multiplicative", responses are multiplied. See generateSpFromFun
niche.breadth: [pca approach] "any", "narrow" or "wide". This parameter defines how tolerant is the species regarding environmental conditions by adjusting the standard deviations of the gaussian functions. See generateSpFromPCA
sample.points: [pca approach] TRUE of FALSE. If you have a large raster file then use this parameter to sample a number of points equal to nb.points.
nb.points: [pca approach] a numeric value. Only useful if sample.points = TRUE. The number of sampled points from the raster, to perform the PCA. A too small value may not be representative of the environmental conditions in your raster.
PA.method: "threshold" or "probability". If "threshold", then occurrence probabilities are simply converted into presence-absence according to the threshold beta. If "probability", then probabilities are converted according to a logistic function of threshold beta and slope alpha.
alpha: NULL or a negative numeric value. Only useful if PA.method = "probability". The value of alpha will shape the logistic function transforming occurrences into presence-absences. See logisticFun and examples therein for the choice of alpha
adjust.alpha: TRUE or FALSE. Only useful if rescale = FALSE. If adjust.alpha = TRUE, then the value of alpha will be adjusted to an appropriate value for the range of suitabilities.
beta: "random", a numeric value in the range of your probabilities or NULL. This is the threshold of conversion into presence-absence (= the inflexion point if PA.method = "probability"). If "random", a numeric value will be randomly generated within the range of probabilities of occurrence. See convertToPA
species.prevalence: NULL or a numeric value between 0 and 1. The species prevalence is the proportion of sites actually occupied by the species. See convertToPA
plot: TRUE or FALSE. If TRUE, the generated virtual species will be plotted.

Author

Boris Leroy leroy.boris@gmail.com

with help from C. N. Meynard, C. Bellard & F. Courchamp

Details

Online tutorial for this function

This function generate random virtual species, either using a PCA approach, or using a response approach. In case of a response approach, only four response functions are currently used: gaussian, linear, logistic and quadratic functions.

Note that in case of numerous predictor variables, the "response" approach will not work well because it will often generate contradicting response functions (e.g., mean annual temperature optimum at degrees C and temperature of the coldest month at 10 degrees C). In these case, it is advised to use the PCA approach (by default, a PCA approach will be used if there are more than 6 predictor variables).

If rescale.each.response = TRUE, then the probability response to each variable will be normalised between 0 and 1 according to the following formula: P.rescaled = (P - min(P)) / (max(P) - min (P)). Similarly, if rescale = TRUE, the final environmental suitability will be rescaled between 0 and 1 with the same formula.

By default, the function will perform a probabilistic conversion into presence- absence, with a randomly chosen beta threshold. If you want to customise the conversion parameters, you have to define two of the three following parameters:

beta: the 'threshold' of the logistic function (i.e. the inflexion point)
alpha: the slope of the logistic function
species.prevalence: the proportion of sites in which the species occur

If you provide beta and alpha, the species.prevalence is calculated immediately calculated after conversion into presence-absence.

As explained in convertToPA, if you choose choose a precise species.prevalence, it may not be possible to reach this particular value because of the availability of environmental conditions. Several runs may be necessary to reach the desired species.prevalence.

Examples

Run this code

# Create an example stack with six environmental variables
a <- matrix(rep(dnorm(1:100, 50, sd = 25)), 
            nrow = 100, ncol = 100, byrow = TRUE)
env <- c(rast(a * dnorm(1:100, 50, sd = 25)),
         rast(a * 1:100),
         rast(a * logisticFun(1:100, alpha = 10, beta = 70)),
         rast(t(a)),
         rast(exp(a)),
         rast(log(a)))
names(env) <- paste("Var", 1:6, sep = "")   

# More than 6 variables: by default a PCA approach will be used
generateRandomSp(env)

# Manually choosing a response approach: this may fail because it is hard
# to find a realistic species with six distinct responses to six variables
# \donttest{
generateRandomSp(env, approach = "response")
# }

# Randomly choosing the approach
generateRandomSp(env, approach = "random")

Run the code above in your browser using DataLab