abgevodivparam {adiv}

Apportionment of Parametric Indices of Phylogenetic Diversity

Description

Function abgevodivparam calculates alpha, beta and gamma components of phylogenetic diversity using parametric indices derived from Tsallis (HCDT) and Hill compositional indices. Alpha is for within-community diversity, beta for between-community diversity and gamma for the diversity of all combined communities.

Usage

abgevodivparam(phyl, comm, w = c("evoab", "even", "speciesab"),
method = c("hillCJC", "hillR", "tsallis"), q = 2, 
option = c("multiplicative", "additive", "proportional", 
"C", "U", "V", "S", "Renyi"), tol = 1e-08)

## S3 method for class 'abgevodivparam'
plot(x, legend = TRUE, 
legendposi = "topright", type = "b", 
col = if (is.numeric(x)) NULL else 1:nrow(x$div), 
lty = if (is.numeric(x)) NULL else rep(1, nrow(x$div)), 
pch = if (is.numeric(x)) NULL else 1:nrow(x$div), 
ylim1 = range(x$div[c("Alpha", "Gamma"), ]), ylim2 = NULL, ...)

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 an index of abundance as entries. Species should be labeled as in the phylogenetic tree where they are the tips.

w

either a numeric vector giving weights for communities (same order as in comm), or a code: one of "even", "evoab", and "speciesab". If several codes are given, only the first one is used. See details.

method

a string with one of the following codes: "tsallis", "hillR", or "hillCJC". See details.

q

a vector with nonnegative value(s) for parameter q. See details.

option

a string code: either "multiplicative", "additive" or "proportional". If several codes are given, only the first one is used. Only, with method="hillCJC", other options are possible: "C", "U", "V", "S", "Renyi". See details.

tol

numeric tolerance threshold: values between -tol and tol are considered equal to zero.

x

an object of class abgevodivparam obtained with function abgevodivparam.

legend

a logical. If TRUE a legend is given with the colour, the type of line (etc.) used to define the diversity curve of each diversity level (gamma, alpha, beta).

legendposi

a string that gives the position of the legend to be passed to function legend of the base of R.

type

a string to be passed to the graphic argument type of functions plot and lines used to draw the diversity curve of each diversity level (gamma, alpha, beta).

col

vector of colours to be passed to the graphic argument col of functions plot and lines to define the colour of the diversity curve of each diversity level (gamma, alpha, beta, in that order).

lty

vector of types of line (plain, broken etc.) to be passed to the graphic argument lty of functions plot and lines used to draw the diversity curve of each diversity level (gamma, alpha, beta, in that order).

pch

vector of types of point (open circle, close circle, square etc.) to be passed to the graphic argument pch of functions plot and lines used to draw the diversity level (gamma, alpha, beta, in that order).

ylim1

a vector with two numerics indicating the range to be used to display alpha and gamma diversity.

ylim2

a vector with two numerics indicating the range to be used to display beta diversity.

...

other arguments can be added and passed to the functions plot and lines used to draw the graphic.

Details

Consider a phylogenetic tree T, b_T the set of branches in T, k a branch, L_k the length of branch k, j a community (j=1,...,m), a_{jk} the abundance associated with branch k in community j (sum of abundance of all species descending from the branch). q is the parameter that increases with the importance given to abundant species compared to rare species in diversity.

The methods available are: tsallis (decomposition of Tsallis or HCDT entropy (Harvda and Charvat 1967; Daroczy 1970; Tsallis 1988) into alpha, beta, gamma components adapted here to phylogenetic diversity):

