Clarify "dead" leaves

Fixes #339

Update python/tskit/trees.py

Co-authored-by: Jerome Kelleher <[email protected]>

Author: 2 people

docs/data-model.md

@@ -997,7 +997,7 @@ position 20 to 40, has a single root. Finally the third tree, from position
 
 #### The virtual root
 
-To access all the roots in a tree, tskit uses a special additional node
+To access all the :attr:`~Tree.roots` in a tree, tskit uses a special additional node
 called the **virtual root**. This is primarily a bookkeeping device, and
 can normally be ignored: it is not plotted in any visualizations and
 does not exist as an independent node in the node table.
@@ -1097,6 +1097,39 @@ print(
 In `tskit`, isolated sample nodes are closely associated with the encoding of
 {ref}`sec_data_model_missing_data`.
 
+
+(sec_data_model_tree_dead_leaves_and_branches)=
+
+### Dead leaves and branches
+
+In a `tskit` tree, a *leaf node* is defined as a node without any children. The
+implications of this turn out to be slighly unintuitive, and so are worth briefly
+documenting here. Firstly, the same node can be a leaf in one tree, and not a leaf
+in the next tree along the tree sequence. Secondly all isolated nodes must be leaves
+(as by definition they have no children). Thirdly sample nodes need not be leaves
+(they could be "internal samples"); likewise leaf nodes need not be samples.
+
+Node 7 in the example above provides a good case study. Note that it is a root node with
+at least one child (i.e. not a leaf) in trees 0 and 2; in contrast in tree 1 it is
+isolated. Strictly, because it is isolated in tree 1, it is also a leaf node there,
+although it is not attached to a root, not a sample, and is therefore not plotted. In
+this case, in that tree we can think of node 7 as a "dead leaf" (and we don't normally
+plot dead leaves). In fact, in a large tree sequence of many trees, most ancestral nodes
+will be isolated in any given tree, and therefore most nodes in such a tree will be of
+this sort. However, these dead leaves are excluded from most calculations on trees,
+because algorithms usually traverse the tree by starting at a root and working down,
+or by starting at a sample and working up. Hence when we refer to the leaves of a tree,
+it is usually shorthand for the leaves **on** the tree (that is, attached via branches,
+to one of the the tree roots). Dead leaves are excluded from this definition.
+
+Note that it is also possible to have trees in which there are "dead branches": that is
+sections of topology which are not accessible from a root, and whose tips are all
+dead leaves. Although valid, this is a relatively unusual state of affairs, and such
+branches are not plotted by the standard {ref}`sec_tskit_viz` methods. The
+{meth}`Tree.nodes` method will not, by default, traverse through dead branches, although
+it can be made to do so by specifying the ID of a dead node as the root for traversal.
+
+
 (sec_data_model_genetic_data)=
 
 ## Encoding genetic variation
@@ -1153,7 +1186,7 @@ outputs the actual allelic state for each sample, defaults to outputting an `N`
 these sites. Therefore where any sample node is isolated, the haplotype will show
 an `N`, indicating the DNA sequence is unknown. This will be so not only in the
 middle of all of the sample genomes, but also at the right hand end of the genome of
-sample 2, as it is the only isolated sample node in the rightmost tree:
+sample 2, as it is an isolated sample node in the rightmost tree:
 
 ```{code-cell} ipython3
 for i, h in enumerate(missing_ts.haplotypes()):

python/tskit/trees.py

@@ -1002,10 +1002,11 @@ def total_branch_length(self):
 
         As this is defined by a traversal of the tree, technically we
         return the sum of all branch lengths that are reachable from
-        roots. Thus, this is the sum of all branches that are ancestral
+        roots. Thus, this is the total length of all branches that are connected
         to at least one sample. This distinction is only important
         in tree sequences that contain 'dead branches', i.e., those
-        that define topology not ancestral to any samples.
+        that define topology that is not connected to a tree root
+        (see :ref:`sec_data_model_tree_dead_leaves_and_branches`)
 
         :return: The sum of lengths of branches in this tree.
         :rtype: float
@@ -1374,6 +1375,16 @@ def is_leaf(self, u):
         Returns True if the specified node is a leaf. A node :math:`u` is a
         leaf if it has zero children.
 
+        .. note::
+            :math:`u` can be any node in the entire tree sequence, including ones
+            which are not connected via branches to a root node of the tree (and which
+            are therefore not conventionally considered part of the tree). Indeed, if
+            there are many trees in the tree sequence, it is common for the majority of
+            non-sample nodes to be :meth:`isolated<is_isolated>` in any one
+            tree. By the definition above, this method will return ``True`` for such
+            a tree when a node of this sort is specified. Such nodes can be thought of
+            as "dead leaves", see :ref:`sec_data_model_tree_dead_leaves_and_branches`.
+
         :param int u: The node of interest.
         :return: True if u is a leaf node.
         :rtype: bool
@@ -1383,7 +1394,8 @@ def is_leaf(self, u):
     def is_isolated(self, u):
         """
         Returns True if the specified node is isolated in this tree: that is
-        it has no parents and no children. Sample nodes that are isolated
+        it has no parents and no children (note that all isolated nodes in the tree
+        are therefore also :meth:`leaves<Tree.is_leaf>`). Sample nodes that are isolated
         and have no mutations above them are used to represent
         :ref:`missing data<sec_data_model_missing_data>`.
 
@@ -2004,9 +2016,17 @@ def get_leaves(self, u):
 
     def leaves(self, u=None):
         """
-        Returns an iterator over all the leaves in this tree that are
-        underneath the specified node. If u is not specified, return all leaves
-        in the tree.
+        Returns an iterator over all the leaves in this tree that descend from
+        the specified node. If :math:`u`  is not specified, return all leaves on
+        the tree (i.e. all leaves reachable from the tree root(s), see note below).
+
+        .. note::
+            :math:`u` can be any node in the entire tree sequence, including ones
+            which are not connected via branches to a root node of the tree. If
+            called on such a node, the iterator will return "dead" leaves
+            (see :ref:`sec_data_model_tree_dead_leaves_and_branches`) which cannot
+            be reached from a root of this tree. However, dead leaves will never be
+            returned if :math:`u` is left unspecified.
 
         :param int u: The node of interest.
         :return: An iterator over all leaves in the subtree rooted at u.
@@ -2309,15 +2329,15 @@ def push(nodes):
 
     def nodes(self, root=None, order="preorder"):
         """
-        Returns an iterator over the node IDs reachable from the root(s) in this
+        Returns an iterator over the node IDs reachable from the specified node in this
         tree in the specified traversal order.
 
         .. note::
             Unlike the :meth:`TreeSequence.nodes` method, this iterator produces
             integer node IDs, not :class:`Node` objects.
 
         If the ``root`` parameter is not provided or ``None``, iterate over all
-        nodes reachable from the roots (see :meth:`Tree.roots` for details
+        nodes reachable from the roots (see :attr:`Tree.roots` for details
         on which nodes are considered roots). If the ``root`` parameter
         is provided, only the nodes in the subtree rooted at this node
         (including the specified node) will be iterated over. If the