Clarify mutation order in Site() object

[hyanwong]

This is useful to know without having to dive into the order requirements docs. I'm often looking this up to find the inherited state at a node.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.86%. Comparing base (d1d5bb7) to head (96777dc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3067   +/-   ##
=======================================
  Coverage   89.86%   89.86%           
=======================================
  Files          29       29           
  Lines       32150    32150           
  Branches     5768     5768           
=======================================
  Hits        28890    28890           
  Misses       1859     1859           
  Partials     1401     1401           

Flag	Coverage Δ
c-tests	86.71% <ø> (ø)
lwt-tests	80.78% <ø> (ø)
python-c-tests	89.05% <ø> (ø)
python-tests	98.98% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/tskit/trees.py	98.80% <ø> (ø)

[jeromekelleher]

Note that there are are loopholes in the mutation data requirements which means that it's possible for this to not actually be true (which is a bug, but not one we can easily resolve now)

[hyanwong]

Right, I know that the sorting process doesn't necessarily enforce parent/child correctness (and this is noted in the docs, and in #2732) but they also say:

when there are multiple mutations per site, mutations should be ordered by decreasing time, if known, and parent mutations must occur before their children..
Violations of these sorting requirements are detected at load time.

I guess violations of mutation parent order are not (yet?) detected at load time, so the doc wording should be changed to point out this bug?

Edit - I see this is part of #2757 (comment)

[jeromekelleher]

It's a bit tricky. Maybe you could put in a link to the definitions instead of explaining, so at least it's all in one place?

[hyanwong]

Maybe we just leave this open until it's (eventually) fixed? It does my head in trying to figure out from the rather involved mutation sorting requirements that the most recent mutations for a site are (should be) at the end of the list. I feel that just needs to be stated simply somewhere, for the non-technical reader.