PLR edits through first half

[petrelharp]

This is a big edit. Besides generally trying to tighten up and clarify wording, the main thing I've tried to do is to emphasize the big things we did! lots more species!! gene conversion and nucleotides!!! This needs a bit more doing - for instance, we haven't said "the new release of stdpopsim", which this paper announces, anywhere.

I've got more edits for later on, but haven't typed them in yet.

Other notes:

• our citations seem a bit thin; I've added a few but there's lots more that could be done there.
• I'm not sure if "standardized" is quite the right word for the simulations we provide? So, I've reduced it's use. I think that 'standardized' implies that we've picked one option out of many equally good ones and want everyone to use the same (e.g.; I think that we do not want everyone to use the same thing, but rather we are making it easy to use particular options that are distinguished (due to having been estimated and published).

Here is a latexdiff of the edits, produced by doing latexdiff-git -r main adding_species_manuscript.tex and then rendering the resulting .tex file: adding_species_manuscript-diffmain.pdf

[petrelharp]

Hmph; I think I'm deleting too much stuff here.

[jeromekelleher]

I've had a read through the diff and I like it. I think it's still leaning towards the "here's stdpopsim, and by the way these are important things you should know about simulations" focus rather than alternative "Here are some important things about parameterising simulations, and this is how we've done it in stdpopsim", but I assume that's intentional?

[petrelharp]

Awesome, thanks. It's tricky, and I think I'm changing too much - really, I should have given high-level comments before jumping in to the edits; before merging I want to look at the diff to see what I've deleted that I can put back in. But, you're right, here's how I am framing this, in tihs priority order (what do you think?):

1. here's some updates to stdpopsim
2. here's some perspective about doing sims
3. here's how we do things in stdpopsim

The reason for this order is that (1) is the reason we're writing hte paper, and the biggest concrete takeaway for people, I think. It is cool that we have more species, and more functionality.

It helped me to remember the history of this paper: first we said "okay let's write a paper about the hackathon and telling everyone how to add their own new species"; but then we realized we didn't want everyone to add their own species, so there's been a somewhat awkward readjustment, with I think several different ideas of what the paper's supposed to be doing.

But - regardless of whether we want everyone to add their own species, it's still useful and cool that we have more species in the catalog, so that people can use stdpopsim for a wider range of taxa, for instance because we don't want all new methods to be tested only on humans + drosophila. So, it makes sense to report on and highlight it. (Plus, if we change the focus we need a new title! =) IMO it was much too far in the other direction: previously, it didn't even say in the text how many new species we'd added, when I think this needs to be in the abstract.

The other thing that I've run into (see slack discussion) is that we have to disentangle "general advice for doing sims" from "this is how we do it in stdpopsim" - in many places we are being way too prescriptive, sounding like everyone must do their sims just as we do in stdpopsim. But, it's just minor wording changes to shift this, and I'm working on that.

[petrelharp]

So - don't merge this yet, I'm going to push more edits and revisit the ones I did (today, hopefully, but this is taking a while).

[petrelharp]

OK, I'm done here. I've not touched the conclusions because I'd like to see if others are on the same page about the edits.

[petrelharp]

Here's a latexdiff to main. adding_species_manuscript-diffmain.pdf

[jeromekelleher]

Looks great @petrelharp, I really like the new focus and the narrative is much clearer. I can see a few places that could be tightened up a bit --- shall I make a follow-up editing pass or drop comments?

[petrelharp]

This is a question for @lauterbur or @igronau, I think.

[lauterbur]

@jeromekelleher To repeat here what I said in the Slack convo, I think it makes sense for you to take an editing pass now, and then I'll go through, and then @igronau after.

(And I realized after merging that I forgot to update the figure legend for the new figure. Rather than muddy things with another PR now, I'll just do that when I take my pass.)