# Getting started

#### Thijs Janzen

#### 2026-08-24

# Using treestats

The treestats package provides an easy to use interface to calculate summary statistics on phylogenetic trees. To obtain a list of all supported summary statistics use:

    list_statistics()

    ##  [1] "area_per_pair"          "average_leaf_depth"     "avg_ladder"
    ##  [4] "avg_vert_depth"         "b1"                     "b2"
    ##  [7] "beta"                   "cherries"               "colless"
    ## [10] "colless_corr"           "colless_quad"           "crown_age"
    ## [13] "diameter"               "double_cherries"        "eigen_centrality"
    ## [16] "eigen_centralityW"      "ew_colless"             "four_prong"
    ## [19] "gamma"                  "i_stat"                 "il_number"
    ## [22] "imbalance_steps"        "j_one"                  "j_stat"
    ## [25] "laplace_spectrum_a"     "laplace_spectrum_e"     "laplace_spectrum_g"
    ## [28] "laplace_spectrum_p"     "max_adj"                "max_betweenness"
    ## [31] "max_closeness"          "max_closenessW"         "max_del_width"
    ## [34] "max_depth"              "max_ladder"             "max_laplace"
    ## [37] "max_width"              "mean_branch_length"     "mean_branch_length_ext"
    ## [40] "mean_branch_length_int" "mean_inv_branch_dist"   "min_adj"
    ## [43] "min_laplace"            "mntd"                   "mpd"
    ## [46] "mw_over_md"             "nltt_base"              "number_of_lineages"
    ## [49] "phylogenetic_div"       "pigot_rho"              "pitchforks"
    ## [52] "psv"                    "rogers"                 "root_imbalance"
    ## [55] "rquartet"               "sackin"                 "sshape"
    ## [58] "stairs"                 "stairs2"                "symmetry_nodes"
    ## [61] "tot_coph"               "tot_internal_path"      "tot_path"
    ## [64] "tree_height"            "treeness"               "var_branch_length"
    ## [67] "var_branch_length_ext"  "var_branch_length_int"  "var_depth"
    ## [70] "vpd"                    "wiener"

If your favourite summary statistic is missing, please let the maintainer know, treestats is a dynamic package always under development, and the maintainers are always looking for new statistics!

Given a phylogenetic tree, you can now use of the available functions to calculate your summary statistic of choice. Let’s take for instance the Colless statistic (and we generate a dummy tree):

    phy <- ape::rphylo(n = 100, birth = 1, death = 0.1)

    treestats::colless(phy)

    ## [1] 387

Looking at the documentation of the colless statistic (`?colless`), we find that the function also includes options to normalize for size: either ‘pda’ or ‘yule’:

    treestats::colless(phy, normalization = "yule")

    ## [1] 0.3807613

## Multiple statistics

The treestats package supports calculating many statistics in one go. For this, several functions have been set up aptly. Firstly, the function `calc_all_stats` will calculate all statistics:

    all_stats <- calc_all_stats(phy)

Similarly, we can also blanket apply all topology associated summary statistics:

    balance_stats <- calc_topology_stats(phy)
    unlist(balance_stats)

    ##      area_per_pair average_leaf_depth         avg_ladder     avg_vert_depth
    ##       1.352626e+01       8.550000e+00       2.142857e+00       7.597990e+00
    ##                 b1                 b2               beta           cherries
    ##       5.395791e+01       5.420227e+00      -3.815967e-01       3.500000e+01
    ##            colless       colless_corr       colless_quad           diameter
    ##       3.870000e+02       7.977737e-02       8.645000e+03       2.400000e+01
    ##    double_cherries   eigen_centrality         ew_colless         four_prong
    ##       6.000000e+00       2.918844e-01       4.316212e-01       4.000000e+00
    ##             i_stat          il_number    imbalance_steps              j_one
    ##       5.067291e-01       3.000000e+01       8.400000e+01       7.770592e-01
    ##    max_betweenness      max_closeness      max_del_width          max_depth
    ##       1.152900e+04                 NA       8.000000e+00       1.500000e+01
    ##         max_ladder          max_width         mw_over_md         pitchforks
    ##       3.000000e+00       2.800000e+01       1.866667e+00       1.300000e+01
    ##             rogers     root_imbalance           rquartet             sackin
    ##       5.500000e+01       7.600000e-01       3.526491e+06       8.550000e+02
    ##             sshape             stairs            stairs2     symmetry_nodes
    ##       1.695977e+02       5.555556e-01       6.561428e-01       5.500000e+01
    ##           tot_coph  tot_internal_path    tot_path_length          var_depth
    ##       8.845000e+03       6.570000e+02       1.512000e+03       7.887500e+00