generateSpFromFun {virtualspecies}

Generate a virtual species distributions with responses to environmental variables

Description

This function generates a virtual species distribution from a stack of environmental variables and a defined set of responses to each environmental parameter.

Usage

generateSpFromFun(
  raster.stack,
  parameters,
  rescale = TRUE,
  formula = NULL,
  species.type = "multiplicative",
  rescale.each.response = TRUE,
  plot = FALSE
)

Arguments

raster.stack

a SpatRaster object, in which each layer represent an environmental variable.

parameters

a list containing the functions of response of the species to environmental variables with their parameters. See details.

rescale

TRUE or FALSE. If TRUE, the final probability of presence is rescaled between 0 and 1.

formula

a character string or NULL. The formula used to combine partial responses into the final environmental suitability value (e.g., "layername1 + 2 * layername2 + layername3 * layername4 etc."). If NULL then partial responses will be added or multiplied according to species.type

species.type

"additive" or "multiplicative". Only used if formula = NULL. Defines how the final environmental suitability is calculated: if "additive", responses to each variable are summed; if "multiplicative", responses are multiplied.

rescale.each.response

TRUE or FALSE. If TRUE, the individual responses to each environmental variable are rescaled between 0 and 1 (see details).

plot

TRUE or FALSE. If TRUE, the generated virtual species will be plotted.

Details

Online tutorial for this function

This function proceeds in two steps:

1. The response to each environmental variable is calculated with the functions provided in parameters. This results in a suitability of each variable.

   By default, each response is rescaled between 0 and 1. Disable with rescale.each.response = FALSE

2. The final environmental suitability is calculated according to the chosen species.type.

   By default, the final suitability is rescaled between 0 and 1. Disable with rescale = FALSE

The SpatRaster stack containing environmental variables must have consistent names, because they will be checked with the parameters. For example, they can be named var1, var2, etc. Names can be checked and set with names(my.stack).

The parameters have to be carefully created, otherwise the function will not work:

• Either see formatFunctions to easily create your list of parameters

• Or create a list defined according to the following template:
  list( var1 = list(fun = 'fun1', args = list(arg1 = ..., arg2 = ..., etc.)), var2 = list(fun = 'fun2', args = list(arg1 = ..., arg2 = ..., etc.)))
  It is important to keep the same names in the parameters as in the stack of environmental variables. Similarly, argument names must be identical to argument names in the associated function (e.g., if you use fun = 'dnorm', then args should look like list(mean = 0, sd = 1)).

  See the example section below for more examples.

Any response function that can be applied to the environmental variables can be chosen here. Several functions are proposed in this package: linearFun, logisticFun and quadraticFun. Another classical example is the normal distribution: stats::dnorm(). Users can also create and use their own functions very easily.

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)) This rescaling has a strong impact on response functions, so users may prefer to use rescale.each.response = FALSE and apply their own rescaling within their response functions.

Value

a list with 3 elements:

• approach: the approach used to generate the species, i.e., "response"

• details: the details and parameters used to generate the species

• suitab.raster: the raster containing the environmental suitability of the virtual species

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

Author(s)

Boris Leroy [e-mail]

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

See Also

generateSpFromPCA to generate a virtual species with a PCA approach

Examples

# Create an example stack with two 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))
names(env) <- c("variable1", "variable2")
plot(env) # Illustration of the variables

# Easy creation of the parameter list:
# see in real time the shape of the response functions
parameters <- formatFunctions(variable1 = c(fun = 'dnorm', mean = 1e-04, 
                                             sd = 1e-04),
                              variable2 = c(fun = 'linearFun', a = 1, b = 0))
                              
# If you provide env, then you can see the shape of response functions:
parameters <- formatFunctions(x = env,
                              variable1 = c(fun = 'dnorm', mean = 1e-04, 
                                             sd = 1e-04),
                              variable2 = c(fun = 'linearFun', a = 1, b = 0))

# Generation of the virtual species
sp1 <- generateSpFromFun(env, parameters)
sp1
par(mfrow = c(1, 1))
plot(sp1)


# Manual creation of the parameter list
# Note that the variable names are the same as above
parameters <- list(variable1 = list(fun = 'dnorm',
                                    args = list(mean = 0.00012,
                                                sd = 0.0001)),
                   variable2 = list(fun = 'linearFun',
                                    args = list(a = 1, b = 0)))
# Generation of the virtual species
sp1 <- generateSpFromFun(env, parameters, plot = TRUE)
sp1
plot(sp1)