Document migrations as a legacy feature, and tidy those docs

[hyanwong]

Also fixes #1157

As per discussion below:

Jerome: I regard the record_migrations option in msprime to be a legacy feature that has been superseded by the additional nodes feature, which provides the same information as nodes explicitly marking migrations and edges, and is much simpler.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.76%. Comparing base (c81a38d) to head (8de2994).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3348   +/-   ##
=======================================
  Coverage   89.76%   89.76%           
=======================================
  Files          29       29           
  Lines       31292    31292           
  Branches     5738     5738           
=======================================
  Hits        28089    28089           
  Misses       1794     1794           
  Partials     1409     1409           

Flag	Coverage Δ
c-tests	86.77% <ø> (ø)
lwt-tests	80.38% <ø> (ø)
python-c-tests	87.12% <ø> (ø)
python-tests	98.85% <ø> (ø)
python-tests-no-jit	33.51% <ø> (ø)
python-tests-numpy1	50.28% <ø> (ø)

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jeromekelleher]

Can you check what msprime actually does here, please?

[jeromekelleher]

Honestly I'm not sure it's worth clarifying this - it's basically a very rarely used feature of msprime which we wouldn't bother putting in now (having been made redundant by tracking migration nodes).

[jeromekelleher]

I would vote for just saying this is a legacy thing that was tied to an old version of msprime, which may be removed from the data model entirely at some point. We do nothing at all with these in tskit.

[hyanwong]

I would be +1 for removing it. But I think if it is in there we should probably clarify what src and dest actually mean, right? This was my attempt to do so, but I got it wrong, I think (which speaks to how confusing it is at the moment).

Should we put a marker into the table definition to say that this is something that could be removed from the tskit data model (which would solve a number of other issues, I think, such as migrations not being supported in various methods, most notably simplify()

[jeromekelleher]

Should we put a marker into the table definition to say that this is something that could be removed from the tskit data model (which would solve a number of other issues, I think, such as migrations not being supported in various methods, most notably simplify()

I think so yeah. We can also just put in a seealso link to the documentation in msprime, which should be definitive.

[hyanwong]

Great points about marking-as-legacy and also linking to the extensive section(s) in the msprime pages, which have much more info. I have done both of these in the latest commit, and corrected my source/dest confusion (with a link to the definition of time section in the msprime docs).

I'm really very happy with marking this as an part of the data model that could be removed, and I think it's good to give people warning of that.

[jeromekelleher]

So to be clear, I regard the record_migrations option in msprime to be a legacy feature that has been superseded by the additional nodes feature, which provides the same information as nodes explicitly marking migrations and edges, and is much simpler.

[jeromekelleher]

typo