decdiv {adiv}

Decomposition of trait-based diversity along the nodes of a phylogenetic tree

Description

The function decdiv calculates trait-based differences between the lineages that descend from a node of a phylogenetic tree in one or several communities (using presence/absence or abundance data).

The function plot.decdiv plots the result of function decdiv for one of the communities.

The function rtestdecdiv tests, for one community (with presence/absence or abundance data), if the representation of trait diversity on the phylogenetic tree highlights a nonrandom pattern.

Usage

decdiv(phyl, comm, dis = NULL, tol = 1e-08, option = 1:5, 
     formula = c("QE", "EDI"))

## S3 method for class 'decdiv'
plot(x, ncom = 1, col = "black", 
    csize = 1, legend = TRUE, ...)

rtestdecdiv(phyl, vecab, dis = NULL, tol = 1e-08, 
    option = 1:5, formula = c("QE", "EDI"), 
    vranking = c("complexity", "droot"), 
    ties.method = c("average", "first", "last", "random", 
    "max", "min"), statistic = 1:3, optiontest = NULL, nrep = 99)

Arguments

phyl

an object inheriting the class phylo (see package ape), phylo4 (see package phylobase) or hclust with species as tips. To ease the interpretation of the results, I advise you to add labels to the nodes of the phylogeny. For example, If your phylogeny is named 'tree' and is of class phylo, you can name the nodes with the following command: tree$node.label <- paste("n", 1:tree$Nnode, sep=""). Use plot(tree, show.node.label=TRUE) to see the result. If it is of class phylo4, you can use: nodeLabels(tree) <- paste("n", 1:nNodes(tree), sep="").

comm

a vector with species presence/absence or an index of abundance as entries, or a data frame or a matrix typically with communities as rows, species as columns and presence/absence or an index of abundance as entries. Species names in comm must be similar as in phyl. Even if comm is a vector, each entry needs to have a species name (use function name to attribute names to a vector).

dis

either NULL or an object of class dist that contains the trait-based distances among species. If NULL, the Gini-Simpson index is used.

tol

a tolerance threshold (a value between -tol and tol is considered equal to zero)

option

a numeric (either 1, 2, 3, 4 or 5) indicating the option to use to calculate the contribution of each node of the phylogenetic tree to trait-based diversity. See details. If several values are given, the function retains only the first one.

formula

either "QE" (default) or "EDI". See details. If several values are given, the function retains only the first one.

x

an object of class decdiv.

ncom

if comm is a matrix, the number of its row corresponding to the focal community for which the results of decdiv will be plotted. Igored if comm is a vector.

col

the color of circles displayed at each node.

csize

a positive numeric giving the scale for plotting the circle at each node. 1 is the default size; if zero, no circle is drawn.

legend

a logical indicating whether the legend for the circle size needs to be displayed.

...

further arguments that can be specified to the internal use of function plot.phylo (argument y.lim cannot be modified).

vecab

a numeric vector giving the presence/absence(1/0) or abundance(non-negative value) of species in a community.

vranking

a string with 2 possible values: either "complexity" for a ranking according to the complexity of the subtree rooted on each interior node (see Pavoine et al. 2010 for an explanation), or "droot" for ordering interior nodes by the distance between them and the root node of the tree.

ties.method

a string to be passed to function rank of the base of R. It can be one of "average", "first", "last", "random", "max", "min".

statistic

a numeric value or a vector of numeric values. Possible values are 1, 2, or 3. They correspond to the three statistics S1, S2 and S3, respectively, developed by Pavoine et al. (eqs. 5 to 7 in Pavoine et al. 2010).

optiontest

a vector of strings specifying the alternative hypothesis of each test, which must be one of "greater", "less" or "two-sided". If null, then statistic=1 is associated with "greater" and statistic=2 and =3 with "two-sided". See function as.randtest of package ade4 for details on these alternatives. The length of the vector given to optiontest must be equal to that given to statistic.

nrep

numeric; the number of permutations to be done in each permutation test.

Details

The function decdiv relies on Rao's (1982) quadratic entropy (QE) to measure the trait-based diversity of a set of species. Two formulas for QE have been introduced in the literature one is the original formula by Rao (1982) (which corresponds to formula = "QE") and the other one introduced by Champely and Chessel (2002), named Euclidean Diversity Index (which corresponds to formula = "EDI"). See function QE for more details.

In function decdiv, each node has a weight proportional to the summed relative abundance of its descending species (or to the relative number of descending species if presence/absence data are used).

