decdiv {adiv} | R Documentation |

## 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 |

`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 |

`dis` |
either |

`tol` |
a tolerance threshold (a value between - |

`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 |

`x` |
an object of class |

`ncom` |
if |

`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 |

`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 |

`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 |

`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 sandrine.pavoine@mnhn.fr

### 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)
```

*adiv*version 2.2.1 Index]