aptree {adiv}

Hierarchical Partitioning of Evolutionary and Ecological Patterns in the Organization of Phylogenetically-Structured Species Assemblages

Description

apd performs Hardy (2008)'s test for phylogenetic structure in species abundance distribution;

aptree apportions the diversity (according to index I_a by Pavoine et al. 2009) within one or several communities between evolutionary periods;

plot.aptree displays the phylogenetic tree with vertical lines at each speciation event (limits of the evolutionary periods), the first period starts at the tips and the last one ends at the root node; the phylogenetic tree is pruned retaining only the species present in at least one of the observed communities;

abgaptree provides the apportionment of alpha, beta and gamma diversities between evolutionary periods, according to index I_a by Pavoine et al. (2009);

rtestaptree performs the test of phylogenetic signal in the differences between communities at each evolutionary periods;

plot.rtestaptree displays the phylogenetic tree with vertical lines at each speciation event (limits of the evolutionary periods; see above); colours are used to highlight the periods where the dissimilarities between communities are different from that expected at random;

tecAptree provides technical information for the apportionment of diversity between evolutionary periods;

pIa calculates the index I_a by Pavoine et al. (2009) within each community.

Usage

apd(phyl, comm, wcom = c("even", "speciesab"), nrep = 99, 
alter = "two-sided", tol = 1e-08)

aptree(phyl, comm, exponent = 2, tol = 1e-08)

## S3 method for class 'aptree'
plot(x, col.line = 'blue', ...)

abgaptree(phyl, comm, exponent = 2, 
wcom = c("even", "speciesab"), tol = 1e-08)

rtestaptree(phyl, comm, nrep = 99, alter = "two-sided", 
exponent = 2, wcom = c("even", "speciesab"), tol = 1e-08)

## S3 method for class 'rtestaptree'
plot(x, col.line = c("blue", "red"), 
alpha = 0.05, ...)

tecAptree(phyl, v = NULL, tol = 1e-08)

pIa(phyl, comm, exponent = 2, tol = 1e-08)

Arguments

phyl

an object inheriting the class phylo (see package ape), phylo4 (see package phylobase), or hclust.

comm

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 should be labeled as in the phylogenetic tree where they are the tips. In function aptree, comm can be a vector that provides the presence/absence or an index of abundance within a single community.

wcom

a numeric vector that gives the weight attributed to the community. The weights must be positive and their sum equals 1.

nrep

a numeric that gives the number of permutations.

alter

a string specifying the alternative hypothesis; it must be one of "greater", "less" or "two-sided".

tol

a numeric. If the absolute value of a statistic is less than tol, this statistic is considered equal to zero.

exponent

a numeric that gives the value of parameter a in index I_a.

x

in plot.aptree, x is an object inheriting class aptree obtained with function aptree. In plot.rtestaptree, x is an object inheriting class rtestaptree obtained with function rtestaptree.

col.line

in plot.aptree, col.line is a string which attributes a colour to the vertical lines placed at each speciation event and defining the evolutionary periods. In plot.rtestaptree, it is a vector with two strings. These strings give colours to the vertical lines placed at each speciation event. The first colour is used when the differences between communities at the evolutionary period are not significantly different from random; the second colour is used when they are.

alpha

a numeric: the nominal alpha level for significancy (the p-values calculated with function rtestaptree are compared to alpha to determine the result of the test).

...

further arguments passed to or from other methods.

v

either NULL or a vector that provides the presence/absence or an index of abundance of species within a single community.

Details

The approaches developed in these functions rely on a parametric index of phylogenetic diversity named I_a. The parameter a controls the importance given to rare versus abundant species in communities. Index I_a generalizes Rao's quadratic entropy (QE) applied to phylogenetic distances between species (when a=2) and Faith's Phylogenetic Diversity index (PD) (when a=0). When a tends towards 1, the index is a generalization of the Shannon index of diversity applied to phylogenetic data in addition to abundance data. In Pavoine et al. (2009), we developed this index and demonstrated how it can be used to partition diversity simultaneously across evolutionary periods in the phylogeny and across spatial (e.g. local communities in a region) and/or time units (e.g. a community investigated yearly).

Value

The function apd returns an object of class randtest with the results of the test (see function randtest in package ade4).

The function aptree returns a data frame with the evolutionary periods as rows, the communities as columns and the diversity values as entries.

The function plot.aptree returns a graph.

The function abgaptree returns a data frame with the evolutionary periods as rows, alpha diversity, beta diversity and gamma diversity as columns and the diversity values as entries.

The function rtestaptree returns an object of class krandtest with the results of the permutation tests. (see function krandtest in package ade4)

The function plot.rtestaptree returns a graph.

The function tecAptree returns a list. If v is NULL, the values of the list are:

h

the height at which each evolutionary period ends;

plength

period length;

ngroups

number of monophyletic groups per evolutionary period;

list

list of the species per monophyletic group at each evolutionary period;

call

original call.

If v contains a vector of presence/absence or abundance, the following object is added in the output:

relab

the relative abundance (sum of species' presences or abundances depending on v) of each monophyletic group at each evolutionary period.

The function pIa returns a data frame with communities as rows and only one column. This column gives, for each community, the value taken by index I_a of phylogenetic diversity developed by Pavoine et al. (2009).

Author(s)

Sandrine Pavoine [e-mail] with contributions of Stephane Dray.

References

Pavoine, S., Love, M., Bonsall, M.B. (2009) Hierarchical partitioning of evolutionary and ecological patterns in the organization of phylogenetically-structured species assemblages: application to rockfish (genus: Sebastes) in the Southern California Bight. Ecology Letters, 12, 898–908.

See Also

QE

Examples

## Not run: 
if(require(ape)){
data(rockfish)
phy <- read.tree(text=rockfish$tre)
ABG <- abgaptree(phy, rockfish$fau, wcom="speciesab")
colSums(ABG)
A <- aptree(phy, rockfish$fau)
colSums(A)
plot(A, cex=0.5)
P <- pIa(phy, rockfish$fau)
P
T <- apd(phy, rockfish$fau)
plot(T)
#R <- rtestaptree(phy, rockfish$fau, nrep=999, wcom="speciesab")
#plot(R)
TA <- tecAptree(phy)
TA$h
}

## End(Not run)