Clarity individual table sorting requirements before subset

Author: hyanwong

python/tskit/tables.py

@@ -3807,7 +3807,8 @@ def sort_individuals(self):
         """
         Sorts the individual table in place, so that parents come before children,
         and the parent column is remapped as required. Node references to individuals
-        are also updated.
+        are also updated. This is a stricter order than is required for a valid tree
+        sequence.
         """
         self._ll_tables.sort_individuals()
         # TODO add provenance
@@ -3816,9 +3817,11 @@ def canonicalise(self, remove_unreferenced=None):
         """
         This puts the tables in *canonical* form, imposing a stricter order on the
         tables than :ref:`required <sec_valid_tree_sequence_requirements>` for
-        a valid tree sequence. In particular, the individual
-        and population tables are sorted by the first node that refers to each
-        (see :meth:`TreeSequence.subset`). Then, the remaining tables are sorted
+        a valid tree sequence. In particular, the population table is sorted to
+        place populations with the lowest node IDs first, and the individual table
+        is sorted firstly as in :meth:`.sort_individuals` and secondarily
+        by the lowest ID of the nodes that refer to each individual
+        (see :meth:`TreeSequence.subset`). The remaining tables are sorted
         as in :meth:`.sort`, with the modification that mutations are sorted by
         site, then time (if known), then the mutation's node's time, then number
         of descendant mutations (ensuring that parent mutations occur before

python/tskit/trees.py

@@ -7513,11 +7513,15 @@ def subset(
         the ancestry of these nodes - for that, see :meth:`.simplify`.
 
         This has the side effect that it may change the order of the nodes,
-        individuals, populations, and migrations in the tree sequence: the nodes
-        in the new tree sequence will be in the order provided in ``nodes``, and
-        both individuals and populations will be ordered by the earliest retained
-        node that refers to them. (However, ``reorder_populations`` may be set to
-        False to keep the population table unchanged.)
+        populations, individuals, and migrations in the tree sequence. Nodes
+        in the new tree sequence will be in the order provided in ``nodes``.
+        Populations will be ordered in ascending order of the lowest ID of
+        the nodes that refer to them. Individuals will be not only ordered
+        so that :attr:`~Individual.parents` come before children (see
+        :meth:`~TableCollection.sort_individuals`) but in addition
+        will be secondarily sorted in ascending order of the lowest ID of
+        their referring nodes. (However, ``reorder_populations`` may be set
+        to ``False`` to keep the population table unchanged.)
 
         By default, the method removes all individuals and populations not
         referenced by any nodes, and all sites not referenced by any mutations.