Sample occurrences in a virtual species distribution

Share:

Description

This function samples presences within a species distribution, either randomly or with a sampling bias. The sampling bias can be defined manually or with a set of pre-defined biases.

Usage

1
2
3
4
5
sampleOccurrences(x, n, type = "presence only", sampling.area = NULL,
  detection.probability = 1, correct.by.suitability = FALSE,
  error.probability = 0, bias = "no.bias", bias.strength = 50,
  bias.area = NULL, weights = NULL, sample.prevalence = NULL,
  plot = TRUE)

Arguments

x

a rasterLayer object or the output list from generateSpFromFun, generateSpFromPCA, generateRandomSp, convertToPA or limitDistribution The raster must contain values of 0 or 1 (or NA).

n

an integer. The number of occurrence points to sample.

type

"presence only" or "presence-absence". The type of occurrence points to sample.

sampling.area

a character string, a polygon or an extent object. The area in which the sampling will take place. See details.

detection.probability

a numeric value between 0 and 1, corresponding to the probability of detection of the species. See details.

correct.by.suitability

TRUE or FALSE. If TRUE, then the probability of detection will be weighted by the suitability, such that cells with lower suitabilities will further decrease the chance that the species is detected when sampled.

error.probability

TRUE or FALSE. Only useful if type = "presence-absence". Probability to attribute an erroneous presence in cells where the species is absent.

bias

"no.bias", "country", "region", "extent", "polygon" or "manual". The method used to generate a sampling bias: see details.

bias.strength

a positive numeric value. The strength of the bias to be applied in area (as a multiplier). Above 1, area will be oversampled. Below 1, area will be undersampled.

bias.area

NULL, a character string, a polygon or an extent object. The area in which the sampling will be biased: see details. If NULL and bias = "extent", then you will be asked to draw an extent on the map.

weights

NULL or a raster layer. Only used if bias = "manual". The raster of bias weights to be applied to the sampling of occurrences. Higher weights mean a higher probability of sampling.

sample.prevalence

NULL or a numeric value between 0 and 1. Only useful if type = "presence-absence". Defines the sample prevalence, i.e. the proportion of presences sampled. Note that the probabilities of detection and error are applied AFTER this parameter, so the final sample prevalence may not different if you apply probabilities of detection and/or error

plot

TRUE or FALSE. If TRUE, the sampled occurrence points will be plotted.

Details

How the function works:

The function randomly selects n cells in which samples occur. If a bias is chosen, then the selection of these cells will be biased according to the type and strength of bias chosen. If the sampling is of type "presence only", then only cells where the species is present will be chosen. If the sampling is of type "presence-absence", then all non-NA cells can be chosen.

The function then samples the species inside the chosen cells. In cells where the species is present the species will always be sampled unless the parameter detection.probability is lower than 1. In that case the species will be sampled with the associated probability of detection.

In cells where the species is absent (in case of a "presence-absence" sampling), the function will always assign absence unless error.probability is greater than 1. In that case, the species can be found present with the associated probability of error. Note that this step happens AFTER the detection step. Hence, in cells where the species is present but not detected, it can still be sampled due to a sampling error.

How to restrict the sampling area:

Use the argument sampling.area:

  • Provide the name (s) (or a combination of names) of country(ies), region(s) or continent(s). Examples:

    • sampling.area = "Africa"

    • sampling.area = c("Africa", "North America", "France")

  • Provide a polygon (SpatialPolygons or SpatialPolygonsDataFrame of package sp)

  • Provide an extent object

How the sampling bias works:

The argument bias.strength indicates the strength of the bias. For example, a value of 50 will result in 50 times more samples within the bias.area than outside. Conversely, a value of 0.5 will result in half less samples within the bias.area than outside.

How to choose where the sampling is biased:

You can choose to bias the sampling in:

  1. a particular country, region or continent (assuming your raster has the WGS84 projection):

    Set the argument bias to "country", "region" or "continent", and provide the name(s) of the associated countries, regions or continents to bias.area (see examples).

    List of possible bias.area names:

    • Countries: type levels(getMap()@data$SOVEREIGNT) in the console

    • Regions: "Africa", "Antarctica", "Asia", "Australia", "Europe", "North America", "South America"

    • Continents: "Africa", "Antarctica", "Australia", "Eurasia", "North America", "South America"

  2. a polygon:

    Set bias to "polygon", and provide your polygon to area.

  3. an extent object:

    Set bias to "extent", and either provide your extent object to bias.area, or leave it NULL to draw an extent on the map.

Otherwise you can define manually your sampling bias, e.g. to create biases along roads. In that case you have to provide to weights a raster layer in which each cell contains the probability to be sampled.

Value

a list with 3 (unbiased sampling) to 4 (biased sampling) elements:

  • sample.points: the data.frame containing the coordinates of samples, the real presence-absences (or presence-only) and the sampled presence- absences

  • detection.probability: the chosen probability of detection of the virtual species

  • error.probability: the chosen probability to assign presence in cells where the species is absent

  • bias: if a bias was chosen, then the type of bias and the associated area will be included.

Author(s)

Boris Leroy leroy.boris@gmail.com

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# Create an example stack with six environmental variables
a <- matrix(rep(dnorm(1:100, 50, sd = 25)),
            nrow = 100, ncol = 100, byrow = TRUE)
env <- stack(raster(a * dnorm(1:100, 50, sd = 25)),
             raster(a * 1:100),
             raster(a * logisticFun(1:100, alpha = 10, beta = 70)),
             raster(t(a)),
             raster(exp(a)),
             raster(log(a)))
names(env) <- paste("Var", 1:6, sep = "")

# More than 6 variables: by default a PCA approach will be used
sp <- generateRandomSp(env, niche.breadth = "wide")

# Sampling of 25 presences
sampleOccurrences(sp, n = 25)

# Sampling of 30 presences and absebces
sampleOccurrences(sp, n = 30, type = "presence-absence")

# Reducing of the probability of detection
sampleOccurrences(sp, n = 30, type = "presence-absence",
                  detection.probability = 0.5)

# Further reducing in relation to environmental suitability
sampleOccurrences(sp, n = 30, type = "presence-absence",
                  detection.probability = 0.5,
                  correct.by.suitability = TRUE)

# Creating sampling errors (far too much)
sampleOccurrences(sp, n = 30, type = "presence-absence",
                  error.probability = 0.5)

# Introducing a sampling bias (oversampling)
biased.area <- extent(0.5, 0.7, 0.6, 0.8)
sampleOccurrences(sp, n = 50, type = "presence-absence",
                  bias = "extent",
                  bias.area = biased.area)
# Showing the area in which the sampling is biased
plot(biased.area, add = TRUE)

# Introducing a sampling bias (no sampling at all in the chosen area)
biased.area <- extent(0.5, 0.7, 0.6, 0.8)
sampleOccurrences(sp, n = 50, type = "presence-absence",
                  bias = "extent",
                  bias.strength = 0,
                  bias.area = biased.area)
# Showing the area in which the sampling is biased
plot(biased.area, add = TRUE)