^q\gamma_{evoTsallis}=\left[1-\sum_{k \in b_T} L_k \left(\sum_{j=1}^m w_j \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q \right]/(q-1)

^q\alpha_{evoTsallis}=\sum_{j=1}^m w_j \left[1-\sum_{k \in b_T} L_k \left( \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q\right]/(q-1)

hillR (Routledge decomposition of Hill diversity into alpha, beta, gamma components adapted hete to phylogenetic diversity):

^q\gamma_{evoHill}=\left[\sum_{k \in b_T} L_k \left(\sum_{j=1}^m w_j \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q \right]^{1/(1-q)}

^q\alpha_{evoHill-R}=\left[\sum_{j=1}^m w_j \sum_{k \in b_T} L_k \left( \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q\right]^{1/(1-q)}

hillCJC (Chiu et al. (2014) decomposition of phylogenetic diversity into alpha, beta, gamma components, see Supplementary material Appendix 2 in Pavoine (2016) for a justification of the formulas):

^q\gamma_{evoHill}=\left[\sum_{k \in b_T} L_k \left(\sum_{j=1}^m w_j \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q \right]^{1/(1-q)}

^q\alpha_{evoHill-CJC}=\frac{1}{m}\left[\sum_{k \in b_T} L_k \sum_{j=1}^m (w_j)^q \left( \frac{a_{jk}}{\sum_{k \in b_T} L_k a_{jk}}\right)^q\right]^{1/(1-q)}

Then option "additive" calculates \beta diversity as \gamma-\alpha. Option "proportional" calculates \beta as (\gamma-\alpha)/\gamma. Option "multiplicative" calculates \beta diversity as \gamma/\alpha. Only for method="hillCJC", options "C", "U", "V", "S", use the multiplicative option and also calculate one of the transformations introduced by Chiu et al. (2014): indices 1-C_{qm}, 1-U_{qm}, 1-V_{qm}, and 1-S_{qm}, respectively. "Renyi" is the ^qevoD_{Renyi} index introduced in Pavoine (2016), see also Supplementary material Appendix 1 in Pavoine (2016).

The weights of the sites (argument w) can be "even" (even weights), "evoab" (proportional to the summed abundances of all evolutionary units), or "speciesab" (proportional to the summed abundances of all species). Note that if the phylogenetic tree is ultrametric (the distance from any species to the root is constant), then options "evoab" and "speciesab" are equivalent.

Value

If only one value of q is given, abgevodivparam returns a vector with alpha, beta, and gamma diversities. If more than one value of q is given, it returns a list of two objects:

q

the numeric vector of values for q.

div

a data frame with alpha, beta, gamma calculated for all values of q.

Only if method="hillCJC" and option= "C", "U", "V", "S", or "Renyi", the index 1-C_{qm} (for "C"), 1-U_{qm} (for "U"), 1-V_{qm} (for "V"), 1-S_{qm} (for "S") or the Renyi transformation (see above, for "Renyi" is also provided in the div data frame under the name "transformed.beta".

The function plot.abgevodivparam returns a graphic.

Author(s)

Sandrine Pavoine [e-mail]

References

The methodologies and scripts were presented in

Pavoine, S. (2016) A guide through a family of phylogenetic dissimilarity measures among sites. Oikos, 125, 1719–1732.

using earlier work by

Daroczy, Z. (1970) Generalized information functions. Information and Control, 16, 36–51.

Havrda, M., Charvat F. (1967) Quantification method of classification processes: concept of structural alpha- entropy. Kybernetik, 3, 30–35

Hill, M.O. (1973) Diversity and evenness: a unifying notation and its consequences. Ecology, 54, 427–432.

Routledge, R.D. (1979) Diversity indices: which ones are admissible? Journal of Theoretical Biology, 76, 503–515.

Rao, C.R. (1986) Rao's axiomatization of diversity measures. In: Kotz S, Johnson NL, editors. Encyclopedia of Statistical Sciences. New York: Wiley and Sons. pp. 614–617.

Chiu, C.-H., Jost, L., Chao, A. (2014) Phylogenetic beta diversity, similarity, and differentiation measures based on Hill numbers. Ecological Monographs, 84, 21–44.

See Also

evodiss, divparam, evodivparam

Examples

## Not run: 
if(require(ape)){
data(batcomm)
phy <- read.tree(text=batcomm$tre)
ab <- batcomm$ab[,phy$tip.label]
abgevodivparam(phy, ab)
plot(abgevodivparam(phy, ab))
abgevodivparam(phy, ab, q=0:4)
plot(abgevodivparam(phy, ab, q=0:4))
}

## End(Not run)