Phylogenetic Tree Statistics • treestats

Measuring properties of phylogenetic trees

The treestats R package contains rapid, C++ based, functions to calculate summary statistics on phylogenies. For some functions (but not all, see below), the phylogenies are required to be ultrametric and/or binary.

Getting started

Installation

To get started, you can either install from CRAN or use the latest version from GitHub:

install.packages("treestats") # install from CRAN

# use the devtools package to install latest version from GitHub:
install.packages("devtools")
devtools::install_github("thijsjanzen/treestats")

Basic usage

Given a tree (for example a simulated tree, as in the code example), you can either access individual statistics, or calculate all currently implemented statistics:

focal_tree   <- ape::rphylo(n = 10, birth = 1, death = 0)
colless_stat <- treestats::colless(focal_tree)
all_stats    <- treestats::calc_all_stats(focal_tree)

List of statistics

The following summary statistics are included:

Statistic	Information	Fischer	Normalization	Assumes Ultrametric tree	Requires binary tree	Assumes rooted tree	Sensitive to root position	Reference
area_per_pair	Topology	Shape	Yule	NO	YES	YES	YES	Lima et al., 2020
average_leaf_depth	Topology	Imbalance	Yule	NO	YES	YES	YES	Shao & Sokal, 1990
avg_ladder	Topology	Shape	None	NO	YES	YES	YES	Kendall et al., 2018
avg_vert_depth	Topology	Imbalance	None	NO	NO	YES	YES	Colijn & Gardy, 2014
b1	Topology	Balance	Tips	NO	NO	YES	YES	Shao & Sokal, 1990
b2	Topology	Balance	Yule	NO	NO	YES	YES	Shao & Sokal, 1990
beta	Topology	No index	None	NO	YES	YES	YES	Aldous, 1996
blum	Topology	Imbalance	None	NO	YES	YES	YES	Blum & François, 2006
cherries	Topology	Shape	Yule	NO	YES	NO	YES	McKenzie et al., 1999
colless	Topology	Imbalance	Yule	NO	YES	YES	YES	Colless, 1982
colless_corr	Topology	Imbalance	None	NO	YES	YES	YES	Heard, 1992
colless_quad	Topology	Imbalance	None	NO	YES	YES	YES	Bartoszek et al., 2021
crown_age	Branching times	No index	None	NO	NO	YES	YES
diameter	Topology	Shape	None	NO	YES	YES	YES	Chindelevitch et al., 2021
double_cherries	Topology	Shape	None	NO	YES	NO	YES	Chindelevitch et al., 2021
eigen_centrality	Topology	No index	None	NO	NO	NO	YES	Chindelevitch et al., 2021
eigen_centralityW	Topology + branch lengths	No index	None	NO	NO	NO	YES	Chindelevitch et al., 2021
ew_colless	Topology	Imbalance	None	NO	YES	YES	YES	Mooers & S. B. Heard, 1997
four_prong	Topology	Shape	None	NO	YES	NO	YES	Chindelevitch et al., 2021
gamma	Branching times	No index	None	YES	NO	YES	YES	Pybus & Harvey, 2000
i_stat	Topology	Imbalance	None	NO	YES	YES	YES	Fusco & Cronk, 1995
il_number	Topology	Shape	Tips	NO	NO	NO	YES	Kendall et al., 2018
imbalance_steps	Topology	No index	Tips	NO	NO	YES	YES	Janzen & Etienne, 2024
j_one	Topology	No index	None	NO	YES	YES	YES	Lemant et al., 2022
j_stat	Topology + branch lengths	No index	None	NO	NO	NO	NO	Izsák & Papp, 2000
laplace_spectrum_a	Topology + branch lengths	No index	None	YES	NO	NO	YES	Lewitus & Morlon, 2016
laplace_spectrum_e	Topology + branch lengths	No index	None	YES	NO	NO	YES	Lewitus & Morlon, 2016
laplace_spectrum_g	Topology + branch lengths	No index	None	YES	NO	NO	YES	Lewitus & Morlon, 2016
laplace_spectrum_p	Topology + branch lengths	No index	None	YES	NO	NO	YES	Lewitus & Morlon, 2016
max_adj	Topology + branch lengths	No index	None	NO	YES	NO	YES	Chindelevitch et al., 2021
max_betweenness	Topology	Shape	Tips	NO	YES	YES	YES	Chindelevitch et al., 2021
max_closeness	Topology	Shape	Tips	NO	YES	NO	Small	Chindelevitch et al., 2021
max_closenessW	Topology + branch lengths	Shape	None	NO	YES	NO	Small	Chindelevitch et al., 2021
max_del_width	Topology	Shape	Tips	NO	NO	YES	YES	Colijn & Gardy, 2014
max_depth	Topology	Imbalance	Tips	NO	NO	YES	YES	Colijn & Gardy, 2014
max_ladder	Topology	Shape	None	NO	YES	NO	YES	Kendall et al., 2018
max_laplace	Topology + branch lengths	No index	None	NO	YES	NO	YES	Chindelevitch et al., 2021
max_width	Topology	Balance	Tips	NO	NO	YES	YES	Colijn & Gardy, 2014
mean_branch_length	Topology + branch lengths	No index	None	NO	NO	NO	YES	Janzen & Etienne, 2017
mean_branch_length_ext	Topology + branch lengths	No index	None	NO	NO	NO	NO	Saulnier et al., 2017
mean_branch_length_int	Topology + branch lengths	No index	None	NO	NO	NO	YES	Saulnier et al., 2017
min_adj	Topology + branch lengths	No index	None	NO	YES	NO	YES	Chindelevitch et al., 2021
min_laplace	Topology + branch lengths	No index	None	NO	YES	NO	YES	Chindelevitch et al., 2021
mntd	Topology + branch lengths	No index	None	NO	NO	NO	NO	Webb et al., 2002
mpd	Topology + branch lengths	No index	Tips	NO	NO	NO	NO	Webb et al., 2002
mw_over_md	Topology	Balance	None	NO	NO	YES	YES	Colijn & Gardy, 2014
nltt_base	Branching times	No index	None	YES	NO	YES	YES	Janzen et al., 2015
number_of_lineages	Topology + branch lengths	No index	None	NO	NO	NO	NO
phylogenetic_div	Topology + branch lengths	No index	None	NO	NO	YES	YES	Faith, 1992
pigot_rho	Branching times	No index	None	YES	NO	YES	YES	Pigot et al., 2010
pitchforks	Topology	Shape	Tips	NO	NO	NO	YES	Kendall et al., 2018
psv	Topology + branch lengths	No index	Tips	NO	NO	NO	NO	Helmus et al., 2007
rogers	Topology	Imbalance	Tips	NO	YES	NO	YES	Rogers, 1996
root_imbalance	Topology	Shape	None	NO	YES	YES	YES	Guyer et al., 1993
rquartet	Topology	Balance	Yule	NO	NO	YES	YES	Coronado et al., 2019
sackin	Topology	Imbalance	Yule	NO	YES	YES	YES	Sackin, 1972
stairs	Topology	Imbalance	None	NO	YES	YES	YES	Norström et al., 2012
stairs2	Topology	Balance	None	NO	YES	YES	YES	Norström et al., 2012
symmetry_nodes	Topology	Imbalance	Tips	NO	YES	YES	YES	Kersting & Fischer, 2021
tot_coph	Topology	Imbalance	Yule	NO	YES	YES	YES	Mir et al., 2013
tot_internal_path	Topology	Imbalance	None	NO	NO	YES	YES	Knuth, 1997
tot_path	Topology	Imbalance	None	NO	YES	YES	YES	Colijn & Gardy, 2014
tree_height	Branching times	No index	None	NO	NO	YES	YES
treeness	Topology + branch lengths	No index	None	NO	NO	NO	YES	Astolfi & Zonta-Sgaramella, 1984
var_branch_length	Topology + branch lengths	No index	None	NO	NO	NO	YES	Saulnier et al., 2017
var_branch_length_ext	Topology + branch lengths	No index	None	NO	NO	NO	YES	Saulnier et al., 2017
var_branch_length_int	Topology + branch lengths	No index	None	NO	NO	NO	YES	Saulnier et al., 2017
var_depth	Topology	Imbalance	Yule	NO	NO	YES	YES	Coronado et al., 2020
vpd	Topology + branch lengths	No index	None	NO	NO	NO	NO	Webb et al., 2002
wiener	Topology + branch lengths	Shape	None	NO	YES	NO	YES	Chindelevitch et al., 2021

Rcpp

For all of these statistics, the package provides Rcpp versions that are much, much faster than their R sister functions. Furthermore, some additional functions have been improved as well: * ape::branching.times * DDD::phylo2L * DDD::L2phylo

C++ Library

For the Rcpp improved summary statistics (excluding statistics that rely on the calculation of eigen values, as these rely on the Rcpp independent Eigen code), R independent C++ code is provided in the inst/include folder. These can be independently linked by adding the treestats package in the DESCRIPTION in both the LinkingTo and Depends fields. Then, in your package, you can also calculate these functions.

Please note that for all functions, there are two versions available: 1) based on input of a phylo object, which is typically one 2-column matrix containing all edges, and a vector containing the edge lengths (depending on which information is required to calculate the statistic). 2) based on input of an Ltable (Lineage table), which is a 4-column matrix containing information on each species, being 1) birth time, 2) parent species, 3) species label and 4) death time (or -1 if extant).

Ltable input can be useful when summary statistics are required for more complicated simulation models.