IbasedI {treebalance}

Calculation of the I-based indices for rooted trees

Description

This function calculates I-based indices I(T) for a given rooted tree T. Note that the leaves of the tree may represent single species or groups of more than one species. Thus, a vector is required that contains for each leaf the number of species that it represents. The tree may contain few polytomies, which are not allowed to concentrate in a particular region of the tree (see p. 238 in Fusco and Cronk (1995)).

Let v be a vertex of T that fulfills the following criteria: a) The number of descendant (terminal) species of v is k_v>3 (note that if each leaf represents only one species k_v is simply the number of leaves in the pending subtree rooted at v), and b) v has exactly two children.

Then, we can calculate the I_v value as follows:

I_v=\frac{k_{v_a}-\left\lceil\frac{k_v}{2}\right\rceil}{k_v-1-\left\lceil\frac{k_v}{2}\right\rceil}

in which k_{v_a} denotes the number of descendant (terminal) species in the bigger one of the two pending subtrees rooted at v.

As the expected value of I_v under the Yule model depends on k_v, Purvis et al. (2002) suggested to take the corrected values I'_v or I_v^w instead.
The I'_v value of v is defined as follows: I'_v=I_v if k_v is odd and I'_v=\frac{k_v-1}{k_v}\cdot I_v if k_v is even.
The I_v^w value of v is defined as follows:

I_v^w=\frac{w(I_v)\cdot I_v}{mean_{V'(T)} w(I_v)}

where V'(T) is the set of inner vertices of T that have precisely two children and k_v\geq 4, and w(I_v) is a weight function with w(I_v)=1 if k_v is odd and w(I_v)=\frac{k_v-1}{k_v} if k_v is even and I_v>0, and w(I_v)=\frac{2\cdot(k_v-1)}{k_v} if k_v is even and I_v=0.

The I-based index of T can now be calculated using different methods. Here, we only state the version for the I' correction method, but the non-corrected version or the I_v^w corrected version works analoguously. 1) root: The I' index of T equals the I'_v value of the root of T, i.e. I'(T)=I'_{\rho}, provided that the root fulfills the two criteria. Note that this method does not fulfil the definition of an (im)balance index. 2) median: The I' index of T equals the median I'_v value of all vertices v that fulfill the two criteria. 3) total: The I' index of T equals the summarised I'_v values of all vertices v that fulfill the two criteria. 4) mean: The I' index of T equals the mean I'_v value of all vertices v that fulfill the two criteria. 5) quartile deviation: The I' index of T equals the quartile deviation (half the difference between third and first quartile) of the I'_v values of all vertices v that fulfill the two criteria.

For details on the family of I-based indices, see also Chapter 17 in "Tree balance indices: a comprehensive survey" (https://doi.org/10.1007/978-3-031-39800-1_17).

Usage

IbasedI(
  tree,
  specnum = rep(1, length(tree$tip.label)),
  method = "mean",
  correction = "none",
  logs = TRUE
)

Arguments

tree

A rooted tree in phylo format (with possibly few polytomies).

specnum

A vector whose i-th entry is the number of species that the i-th leaf represents. (default is 1,...,1)

method

A character string specifying the method that shall be used to calculate I(T). It can be one of the following: "root", "median", "total", "mean", "quartdev".

correction

A character string specifying the correction method that shall be applied to the I values. It can be one of the following: "none", "prime", "w".

logs

Boolean value, (default true), determines if the number of suitable nodes (i.e. nodes that fulfill the criteria) and polytomies in the tree should be printed.

Value

IbasedI returns an I-based balance index of the given tree according to the chosen (correction and) method.

Author(s)

Luise Kuehn and Sophie Kersting

References

G. Fusco and Q. C. Cronk. A new method for evaluating the shape of large phylogenies. Journal of Theoretical Biology, 1995. doi: 10.1006/jtbi.1995.0136. URL https://doi.org/10.1006/jtbi.1995.0136.

A. Purvis, A. Katzourakis, and P.-M. Agapow. Evaluating Phylogenetic Tree Shape: Two Modifications to Fusco & Cronks Method. Journal of Theoretical Biology, 2002. doi: 10.1006/jtbi.2001.2443. URL https://doi.org/10.1006/jtbi.2001.2443.

Examples

tree <- ape::read.tree(text="(((((,),),),),);")
IbasedI(tree, method="mean")
IbasedI(tree, method="mean", correction="prime", specnum=c(1,1,2,1,1,1))