IbasedI: 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
)

Value

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

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.

Author

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

Run this code

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

Run the code above in your browser using DataLab