diff --git a/python/tskit/tables.py b/python/tskit/tables.py index d61f864593..5c47997d57 100644 --- a/python/tskit/tables.py +++ b/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 ` 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 diff --git a/python/tskit/trees.py b/python/tskit/trees.py index 7775231dde..c4ae2dc18a 100644 --- a/python/tskit/trees.py +++ b/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.