Hi everyone. We have just released SLiM 3.3. This is a major release, including a couple of important bug fixes:
- The big new feature is that nucleotide-based models are now supported in SLiM. This means that the full nucleotide sequence for each genome can be tracked and output, with each segregating mutation involving an explicit nucleotide change. New mutations can occur at sequence-specific rates, following standard mutational models (Jukes-Cantor, Kimura 1980) or custom models, including dependence upon the trinucleotide context around a mutating site (allowing things like an elevated mutation rate at CpG sites). Fitness can depend upon the nucleotide sequence, or upon the resulting codon or amino-acid sequences (which can also be accessed in script). Gene conversion has been extended to a more biologically realistic model that can include GC-biased heteroduplex mismatch repair (see section 1.5.6 and recipe 18.11). Support for writing and reading nucleotide-based mutations with SLiM output files, .trees files, and VCF files has been added. A new manual section introduces the basic concepts of nucleotide-based models (section 1.8), and a new chapter has been added providing nucleotide-based recipes (chapter 18).
- The other big new feature is a new callback type, the mutation() callback. This allows you to examine, modify, or even veto proposed new mutations auto-generated by SLiM. You can easily add additional state to new mutations (using the tag property or setValue()/getValue()), or change the selection coefficient or mutation type of new mutations, or block particular new mutations from occurring at all. Several new recipes have been added to show the use of this feature, and section 24.8 provides reference documentation for this new callback type. Most users will probably never use this feature, however.
- Miscellaneous smaller features have also been added, including better support for reading and writing MS format files, improved control of auto-simplification in tree-sequence recording models, and some optimization work; see the change list in the manual (chapter 28) for details.
- The manual has received a thorough edit. A new chapter 13 provides a more organized treatment of QTL-based models, gathered in one place with a modernized treatment. Besides the new chapter 18 (nucleotide-based models), there are several other new recipes: 6.1.4 (simulating multiple chromosomes), 10.6 (varying dominance coefficients), 12.5 (tracking separate sexes in script), and 14.4 (tracking and visualizing ancestry and admixture with mutation() callbacks). Many typos were fixed, many fuzzy details clarified.
- A major bug was found and fixed: the mutationCounts() and mutationFrequencies() methods would return incorrect results if called in an early() event in a nonWF model. Results from any models hitting this specific case should be considered invalid. All other uses of these methods are believed to have provided correct results, so hopefully the impact of this bug is minimal.
- A major bug was found and fixed: the 0/1 calls in MS-format output (from outputMS() and outputMSSample()) were potentially incorrect if the filterMonomorphic flag passed to those methods was T. The default for that flag is F, so unless you explicitly specified filterMonomorphic=T you are fine, so again hopefully the impact of this bug is minimal.
- A major bug was found and fixed (thanks Graham Gower): calling max() with integer arguments, where at least one of those integer arguments is a singleton that is != 0 and != 1, would produce incorrect results. The bug is limited to this specific case; if you are calling max() with a non-singleton vector or vectors, you are fine. So again, hopefully minimal impact, but ugh. (If you're wondering how such a specific bug can even happen: integer singleton arguments were getting incorrectly coerced to type logical, due to a copy/paste bug, and this specific case was slipping past my unit tests.)
- A major bug was found and fixed: the function matrixMult() would produce incorrect results in some cases with operands of type float. Probably nobody is even using this function – no recipe uses it, and matrices in Eidos are a pretty new feature to begin with – but if you are using matrixMult() with type float, you should re-run.
- Various minor bugs were fixed that should not affect the correctness of simulations/output; see the change list (chapter 28), the VERSIONS file in the SLiM sources, or the GitHub commit record for details.
This upgrade is strongly recommended for all users, especially since it fixes the major bugs above. Note that I have been working to improve the Eidos and SLiM self-tests, which unearthed some of these issues; hopefully everything is solid now, but of course bugs happen. Apologies to anyone bitten by any of these bugs; but software is software, so always validate your results!
For those upgrading, note that the .trees file format has been changed; old .trees files can still be read, but new .trees files generated by SLiM 3.3 will require the latest pyslim version (just released) to work. Those using tree-sequence recording should update their Python msprime, tskit, kastore, and pyslim packages simultaneously with the upgrade to SLiM 3.3 to avoid version issues.
SLiM 3.3 will break backward reproducibility (i.e., the same model, with the same seed, will produce different results than SLiM 3.2.1) in some limited cases; contact me if you need details. SLiM 3.3 should be almost entirely backward compatible with SLiM 3.2.1, in the sense that changes to your model script should generally not be necessary; the exception is models that call initializeGeneConversion(), since the gene conversion model has fundamentally changed in SLiM 3.3 (see section 1.5.6). Models that used tag/tagF values incorrectly (accessing their values when those values were undefined) will now produce an error at runtime, but you shouldn't have been doing that anyway, and those new errors tell you that your model has a bug, so that's good.
You can obtain SLiM 3.3 from the SLiM home page at http://messerlab.org/slim/
; note that the manuals, recipes, and reference sheets have also undergone revisions.
If you have any questions, comments, etc., please use the slim-discuss group for that. Thanks, and happy modeling!
Benjamin C. Haller