virtualspecies (version 1.6)

convertToPA: Convert a virtual species distribution (or a suitability raster) into presence-absence

Description

This functions converts the probabilities of presence from the output of generateSpFromFun, generateSpFromPCA, generateRandomSp or a suitability raster into a presence-absence raster. The conversion can be threshold-based, or based on a probability of conversion (see details).

Usage

convertToPA(
  x,
  PA.method = "probability",
  prob.method = "logistic",
  beta = "random",
  alpha = -0.05,
  a = NULL,
  b = NULL,
  species.prevalence = NULL,
  plot = TRUE
)

Value

a list containing 6 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 environmental suitability of your virtual species, as a Raster object

• probability.of.occurrence: the probability of occurrence of your species, based on the chosen transformation of environmental suitability, as a Raster object

• PA.conversion: the parameters used to convert the suitability into presence-absence

• pa.raster: the presence-absence map, as a Raster object containing 0 (absence) / 1 (presence) / NA

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

Arguments

x

the output from functions generateSpFromFun, generateSpFromPCA or generateRandomSp, or a suitability SpatRaster

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.

prob.method

"logistic" or "linear". Defines how the initial environmental suitability is translated into probabilities of presence/absence.

beta

"random", a numeric value in the range of your probabilities or NULL. This is the threshold of conversion into presence-absence (if PA.method = "probability" and prob.method = "logistic", then beta = the inflexion point). If "random", a numeric value will be randomly generated within the range of x.

alpha

NULL or a negative numeric value. Only useful if PA.method = "probability" and proba.method = "logistic". The value of alpha will shape the logistic function transforming occurrences into presence-absences. See logisticFun and examples therein for the choice of alpha

a

NULL or a numeric value. Only useful if PA.method = "probability" and proba.method = "linear". Slope of the linear conversion of environmental suitability.

b

NULL or a numeric value. Only useful if PA.method = "probability" and proba.method = "linear". Intercept of the linear conversion of environmental suitability.

species.prevalence

NULL or a numeric value between 0 and 1. The species prevalence is the proportion of sites actually occupied by the species.

plot

TRUE or FALSE. If TRUE, maps of probabilities of occurrence and presence-absence will be plotted.

Author

Boris Leroy

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

Details

Online tutorial for this function

The conversion of environmental suitability into presence - absence used to be performed by selecting a threshold above which presence always occurs, and never below. However, this approach may is unrealistic because species may sometime be present in areas with a low probability of occurrence, or be absent from areas with a high probability of occurrence. In addition, when using a threshold you erase the previously generated response shapes: it all becomes threshold. Thus, this threshold approach should be avoided.

A more realistic conversion consists in converting environmental suitability into presence - absence with a probability function (see references). Such a probability conversion can be performed with two different methods here:

1. Using a logistic transformation of environmental suitability (see logisticFun). A logistic function on the other hand, will ensure that the simulated probability is within the 0-1 range and allow easy control of species prevalence. However, the logistic function will also flatten out the relationship at the extreme suitability values, and narrow or broaden the intermediate probability values depending on the slope of the logistic curve

2. Using a linear transformation of environmental suitability. A linear transformation will preserve the shape of the originally simulated occurrence-environment relationships, uniformly increasing or decreasing the probabilities of occurrence across the landscape.

--- note ---

If the Virtual Species study aims at comparing simulated and predicted probability values, it is important to recover the correct simulated probability instead of directly using the initial suitability function.

Therefore, the function stores the probability of occurrence in the output list, under the object probability.of.occurrence. The initial suitability function (before logistic or linear conversion) will still be stored in the output list as suitab.raster.

--------------------------------------------------------------------------

PROBABILISTIC CONVERSION - LOGISTIC METHOD

To perform the logistic transformation of environmental suitability you have to define two of the three following parameters:

• beta: the 'threshold' of the logistic function (i.e. the inflexion point. It should normaly be in the range of values of your environmental suitability.)

• alpha: the slope of the logistic function. It should generally be in value equal to something like 1/20 or 1/10 of your environmental suitability range

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

On the other hand, if you provide species.prevalence and either beta or alpha, the function will try to determine alpha (if you provided beta) or beta (if you provided alpha).

The relationship between species prevalence, alpha and beta is dependent on the available range of environmental conditions (see Meynard and Kaplan, 2011 and especially the Supporting Information). As a consequence, the desired species prevalence may not be available for the defined alpha or beta. In these conditions, the function will retain the alpha or beta which provides the closest prevalence to your species.prevalence, but you may also provide another value of alpha or beta to obtain a closer prevalence.

