Stdpopsim: Adding a new model docs

[agladstein]

Maybe this belongs in a section before Model review process, but there are no instructions on how to write a new model. I think that adding a new model is the most basic way that people will contribute, and I think the people contributing models will be more on the biology side of things than the programming side. So the instructions should be aimed at computational biologists, not programmers.

• What part of the code base does the new model go in?
• Is there a naming convention that should be followed?
• How do we specify what published model it is based on?
• What unit tests need to be included?
• What documentation needs to be included?
• other necessary instructions on how to write a new model?

sub-issue of #137

[agladstein]

more specifically,

• what convention is used for writing the doctstring

[jeromekelleher]

I think adding generic models is going to be rare and mostly people will be talking about specific models from the literature. We should probably just assume the documentation here is for concrete models, to keep the narrative simple.

[agladstein]

Yeah, I meant for the concrete models. But, now I see that those models aren't being documented with docstrings. All the more reason to add documentation on how to write documentation for those models.

[gtsambos]

On a related note -- are there other generic models that are important enough to consider here? I think that if we add in enough 'basic' models ourselves (and document them well!!!), that should suffice for users of this software.

Some particular improvements I can think of are:

1. A stepping-stone model.
2. The piecewise constant model but for growth rate changes
3. (Most useful) Allowing users to specify an arbitrary number of populations to these generic models

I have a few other API- and docs-related thoughts about these 'generic' models, so will put them in a separate issue

[jeromekelleher]

I think we should focus on the concrete species models for the initial release. There's a whole bunch of generic models we could implement, but, to be honest, these are already pretty easy in msprime, so we're not really adding that much value by putting them in here. It's the catalog of curated species population models that's the real feature here --- that is not easy to reproduce.

[agladstein]

Can someone work on this? I don't know the answers to my questions up there. Maybe @ndukler @apragsdale @jeromekelleher @andrewkern or someone else who has been involved in writing models?

[agladstein]

@ndukler still have this on your TODO list?
I do think this is vital section to have in the docs (before model review section).

[jeromekelleher]

See also #374

[petrelharp]

This would be nice to do before the paper comes out - even a sketchy version. Who knows how to do this - @ndukler? @ckyriazis? @grahamgower @apragsdale? @jradrion? Any volunteers?

[apragsdale]

I can pick this up over the next few days.

[agladstein]

And I can definitely review to see if it makes sense.

[agladstein]

I believe this can be closed now by the PR https://github.com/popsim-consortium/stdpopsim/pull/482

I'm going to try adding a new model according to these directions! So, I may also make a PR to edit the directions a bit or make an issue with some questions.