IbasedI: Calculation of the I-based indices for rooted trees

Description Usage Arguments Value Author(s) References Examples

View source: R/IbasedI.R

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(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=(k_va-ceiling(k_v/2))/(k_v-1-ceiling(k_v/2))

in which k_va 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 (k_v-1)/k_v*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>=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)=2*(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'_ρ, 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.

Usage

1
2
3
4
5
6
7
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

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

treebalance documentation built on Oct. 17, 2021, 5:06 p.m.