"Wish list" for fwdpy11.selective_sweep function.

[molpopgen]

PR #828 is adding a new function, fwdpy11.selective_sweep. I'm opening the floor here to discuss what features interested parties would like it to have. In the long run, we have to balance API simplicity with generality, but we can definitely discuss options right now.

There's no timeline in mind for merging #828. There are issues related to "unwinding" data structures when mutations are lost, and so a lot of testing will be needed prior to a merge.

cc @apragsdale @sgravel @BCFZzw

[apragsdale]

I can imagine wanting to be able to keep a simulation where the simulation length has finished but the mutation is still segregating, so that it's incomplete in the sample. Perhaps criteria for a minimum frequency of the selected mutation (in a given deme) at the end of the simulation?

Otherwise, flexibility in checking which demes the mutation is fixed in (or meets whatever stopping/restarting criteria) in multipopulation settings would be very nice.

[molpopgen]

So, there's a prototype in place for monitoring fixation in a focal deme, and it seems to be working. The minimum frequency idea is a good one, and gets at the more general question of what to do when the sweeping variant's origin time is close to the end of the simulation. Right now, a variant that is still segregating, but not fixed, gets rejected and we try again.

[sgravel]

Personally, I would say keep the simulation running unless the mutation has disappeared. I don't see a good reason to impose that a sweep is complete. I do want to avoid the situation where the beneficial mutation appears and then is immediately lost, but that does not require imposing fixation.

[molpopgen]

One way to handle this is to add an option: allow_partial_sweep: bool = False. That may not be the best name--allow_segregating may be more accurate.

[sgravel]

Oh, I see the source of my confusion. In our case, we are conditioning on a beneficial mutation having occurred at time T, and are happy as long as the mutation does not get lost. In the majority of cases where there is not complete isolation between populations, mutations that do not get lost will eventually sweep, and it is easy to ascertain at the end of the simulation.

I gather that you are considering a user that wants to condition on the mutation having occurred at time T1 and completed sweeping by time T2? In that case, I expect that different users will have different preferences.

Can't the question of incomplete sweeps at the end of the simulation be left at the discretion of the user? If you have gone through the trouble of simulating the trees up to the end, why not just record the simulation results and let the user filter post-hoc as they want?

[molpopgen]

Yeah, that's roughly what I have in mind. Right now:

• The mutation arises at time t during the course of some demographic model.
• We simulate until the mutation is fixed, is lost, or we reach the end of the demographic model.
• If the mutation is lost, or we reached the end of the model w/o fixation, we try again.

(If a mutation is fixed, and the demographic model is not complete, the code the simulates it the rest of the way. Doing this allows for "ancestral" sweeps.)

The behavior of the last bullet point can be amended in many ways (none of which are implemented, but are easy-ish to do):

• Allow the mutation to remain segregating at any frequency. "Any" can be further refined: globally, or in some "focal" deme of interest.
• Require the mutation to by at any frequency >= x. Again, "any" can be global or within some focal deme.

If either of those 2 are met, we run the "try again" code, thus leaving the possibility of it remaining segregating at the end of the model up to the user (by specifying the right arguments to the function).

I've avoided having an origin time and a T2 for now, because the goal is to facilitate sweep simulations. But, more generally, these ideas apply to a concept of "monitor a mutation for a while".

[sgravel]

Got it. The default behaviour I would personally prefer would be to only restart automatically if there is loss of the variant. I feel like other restart conditions based on frequency or fixation will be rather user- and model-specific. If you want the restart feature built-in to fwdpy11.selective_sweep, maybe have a "restart_function" argument that can accommodate default values (None, "low_frequency", "not_fixed") or a Boolean function to allow the user to define their preferred restart criterion? Maybe overkill. You would also probably need a "restart arguments" to pass allele frequencies, position to test, or similar information.

[molpopgen]

The initial frequency, position, etc., Is specified by the user already. It must not be a neutral mutation. So restarting means trying again with that same mutation.

It may be that a better design is to rename the function and have options that allow fixation/minimum frequency to be enforced. Or, have a sweep function wrap such a function.

[molpopgen]

Quick follow up: I've made a lot of progress over in #828. I've run into a couple tricky issues, as this feature is bringing some undocumented options into heavier use, meaning I'm finding some bugs in these murkier corners.

[molpopgen]

@sgravel, @apragsdale, @BCFZzw -- I just release 0.17.0 alpha 0, which has the draft of this new API. Please give it a spin and leave comments in #854.

[molpopgen]

PS, I am hoping that binary wheels will be ready "within the hour". Given that this is a pre-release, it will not go to conda, so installing will require python -m pip install --upgrade --pre fwdpy11.