Add docs and C changelog

Author: benjeffery

c/CHANGELOG.rst

@@ -1,3 +1,35 @@
+--------------------
+[1.2.0] - 2025-XX-XX
+--------------------
+
+**Breaking changes**
+
+- ``tsk_treeseq_init`` now requires that mutation parents in the table collection
+  are correct and consistent with the topology of the tree at the mutation site.
+  Returns ``TSK_ERR_BAD_MUTATION_PARENT`` if this is not the case, or 
+  ``TSK_ERR_MUTATION_PARENT_AFTER_CHILD`` if the mutations are not in an order
+  compatible with the correct mutation parent.
+  (:user:`benjeffery`, :issue:`2729`, :issue:`2732`, :pr:`3212`).
+
+**Features**
+
+- Add ``TSK_TS_INIT_COMPUTE_MUTATION_PARENTS`` to ``tsk_treeseq_init``
+  to compute mutation parents from the tree sequence topology.
+  Note that the mutations must be in the correct order.
+  (:user:`benjeffery`, :issue:`2757`, :pr:`3212`).
+
+- Add ``TSK_CHECK_MUTATION_PARENTS`` option to ``tsk_table_collection_check_integrity``
+  to check that mutation parents are consistent with the tree sequence topology.
+  This option implies ``TSK_CHECK_TREES``.
+  (:user:`benjeffery`, :issue:`2729`, :issue:`2732`, :pr:`3212`).
+
+- Add the ``TSK_NO_CHECK_INTEGRITY`` option to ``tsk_table_collection_compute_mutation_parents``
+  to skip the integrity checks that are normally run when computing mutation parents.
+  This is useful for speeding up the computation of mutation parents when the
+  tree sequence is certainly known to be valid.
+  (:user:`benjeffery`, :pr:`3212`).
+
+
 --------------------
 [1.1.4] - 2025-03-31
 --------------------

docs/data-model.md

@@ -507,13 +507,14 @@ requirements for a valid set of mutations are:
   `time` and equal to or less than the `time` of the `parent` mutation
   if this mutation has one. If one mutation on a site has `UNKNOWN_TIME` then
   all mutations at that site must, as a mixture of known and unknown is not valid.
-- `parent` must either be the null ID (-1) or a valid mutation ID within the
-  current table
+- `parent` must either be the null ID (-1), if the mutation has no parent, or a
+  valid mutation ID within the current table. 
 
 Furthermore,
 
-- If another mutation occurs on the tree above the mutation in
-  question, its ID must be listed as the `parent`.
+- The `parent` value must be consistent with the topology of the tree at the site
+  of the mutation, such that a path from the child mutation to the parent mutation
+  exists without passing through any other mutations at the same site.
 
 For simplicity and algorithmic efficiency, mutations must also:
 

python/tskit/tables.py

@@ -3682,8 +3682,8 @@ def compute_mutation_parents(self):
         valid, and the site and mutation tables must be sorted (see
         :meth:`TableCollection.sort`).  This will produce an error if mutations
         are not sorted (i.e., if a mutation appears before its mutation parent)
-        *unless* the two mutations occur on the same branch, in which case
-        there is no way to detect the error.
+        *unless* the two mutations occur on the same branch, and have unknown times
+        in which case there is no way to detect the error.
 
         The ``parent`` of a given mutation is the ID of the next mutation
         encountered traversing the tree upwards from that mutation, or