Revise SLiM recipe(s) to use msprime-generated SLiM mutations?

[bhaller]

Recipe 17.8 and 17.9 in the SLiM manual use msprime to generate a coalescent history without mutations, and load the resulting .trees into SLiM, do some simulating, dump, and then do analysis; neutral mutations are never overlaid, but they could be, at the end of the process, if desired. That seems like a reasonable and useful workflow.

However, we now also have the option to use msprime to generate a coalescent history with mutations, since it can now generate SLiM mutations that can be loaded into SLiM (i.e., with integer positions). We should certainly have an example of this in the manual too, to advertise the new capability. It seems to me that it ought to be a new recipe, not a replacement for 17.8/17.9, but I'm not sure.

[bhaller]

@petrelharp commented over in x:

We ought to move the msprime code in the SLiM manual over to using the new msprime.sim_ancestry( ) function anyhow. msprime.simulate( ) is maintained, but deprecated.

[bhaller]

Hi @petrelharp. So, note that the recipes live in GitHub at https://github.com/MesserLab/SLiM/tree/master/QtSLiM/recipes (and are duplicated in SLiMguiLegacy, but that's my problem :->). If you submit a PR with the changes from msprime.simulate( ) to msprime.sim_ancestry( ), I'll do the corresponding edits to the text of the manual, so that will clean up that minor issue (which is not really what this issue is about anyway; feel free to open a new issue on it if you want to separate the two).

To the main issue here: do you agree that the proposed recipe, to show how to generate SLiM mutations in msprime and import them into a simulation, ought to be a new recipe, rather than a revision of 17.8/17.9? If so, perhaps you could email me the code for such a recipe, and I'll do a writeup for it as a new recipe 17.11? Or if you now have a pyslim vignette that shows how to do this, perhaps I ought to just provide a link in the SLiM manual to your vignette? I don't think we need to duplicate our documentation efforts, anybody doing this kind of stuff should be reading your pyslim doc anyway. :-> Thoughts?

[petrelharp]

How about this one?
https://tskit.dev/pyslim/docs/latest/vignette_coalescent_diversity.html

[bhaller]

OK cool, so I'll just say "msprime can now generate mutations at integer positions, as required by SLiM, so now you can import msprime-generated .trees files that contain mutations; see this pyslim vignette for an example of this workflow". I'll put that in, and then I'll close this issue, if you're in agreement. Thanks!

[bhaller]

OK, I added this to recipe 17.10 (recapitation):

If the forward simulation actually needs to do something with the mutations that exist from the burn-in period, recapitation cannot be used. For example, you might want to model a soft sweep in which a neutral mutation from “deep time”, back in the burn-in period, becomes non-neutral due to an environmental change. The non-neutral time period must be forward-simulated in SLiM, as usual. The burn-in needs to be simulated first, with the coalescent in msprime, and then needs to have mutations overlaid onto it before forward simulation begins, so that those overlaid mutations get imported into SLiM for its use. The pyslim documentation has a nice example of this technique at https://tskit.dev/pyslim/docs/latest/vignette_coalescent_diversity.html.

I also edited section 17's intro to tree-seq to say:

• Moving between coalescent and forward simulation methods. Tree-sequence recording and the .trees file format build a sort of bridge between coalescent and forward simulation methods, allowing both methods to be used in a single simulation. For example, a neutral “burn-in” period for a model could be simulated using the coalescent in msprime without mutations, and the results saved to a .trees file in the proper SLiM-compatible format using pyslim. That .trees file could then be loaded into SLiM as the starting state for forward simulation; perhaps the evolutionary dynamics become non-neutral at that point in time, for example, due to a change in the environment, and so now one wishes to simulate those non-neutral dynamics in forward time. Since the coalescent is so fast, this can result in much quicker burn-in compared to simulating the burn-in with SLiM. You could then overlay neutral mutations after forward simulation is completed, as discussed above; this is a common strategy that moves between coalescent and forward simulation methods. Moving between methods in this manner allows the strengths of each method to be leveraged, while avoiding their weaknesses; “recapitation”, described below, is another such strategy. As mentioned above, the pyslim package is essential to this sort of interoperability, as we will see in chapter 17. Several ways of moving .trees data between SLiM and msprime using pyslim will be shown in chapter 17. The pyslim documentation has even more examples of such interoperability; for example, the vignette at https://tskit.dev/pyslim/docs/latest/vignette_coalescent_diversity.html shows how to generate a neutral burn-in with msprime, including overlaid neutral mutations, and import that whole burn-in into SLiM (as opposed to overlaying the neutral mutations after completing forward simulation, which is the more typical workflow); this can be useful if the forward simulation actually needs to use or modify mutations that come from the burn-in period.

This seems good to me; let me know if you have edits for it. Closing.

[bhaller]

Opened #262 on the side issue of modernizing the APIs used in all the tree-seq recipes.