bhaller
commented
2 years ago Hey. Catching up on things. First of all, in reading your doc I realized that the doc for SLiM 4 had not been updated correctly to reflect the new policy (which you state correctly in what you wrote) that the defaunt time unit is now "ticks" in all cases. I've just rewritten the doc as follows:
The timeUnit parameter controls the time unit stated in the tree sequence when it is saved (which can be accessed through tskit APIs); it has no effect on the running simulation whatsoever. The default value, NULL, means that a time unit of "ticks" will be used for all model types. (In SLiM 3.7 / 3.7.1, NULL implied a time unit of "generations" for WF models, but "ticks" for nonWF models; given the new multispecies timescale parameters in SLiM 4, a default of "ticks" makes sense in all cases since now even in WF models one tick might not equal one biological generation.) It may be helpful to set timeUnit to "generations" explicitly when modeling non-overlapping generations in which one tick equals one generation, to tell tskit that the time unit does in fact represent biological generations; doing so may avoid warnings from tskit or msprime regarding the time unit, in cases such as recapitation where the simulation timescale is important.
I'll probably rip a new PDF of the manual to reflect this change. But anyhow, you write that it is always "ticks" so this is just a doc problem on my end, and I don't think affects anything you have done/written.
Edits:
-
reword "one spin around SLiM’s life cycle corresponds to" to "corresponds to one spin around SLiM’s life cycle" to make it less confusing :->
-
"and you want to put neutral mutations with msprime" – "put in", or I like "overlay"
-
"we need to divide the coalescence rate by T ," – there seems to be a space after T and before the comma, the line breaks before the comma
-
"and so rate of r Morgans" – "a rate of"
-
"Since msprime (by default) runs a continuous-time simulation, there is no harm in adjusting time units in msprime this way, but it is confusing." – so, is there a way to make all this less confusing? Can the user rescale the time used by their tree sequence, in Python, so that then they can do mutation overlay, recapitation, etc., without having these confusing timescale issues because their tree sequence is now in whatever time unit is "natural" for tskit? That seems like it would be the best; maybe that's a feature request for tskit, or for pyslim? Basically a "rescale to units of generations" call, which would be passed a rescaling factor T, and would both rescale all times in the tree sequence, and change the time unit to "generations".
-
"The definition depends on what we mean by the various “average”s, but this is not the place to explain the distinctions." Hmm – maybe it is, actually? I mean, if not here, where? This kind of leaves the reader wondering what they're missing, and worried that their lack of understanding of this might mean that they're doing something wrong in their analysis.
-
"then to take the average across all individuals alive at a given time of the age..." – would be easier to parse with commas: "then to take the average, across all individuals alive at a given time, of the age..."
-
"assign to each individual a tag that records the average age of their parents" – hmm, interesting script. I was expecting you to do this analysis on the Python side, but I guess once simplification happens there's not enough information left in the tree sequence to determine parental ages at birth. So you have to do it in SLiM, hmm. Should this be something that SLiM tracks automatically, as it now tracks lifetime reproductive output automatically? I guess when doing these timescale adjustments and so forth, this is something that it will be very common for users to need to figure out; so maybe built-in support would be useful, especially since many models will already be using
tagfor other purposes, making your recipe difficult to adapt. I think the memory/time overhead of adding automatic tracking of this – maybe not as the mean of the parental ages, but instead as the age of each parent separately – would be pretty inconsequential. -
"measures the number of time steps (“tick”) since" – should be plural, "ticks"
-
"it is “first → “early → birth → late”, while in a nonWF model, it is “first → “birth → early → late”" – I'd get rid of the quotes around these (the italics makes them easy to visually separate anyway); in any case, note that there is an extra quote before "early" in both sequences
-
"Usually, the first set of individuals are created in the early() phase of tick 1" – I'm not sure I'd say this is "usual". Creating the initial subpop in late() is also quite common. "Often" would be better.
-
"As the simulation goes along, tskit time ago is recorded as minus one times the number of birth phases so far" – I'd add " – multiplied by minus one because the simulation is, in fact, going forward in time, which is a negative number of time-ago units" or some such.
-
"but in a WF they are not" – "WF model"
-
"To see the nonWF model" – "nonWF model schematic"
-
"birth happens between the “early()” and “late()” stages" – I would get rid of the quotes around these, here and elsewhere; unnecessary and just makes it harder to read
-
"The stage that the tree sequence was saved is recorded" – "The stage in which the tree sequence was saved is recorded"
-
"(This means you must specify the stage of the block in your SLiM script, since the stage defaults to “early()”!)" – happily, this default to early() is now gone, so you can delete this sentence.
-
Maybe it can somehow be made more clear, witha bounding box that is drawn connected to the tabs, or "blockquote" indentation, or something, that the tabs only switch out the table itself, and not the text below? I read the content for the WF tab, and then when I switched to the nonWF tab I expected the text below the table to change to talk about nonWF stuff; in particular, I expected the sentence "However, in WF models, birth happens between the “early()” and “late()” stages..." to go away, since I was now reading about nonWF models. I was initially confused that that text did not change to match my tab choice above. Not sure what the right fix is, with what you are able to do in the styling supported by whatever doc tools you're using...
Overall, LGTM! Whew!
But I think this review was very helpful for leading to the two ideas above: that SLiM could keep track of parent ages, and that there could be an easy way to rescale a given tree sequence from ticks to generations, given a biological generation time (perhaps automatically derived from SLiM's proposed automatic recording of parent ages!) as a scaling factor. I think if we do those two thing this whole story becomes much, much simpler for users.
I also think that a pass over the SLiM manual's chapter 17, with an eye towards adding mention of this and other real-world issues, and adding cross-links into the pyslim documentation, would be a Very Good Idea. I would suggest that you and I ought to do this kind of separately-but-together: do it one subsection at a time, reading and thinking separately and then having a shared-screen discussion and revision of the manual for that one subsection, then moving on to the next. If we do one subsection at a time, we can spread this work over a longer period of time and make the project less monolithic. It feels important to do, though; SLiM users need to know about these sorts of issues, and need to go to the pyslim doc to read about them, and the existing general statement to "Go read the pyslim doc, it's important" is presumably ignored/forgotten by most users.
petrelharp
You can read the new section I wrote at https://tskit.dev/pyslim/docs/latest/time_units.html
The last section ("Converting to SLiM time and back") is not new (although I made edits); however, the stuff before that is new and should have a wide-ish audience. It'd be nice if someone had a read of it to see if you agree and if it makes sense. @bhaller?