treebalance (version 1.2.0)

collesslikeI: Calculation of the Colless-like indices for rooted trees

Description

This function calculates the Colless-like index for a given rooted tree \(T\) according to the chosen weight function \(f\) and dissimilarity \(D\). The Colless-like index \(CL(T)\) relative to \(D\) and \(f\) is the sum of the \((D,f)\)-balance values over all inner vertices of the tree. More precisely, $$CL(T)=\sum_{v\in V_{in}(T)} bal_{D,f}(v)$$ where \(V_{in}(T)\) is the set of inner vertices of \(T\). The \((D,f)\)-balance value of \(v\) with children \(v_1,...,v_k\) is computed as $$bal_{D,f}(v)=D(fs(T_{v_1}),...,fs(T_{v_k}))$$ with \(D\) denoting the dissimilarity and \(fs\) denoting the f.size.
The f.size \(fs(T)\) of a tree \(T\) uses the function \(f\), which maps any integer to a non-negative real number, to build a weighted sum of the out-degrees of all vertices in \(T\). More precisely, $$fs(T)=\sum_{v\in V(T)} f(deg+(v))$$ where \(V(T)\) is the set of all vertices of \(T\) and \(deg+(v)\) denotes the out-degree (i.e. the number of children) of the vertex \(v\). The \(f\)-functions that are already implemented are \(f(x)=e^x\) and \(f(x)=ln(x+e)\).
The dissimilarity \(D(x_1,...,x_k)\) of a vector \(x_1,...,x_k\) assigns a non-negative value to the vector, is independent of the order of the vector entries and equals zero if and only if \(x_1=...=x_k\). In this implementation the following dissimilarity functions are already built-in: mean deviation from the median (\(mdm\)), the sample variance (\(var\)) and the sample standard deviation (\(sd\)).
collesslikeI also allows the use of other functions for the weight function \(f\) and the dissimilarity \(D\).

Special cases: For \(n=1\) the function returns \(CL(T)=0\) and a warning.

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

Usage

collesslikeI(tree, f.size, dissim)

Value

collesslikeI returns the Colless-like index of the given tree according to the chosen function and dissimilarity.

Arguments

tree

A rooted binary tree in phylo format.

f.size

A character string specifying the function \(f\) that shall be used to compute the f.size. It can be one of the following: "exp", "ln" or the name of a function as a string.

dissim

A character string specifying the dissimilarity that shall be used. It can be one of the following: "mdm", "var", "sd" or the name of a function as a string.

Author

Luise Kuehn, Sophie Kersting

References

A. Mir, L. Rotger, and F. Rossello. Sound Colless-like balance indices for multifurcating trees. PLOSONE, 13(9):e0203401, 2018. doi: 10.1371/journal.pone.0203401

Examples

tree <- ape::read.tree(text="((((,),),(,)),(((,),),(,)));")
collesslikeI(tree, f.size="exp", dissim="mdm")
collesslikeI(tree, f.size="exp", dissim="var")
collesslikeI(tree, f.size="ln", dissim="sd")
myfsize <- function(x) return(x+1)
mydissim <- function(x) return (var(x))
collesslikeI(tree, f.size="myfsize",dissim = "mydissim")