Bug with mutation frequencies/counts in script

[Ben Haller]

Hi folks.  I've just found and fixed a significant bug, which I think merits an email to slim-discuss.  Please read on to understand whether you might be affected.

The bug has to do with mutation frequencies/counts calculated by SLiM.  Essentially, there were certain cases, described below, in which a previously calculated set of frequencies/counts would be cached and reused incorrectly; the cached values should have been thrown out, but were not.  As a result, incorrect mutation frequencies/counts could be returned to your script.

This affected ONLY the results from the SLiMSim methods mutationFrequencies() and mutationCounts().  It did not affect the Genome methods mutationCountsInGenomes() and mutationFrequenciesInGenomes().  It also did not affect the internal operation of SLiM; for the purposes that SLiM internally uses mutation frequency/count tallies (detecting mutation fixation and loss), the bug did not cause any incorrect behavior.  So if you do not call mutationFrequencies() or mutationCounts() in your script, you are fine.  (In some cases the frequencies shown in SLiMgui could be momentarily incorrect, but that had no consequence for the simulation itself.)

The bug would occur, sometimes, if frequencies/counts were requested after particular operations (and ONLY these operations, as far as I can tell): addSubpop() or addSubpopSplit() to add a new subpopulation, setSubpopulationSize(0) to remove a subpopulation in a WF model, removeSubpopulation() to remove a subpopulation in a nonWF model, or takeMigrants() to move individuals in a nonWF model.  If one of those calls was made and then frequencies/counts were requested afterwards, within one cycle of the generation cycle, the values returned could potentially be incorrect – essentially failing to account for the change in mutation frequencies caused by the call in question.  These were the only cases where the bug would manifest; so if you did not assess frequencies/counts immediately after performing one of those calls, you should be fine.  (Frequencies would be correct after a call to readFromPopulationFile(), so typical conditional sweep models that watch frequencies/counts and reload from a saved state should be unaffected by the bug.)

So the scope of the bug is pretty limited, and I would be surprised if this importantly affected anybody.  Nevertheless, it seemed worth alerting the list just in case.  The bug has been fixed, and the fix is now available in the `multispecies` branch of SLiM's GitHub repository (which will be SLiM 4 fairly soon).  You can wait for SLiM 4 to be released to get the fix, or you can build that branch from sources following the instructions in chapter 2 of the manual.

Note that changes on the `multispecies` branch, relative to SLiM 3.7.1, break backward reproducibility, so you will probably see the results of your simulations change; that does not, in itself, indicate that your model was affected by this bug.  Instead, if you want to test whether your model is affected by the bug, the best thing to do is, in SLiM 3.7.1, add a call to the Genome methods mutationCountsInGenomes() or mutationFrequenciesInGenomes() to get exactly the same frequency/count information that your model already gets from mutationFrequencies() or mutationCounts(), and cross-check that the results are identical.  Feel free to contact me (off-list) if you are unsure how to do this.

Sorry for the hiccup; every once in a while a bug does sneak through!  I always recommend that people look at their simulation results with a very critical eye, to spot discrepancies that might be due to a bug (in their code or in SLiM).  Also, you should always do what you can to validate your model by comparing it against analytical results, and/or against results from a different simulation approach.  Happy modeling!

Cheers,
-B.

Benjamin C. Haller
Messer Lab
Cornell University