convertToPA {virtualspecies} | R Documentation |
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
)
Arguments
x |
the output from functions
|
PA.method |
|
prob.method |
|
beta |
|
alpha |
|
a |
|
b |
|
species.prevalence |
|
plot |
|
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:
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 curveUsing 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 rangespecies.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 interceptb
of 0.)the coefficients of the linear regression: slope
a
and interceptb
. 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 requestedspecies.prevalence
(see below).
Method used to find coefficients of a linear regression which results in the
requested species.prevalence
:
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.
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.
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.
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 speciessuitab.raster
: the environmental suitability of your virtual species, as a Raster objectprobability.of.occurrence
: the probability of occurrence of your species, based on the chosen transformation of environmental suitability, as a Raster objectPA.conversion
: the parameters used to convert the suitability into presence-absencepa.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()
Note
The approximation of alpha
or beta
to the chosen
species.prevalence
may take time if you work on very large rasters.
Author(s)
Boris Leroy leroy.boris@gmail.com
with help from C. N. Meynard, D.M. Kaplan, C. Bellard & F. Courchamp
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)