--------------------------------------------------------------------------

PROBABILISTIC CONVERSION - LINEAR METHOD

To perform the linear transformation of environmental suitability you have to define *one* of the following:

• nothing - in which case your input environmental suitability will be used as the probability of occurrence for the Bernoulli trial (it is equivalent to defining a slope a of 1 and intercept b of 0.)

• the coefficients of the linear regression: slope a and intercept b. The transformed environmental suitability will be used as the probability of occurrence for the Bernoulli trial.

• species.prevalence: the proportion of sites in which the species occur. In this case, the function will try to find coefficients of a linear regression which results in the requested species.prevalence (see below).

Method used to find coefficients of a linear regression which results in the requested species.prevalence:

1. The simplest linear transformation of habitat suitability would be to just multiply the raw suitability by a constant. For example, if the raw average suitability in the area is 0.04, it means an expected prevalence of 0.40. To to go from this expected prevalence of 0.04 to an expected prevalence of 0.4, we can just multiply the raw suitability by 10. It is the default choice, unless it results in probabilities superior to 1 or raw suitability have values below 0, in which case the function proceeds to method 2.

2. If it does not work, then we look at the line that passes through (min suitability, 0) and (mean suitability, desired prevalence). For this line, we only need to ensure that the maximum probability of occurence is lower than 1. Otherwise, the function proceeds to method 3.

3. If method 2 fails, then we test the line going through (mean suitability, desired prevalence) and (max suitability, 1). If the minimum probability resulting from this line is greater than 0, then this method is correct.

One of these 3 lines should always work. In fact, one of the last two has to work, and it does not hurt to try the first one which is simpler.

--------------------------------------------------------------------------

In all cases, the species.prevalence indicated in the output is the prevalence measured on the output presence-absence map.

References

Meynard C.N. & Kaplan D.M. 2013. Using virtual species to study species distributions and model performance. Journal of Biogeography 40:1-8

Meynard C.N. & Kaplan D.M. 2011. The effect of a gradual response to the environment on species distribution model performance. Ecography 35:499-509

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")

# Creation of the parameter list
parameters <- formatFunctions(variable1 = c(fun = 'dnorm', mean = 0.00012,
                                            sd = 0.0001),
                              variable2 = c(fun = 'linearFun', a = 1, b = 0))
sp1 <- generateSpFromFun(env, parameters, plot = FALSE)

# Conversion into presence-absence with a threshold-based approach
convertToPA(sp1, PA.method = "threshold", beta = 0.2,  plot = TRUE)
convertToPA(sp1, PA.method = "threshold", beta = "random", plot = TRUE)

# Conversion into presence-absence with a probability approach using logistic
# method
convertToPA(sp1, PA.method = "probability", beta = 0.4, 
              alpha = -0.05, plot = TRUE)
convertToPA(sp1, PA.method = "probability", beta = "random", 
              alpha = -0.1, plot = TRUE)
              
# Conversion into presence-absence with a probability approach using linear 
# method
convertToPA(sp1, PA.method = "probability", prob.method = "linear",
            a = 1, b = 0, plot = TRUE)         
              
              
# Conversion into presence-absence by choosing the prevalence
# Threshold method
convertToPA(sp1, PA.method = "threshold",
              species.prevalence = 0.3, plot = TRUE)
# Logistic method, with alpha provided              
convertToPA(sp1, PA.method = "probability", alpha = -0.1, 
              species.prevalence = 0.2, plot = TRUE)        
# Logistic method, with beta provided              
convertToPA(sp1, PA.method = "probability", beta = 0.5, 
              species.prevalence = 0.2, alpha = NULL, 
              plot = TRUE)    
# Linear method
convertToPA(sp1, PA.method = "probability", prob.method = "linear",
            species.prevalence = 0.2,
            plot = TRUE)              
convertToPA(sp1, PA.method = "probability", prob.method = "linear",
            species.prevalence = 0.5,
            plot = TRUE) 
convertToPA(sp1, PA.method = "probability", prob.method = "linear",
            species.prevalence = 0.8,
            plot = TRUE)                
 
# Plot the output Presence-Absence raster only             
sp1 <- convertToPA(sp1, plot = FALSE)
plot(sp1$pa.raster)