virtualNicheR (version 1.0)

fund.niche: Fundamental Niche

Description

Calculates the n-dimensional fundamental niche at m coordinates in niche space.

Usage

fund.niche(niche.coords, species)

Arguments

niche.coords

A m-by-n matrix of niche coordinates.

species

Ordered list of: maximum finite rate of increase, a means vector, and variance-covariance matrix that together define the fundamental niche of the species.

Value

Returns a vector of length m containing the fundamental niche value for each of the input niche space coordinates.

Details

Fundamental niche values are calculated on the basis of a multi-variate normal distribution, and hence are unimodal and convex in shape. The niche.coords can either be coordinates of specific interest, such as for mapping niche suitability for a study area, or for visualisation in niche space a grid of systematic coordinates as can be generated using niche.grid.coords. The species ordered list should contain:

• maximum finite rate of increase, the species' maximum finite rate of increase at the fundamental niche optimum,

• a n-by-1 column vector of means that gives the optimum location of the niche in each dimension, and

• a n-by-n variance-covariance matrix, that gives the size and orientation of the niche in each dimension.

References

Etherington TR, Omondiagbe OP (2019) virtualNicheR: generating virtual fundamental and realised niches for use in virtual ecology experiments. Journal of Open Source Software 4:1661 https://doi.org/10.21105/joss.01661

See Also

Used internally by real.niche

Examples

# NOT RUN {
# Create coordinates across niche space
niche.XY = niche.grid.coords(mins=c(15,0), maxs=c(35,200), nCoords=121)
# Define a species as a function of the maximum finite rate of increase,
# a means vector, and covariance matrix
lambdaMax = 2.5
meansVector = matrix(c(25, 100))
covarMatrix = matrix(data=c(9, 60,
                            60, 625), nrow=2, ncol=2, byrow = TRUE)
species = list(lambdaMax, meansVector, covarMatrix)
# Calculate the fundamental niche
fundNiche = fund.niche(niche.XY, species)
# Plot the fundamental niche
fundNicheMatrix = matrix(fundNiche, nrow=length(unique(niche.XY[,1])))
nContour = 10
filled.contour(unique(niche.XY[,1]), unique(niche.XY[,2]), fundNicheMatrix,
               levels = seq(0, lambdaMax, lambdaMax/nContour),
               col=colorRampPalette(c("gold", "firebrick"))(nContour),
               xlab=expression(paste("Temperature (", degree, "C)")),
               ylab="Rainfall (mm)",
               main ="Fundamental niche",
               key.title = title(main = expression(lambda)))

# Map the potential niche given maps of environmental variables
# Convert matrices of variables into columns
temp1D = matrix(temperatureMap, ncol=1)
rain1D = matrix(rainfallMap, ncol=1)
data.XY = cbind(temp1D, rain1D)
# Calculate the potential niche and form back in a 2D map
poteNiche = fund.niche(data.XY, species)
poteNiche2D = matrix(poteNiche, ncol=100)
filled.contour(z=poteNiche2D,
               levels = seq(0, lambdaMax, lambdaMax/nContour),
               col=colorRampPalette(c("gold", "firebrick"))(nContour),
               asp=1, plot.axes = {}, frame.plot=FALSE,
               main ="Map of the potential niche",
               key.title = title(main = expression(lambda)))
# }