Select (version 1.4)

selectSpecies: Select species based on traits

Description

This function returns a probability distribution for a species pool based on their traits and a desired trait profile (Laughlin 2014). It can simultaneously constrain specific trait value(s) and optimise functional diversity.

Usage

selectSpecies(t2c = NULL, constraints = NULL, t2d, obj = c("QH", "Q",
  "H"), phi = 0.5, capd = FALSE, euclid = TRUE)

Arguments

t2c

"Traits to constrain": A matrix of species trait values, where species are organized as rows and traits as columns. These should be numeric arrays, and no missing values are tolerated. Ordinal data will yield meaningful results, but nominal data entered as numeric vectors are invalid. Row and column names are optional. This matrix can be any dimension, but the number of traits should be less than the number of species.

constraints

Trait constraints: A vector of trait values that serve as constants in the constraint equations. If not specified, the function will not constrain solutions to trait means. These trait contraints must be listed in the same order as columns in t2c. These constraints are community-weighted mean trait values, i.e., average traits weighted by the relative abundance of each species.

t2d

"Traits to diversify": Can be 1) a matrix of species trait values to diversify where species are organized as rows and traits as columns. NAs are tolerated as long as each pair of species can be compared by at least one trait. In this case, dissimilarities among species are computed using Euclidean distance. The number of species in t2d must match those in t2c. Or 2) a distance matrix of class 'dist' that contains dissimilarities among species, no NAs are tolerated in the distance matrix.

obj

Objective function: The objective function to optimise, one of three possibilities = c("QH", "Q", "H"). QH = Quadratic entropy (Q) plus entropy (H'); Q = Quadratic entropy; H = entropy.

phi

A parameter bounded between 0 and 1 that weights the importance of either quadratic entropy or entropy (default = 0.5). Phi of 1 corresponds to 100 percent Q, phi of 0.5 corresponds to 50 percent Q and 50 perfect H', phi of 0 corresponds to 100 percent H'.

capd

A logical stating whether the distance matrix should be capped at the mean distance among species (default = FALSE). Mean distance is calculated as the average of all upper triangular entries in the distance matrix calculated from t2d.

euclid

A logical stating whether the distance matrix should be transformed to an Euclidean matrix if necessary (default = TRUE).

Value

A list with the elements:

prob

Probabilities, i.e. optimal solutions of species relative abundance

cwm_t2d

Community-weighted mean trait values of resulting community for traits that were diversified, computed as probabilities x t2d using matrix multiplication

cwm_t2c

Community-weighted mean trait values of resulting community for traits that were constrained, computed as probabilities x t2d using matrix multiplication

H

Final entropy of community

Q

Final Rao Q of community

objval

Values of the objective function being maximized. The last value is the maximum.

lagrange

Lagrange multipliers.

hessian

The Hessian at the optimal solution.

References

Laughlin, D.C. 2014. Applying trait-based models to achieve functional targets for theory-driven ecological restoration. Ecology Letters, 17, 771-784.

Examples

# NOT RUN {
### 1 trait constraint with maximum entropy
Spp <- 5 #S = number of species
trait <- as.matrix(data.frame(trait=c(1:Spp)))
rownames(trait) <- c(letters[1:nrow(trait)])
result1 <- selectSpecies(t2c=trait, constraints=c(trait=3.5), t2d=trait, obj="H", capd=FALSE)
### compare result1 with virtually identical maxent output from FD package
#FD::maxent(constr=c(3.5),states=trait)$prob
### 1 trait constraint with maximum functional diversity
result2 <- selectSpecies(t2c=trait, constraints=c(trait=3.5), t2d=trait, obj="Q", capd=FALSE)
### 1 trait constraint with maximum functional diversity and entropy
result3 <- selectSpecies(t2c=trait, constraints=c(trait=3.5), t2d=trait, obj="QH", capd=FALSE)

### Plot results
plotProbs(result1,trait, xlab="Trait")
plotProbs(result2,trait, xlab="Trait")
plotProbs(result3,trait, xlab="Trait")

### 1 trait and no trait constraint
result4 <- selectSpecies(t2d=trait, obj="QH", capd=FALSE)
plotProbs(result4,trait, xlab="Trait")

##### 2 traits: Constrain trait X at X=3, diversify trait Y
traitX <- matrix(c(rep(1,4),rep(2,4),rep(3,4),rep(4,4)))
traitY <- matrix(c(rep(c(1,2,3,4),4)))
rownames(traitX) <- c(letters[1:16]); colnames(traitX) <- c("traitX")
rownames(traitY) <- c(letters[1:16]); colnames(traitY) <- c("traitY")

result5 <- selectSpecies(t2c=traitX,constraints=c(traitX=3),t2d=traitY,obj="Q",capd=FALSE)
result6 <- selectSpecies(t2c=traitX,constraints=c(traitX=3),t2d=traitY,obj="QH",capd=TRUE)

trait.matrix <- cbind(traitX, traitY)
plotProbs(result5,trait.matrix)
plotProbs(result6,trait.matrix)

##### 3 traits: Constrain trait Z to value 2.5, diversify trait X and Y
traitZ <- as.matrix(data.frame(c(1,3,2,2,3,1,2,3,1,2,1,3,2,3,2,2)))
rownames(traitZ) <- c(letters[1:16]); colnames(traitZ) <- c("traitZ")
result7 <- selectSpecies(t2c=traitZ,constraints=c(traitZ=2.5),t2d=trait.matrix, capd=TRUE, obj="QH")
plotProbs(result7,trait.matrix)

# }