limitDistribution {virtualspecies}

Limit a virtual species distribution to a defined area

Description

This function is designed to limit species distributions to a subsample of their total distribution range. It will thus generate a species which is not at the equilibrium with its environment (i.e., which did not occupy the full range of suitable environmental conditions).

This function basically takes any type of raster and will limit values above 0 to areas where the species is allowed to disperse.

Usage

limitDistribution(x, geographical.limit = "extent", area = NULL, plot = TRUE)

Arguments

x

a SpatRaster object composed of 0, 1 and NA, or the output list from generateSpFromFun, generateSpFromPCA or generateRandomSp

geographical.limit

"country", "region", "continent", "polygon", "raster" or "extent". The method used to limit the distribution range: see details.

area

NULL, a character string, a polygon, a raster or an extent object. The area in which the distribution range will be limited: see details. If NULL and geographical.limit = "extent", then you will be asked to draw an extent on the map.

plot

TRUE or FALSE. If TRUE, the resulting limited distribution will be plotted.

Details

Online tutorial for this function

How the function works:

The function will remove occurrences of the species outside the chosen area:

• NA are kept unchanged

• 0 are kept unchanged

• values > 0 within the limits of area are kept unchanged

• values > 0 outside the limits of area are set to 0

How to define the area in which the range is limited:

You can choose to limit the distribution range of the species to:

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

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

   List of possible area names:

   • Countries: type unique(rnaturalearth::ne_countries(returnclass ='sf')$sovereignt) in the console

   • Regions: "Africa", "Antarctica", "Asia", "Oceania", "Europe", "Americas"

   • Continents: "Africa", "Antarctica", "Asia", "Europe", "North America", "Oceania", "South America"

2. a polygon:

   Set geographical.limit to "polygon", and provide your polygon to area.

3. a raster:

   Set geographical.limit to "raster", and provide your raster to area. Your raster values should be 1 (suitable area), 0 (unsuitable area) or NA (outside your mask).

4. an extent object:

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

Value

a list containing 7 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 virtual species distribution, as a Raster 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 Raster object containing 0 (absence) / 1 (presence) / NA

• geographical.limit: the method used to limit the distribution and the area in which the distribution is restricted

• occupied.area: the area occupied by the virtual species as a Raster of presence-absence

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

Examples

# 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
sp <- generateRandomSp(env)

# limiting the distribution to a specific extent
limit <- ext(1, 50, 1, 50)

limitDistribution(sp, area = limit)


# Example of a raster of habitat patches
habitat.raster <- setValues(sp$pa.raster, 
                            sample(c(0, 1), size = ncell(sp$pa.raster), 
                            replace = TRUE))

plot(habitat.raster) # 1 = suitable habitat; 0 = unsuitable habitat
sp <- limitDistribution(sp, geographical.limit = "raster", area = habitat.raster)
par(mfrow = c(2, 1))
plot(sp$pa.raster)
plot(sp$occupied.area) # Species could not occur in many cells because
# habitat patches were unsuitable