With option = 1, the function decdiv apportions trait-based diversity across the nodes of a phylogenetic tree using the algorithm defined in Pavoine et al. (2010). In that case the value at a given node is equal to the weight of a node times a measure of beta trait-based diversity between the lineages that descend from the node. The sum of all values attributed to the nodes of a phylogeny is equal to the total trait-based diversity of the species (tips of the phylogeny) as defined by Rao's quadratic entropy. In case of dichotomic trees, only two lineages descend from a given node. Here I consider a more general case where more than two lineages may descend from a node (polytomy). The beta trait-based diversity among the lineages that descend from a node is measured here as the average trait-based dissimilarity between any two of these descending lineages. With option = 1, the trait-based dissimilarity between two lineages is measured by Rao's DISC index (gamma diversity [average trait-based dissimilarity between any two species descending from the node] - alpha diversity [average trait-based dissimilarity between any two species descending from one of the lineages branched to the node]).

In the present version of function decdiv, I have added other options. Options 2 and 3 code different ways of measuring trait-based differences between lineages, standardized between 0 and 1: with option = 2, the formula is (gamma - alpha) / (1 - alpha) * M / (M - 1), where gamma and alpha are defined above (for option = 1) and M is the number of lineages descending from the node; with option = 3, the formula is (gamma - alpha) / (1 - gamma) / (M - 1).

Options 4 and 5 decompose the result given by option = 1. option = 4 returns gamma minus alpha (a measure of beta functional diversity between the lineages that descend from a node). option = 5 returns the weights of the nodes (the summed relative abundance of its descending species or the relative number of descending species if presence/absence data are used).

Values for option different from 1 needs that values in dis (the trait-based dissimilarities between species) are bounded between 0 and 1 if formula = QE or sqrt(2) if formula = EDI. If they are not bounded, the function decdiv will bound them using the maximum observed value in dis.

The argument ties.method in rtestdecdiv allows you to explicitly take into account potential ties when ranking nodes according to their complexity or their distance to root (see Pavoine et al. 2010 for more details on the permutation test implemented in rtestdecdiv).

Value

Function decdiv returns a matrix with nodes of the phylogenetic tree as rows and the decomposition of trait-based diversity in communities as columns. An attribute of this matrix is the phylogenetic tree (of class phylo with specified names for nodes). If the nodes of phyl had no names, the function decdiv automatically attributed names to them.

Author(s)

Sandrine Pavoine [e-mail]

References

Champely, S. and Chessel, D. (2002) Measuring biological diversity using Euclidean metrics. Environmental and Ecological Statistics, 9, 167–177.

Pavoine, S., Baguette, M., Bonsall, M.B. (2010) Decomposition of trait diversity among the nodes of a phylogenetic tree. Ecological Monographs, 80, 485–507.

Rao, C.R. (1982) Diversity and dissimilarity coefficients: a unified approach. Theoretical Population Biology, 21, 24–43.

Examples

## Not run: 
if(require(ape) && require(adephylo)){
data(ungulates)
ung.phy <- read.tree(text=ungulates$tre)
ung.phy$node.label
plot(ung.phy, show.node.label=TRUE)
# Regaring traits, we log-tranformed the first three traits 
# measuring volumes 
# and we standardized all the traits (mean=0; variance=1).
tab <- cbind.data.frame(afbw = log(ungulates$tab$afbw),
mnw = log(ungulates$tab$mnw), fnw = log(ungulates$tab$fnw),
ls = ungulates$tab$ls)
ung.tab0 <- data.frame(scalewt(tab))
ung.tab0 <- data.frame(scalewt(log(ungulates$tab)))
ung.pres <- rep(1, nrow(ung.tab0))
names(ung.pres) <- rownames(ung.tab0)
ung.dec1 <- decdiv(ung.phy, ung.pres, dist(ung.tab0), 
    option=1, formula = "EDI")
plot.decdiv(ung.dec1)

ung.dec2 <- decdiv(ung.phy, ung.pres, dist(ung.tab0), 
    option=2, formula = "EDI")
plot.decdiv(ung.dec2)

ung.dec3 <- decdiv(ung.phy, ung.pres, dist(ung.tab0), 
    option=3, formula = "EDI")
plot.decdiv(ung.dec3)

ung.dec4 <- decdiv(ung.phy, ung.pres, dist(ung.tab0), 
    option=4, formula = "EDI")
plot.decdiv(ung.dec4)

ung.dec5 <- decdiv(ung.phy, ung.pres, dist(ung.tab0), 
    option=5, formula = "EDI")
plot.decdiv(ung.dec5)
}

## End(Not run)