Docs and changelog for balance indexes

Closes #2261

docs/python-api.md

@@ -546,6 +546,16 @@ Functions and static methods
   Tree.kc_distance
 ```
 
+(sec_python_api_trees_balance)=
+
+#### Balance/imbalance indices
+
+```{eval-rst}
+.. autosummary::
+  Tree.colless_index
+  Tree.sackin_index
+  Tree.b1_index
+```
 
 (sec_python_api_trees_sites_mutations)=
 

python/CHANGELOG.rst

@@ -47,10 +47,22 @@
 - Add support for missing data to ``write_vcf``, and add the ``isolated_as_missing``
   argument. (:user:`jeromekelleher`, :pr:`2329`, :issue:`447`).
 
-- Add ``Tree.num_children_array`` and ``Tree.num_children``. Returns the counts of 
-  the number of child nodes for each or a single node in the tree respectively. 
+- Add ``Tree.num_children_array`` and ``Tree.num_children``. Returns the counts of
+  the number of child nodes for each or a single node in the tree respectively.
   (:user:`GertjanBisschop`, :issue:`2318`, :issue:`2319`, :pr:`2332`)
 
+- Add ``Tree.path_length``.
+  (:user:`jeremyguez`, :issue:`2249`, :pr:`2259`).
+
+- Add B1 tree balance index.
+  (:user:`jeremyguez`, :user:`jeromekelleher`, :issue:`2251`, :pr:`2281`, :pr:`2346`).
+
+- Add Sackin tree imbalance index.
+  (:user:`jeremyguez`, :user:`jeromekelleher`, :pr:`2246`, :pr:`2258`).
+
+- Add Colless tree imbalance index.
+  (:user:`jeremyguez`, :user:`jeromekelleher`, :issue:`2250`, :pr:`2266`, :pr:`2344`).
+
 **Breaking Changes**
 
 - The JSON metadata codec now interprets the empty string as an empty object. This means

python/tskit/trees.py

@@ -2783,9 +2783,10 @@ def path_length(self, u, v):
 
     def b1_index(self):
         """
-        Returns the B1 balance index for this tree.
-        This is defined as the inverse of the sum of all longest paths
-        to leaves for each node besides roots.
+        Returns the
+        `B1 balance index <https://treebalance.wordpress.com/b%E2%82%81-index/>`_
+        for this tree. This is defined as the inverse of the sum of all
+        longest paths to leaves for each node besides roots.
 
         .. seealso:: See `Shao and Sokal (1990)
             <https://www.jstor.org/stable/2992186>`_ for details.
@@ -2797,12 +2798,13 @@ def b1_index(self):
 
     def colless_index(self):
         """
-        Returns the Colless imbalance index for this tree.
-        This is defined as the sum of all differences between number of
-        leaves subtended by the left and right child of each node.
-        The Colless index is undefined for non-binary trees and trees
-        with multiple roots. This method will raise a LibraryError if the
-        tree is not singly-rooted and binary.
+        Returns the
+        `Colless imbalance index <https://treebalance.wordpress.com/colless-index/>`_
+        for this tree. This is defined as the sum of all differences between
+        number of leaves subtended by the left and right child of each node.
+        The Colless index is undefined for non-binary trees and trees with
+        multiple roots. This method will raise a LibraryError if the tree is
+        not singly-rooted and binary.
 
         .. seealso:: See `Shao and Sokal (1990)
             <https://www.jstor.org/stable/2992186>`_ for details.
@@ -2814,9 +2816,11 @@ def colless_index(self):
 
     def sackin_index(self):
         """
-        Returns the Sackin imbalance index for this tree. This is defined
-        as the sum of the depths of all leaves in the tree.
-        Equivalent to ``sum(tree.depth(u) for u in tree.leaves())``
+        Returns the
+        `Sackin imbalance index <https://treebalance.wordpress.com/sackin-index/>`_
+        for this tree. This is defined as the sum of the depths of all leaves
+        in the tree. Equivalent to ``sum(tree.depth(u) for u in
+        tree.leaves())``
 
         .. seealso:: See `Shao and Sokal (1990)
             <https://www.jstor.org/stable/2992186>`_ for details.