Stdpopsim: Docs revamp: "Catalog" and "Tutorial" sections

[gtsambos]

I think these are the two sections that users will jump to to make a start on using stdpopsim, so it's particularly important that these sections are clear and well-structured. At present I think they're both a bit confusing:

1. It's not clear what 'Catalog' means, as @agladstein has noted in #148. Also, although there is some repeated structure to this section (Genome, Genetic Maps, Models), it's not obvious why these particular features are the things the user needs to choose. The stdpopsim ingredients that they correspond to have different names ('Genome' information is part of the Species object and 'Genetic Maps' are part of the the Contig object, right)? I have some specific suggestions for what to do about this that I'll put in #148.

2. The 'generic models' should all be included in a subsection of 'Catalog' as well -- at the moment, you can only see that these models exist in stdpopsim because of the API docs (and the single example in the 'Tutorials' section).

   1. The 'Tutorials' section should have some examples of different demographic models (generic and specific) and different species, to highlight the fact that there are different default parameter values in different models and species (BTW: I think this is going to be a big gotcha for users, and will mention in a separate issue somewhere). I think it would be good if the 'Tutorials' section was split into 'generic' and 'specific' subsections also.

I plan to get a start on all of these, but wanted to open up discussion here in case there's disagreement.

[gtsambos]

Another big picture thing that might be helpful to explain explicitly somewhere: the most flexible type of model that you can run are the 'generic models', right? In these simulations, you choose can choose species, chromosomes, recombination maps, population sizes, generation times, sample sizes and certain model-specific parameters (anything else? You can't choose mutation rates -- or am I wrong here??) Whereas in the manuscript-specific models, you can only choose the chromosome you are simulating, right?

[gtsambos]

(sub-issue of #137)

[jeromekelleher]

The 'generic models' should all be included in a subsection of 'Catalog' as well -- at the moment, you can only see that these models exist in stdpopsim because of the API docs (and the single example in the 'Tutorials' section).

I think we should keep these separate, and emphasise the functionality of simulating models from the Catalog (which most users will want, I think), which can be done via the CLI. Simulating "Generic" models is for advanced users, as they need to understand what these models mean and they need to use the Python API.

The users I have in mind here are those who know very little about popgen, who just want a somewhat realistic model of population structure to generate some data for them. They have never heard of an "IM" model, have no idea what Ne is, etc. These are the users we want to cater for first. We can have an "Advanced topics" bit somewhere showing people how to use the catalog to get values for instantiating an IM model, but we don't want to confuse the simple narrative of "we'll simulate realistic stuff for you, simply" with this level of detail.

The Catalog is for people like this: you just choose a species and few other things from the catalog, and stdpopsim does the rest for you.

[agladstein]

I agree wit @jeromekelleher here.
But, I do think this needs to be explained somewhere upfront in the docs.

[jeromekelleher]

I think this is done now @gtsambos?

[gtsambos]

All except this:

The 'generic models' should all be included in a subsection of 'Catalog' as well -- at the moment, you can only see that these models exist in stdpopsim because of the API docs (and the single example in the 'Tutorials' section).

But this is a more specific issue that can perhaps be handled on its own.

[jeromekelleher]

I disagree with including the Generic models in the catalog --- I think they are separate things. Genetic models are not "in" the catalog, because the catalog consists of species and published demographic models for them. The generics are only accessible through the Python API, so it's appropriate that they're only documented in the Python API.

It would also complicate the code for generating the catalog HTML.

[gtsambos]

Yes; perhaps I could have been a bit clearer given what I now know about the catalog. My broader point was that the generic models would ideally be documented somewhere on a page, so that users can see that they exist, see how they differ and understand that they are an option to be utilised. At present, I don't think it's obvious that users will know about them -- they will have to have stumbled on @agladstein's tutorial, or be hanging around the bottom of the API page.

[gtsambos]

Ie. they don't need to be in "the" model catalog, but they should be "catalogued" (catalogged?? 🤔 ) somewhere I think

[jeromekelleher]

Good point --- perhaps we should include a "list of models" index somewhere?

[gtsambos]

yes -- I'll try to do it quickly with the other little fix tomorrow. It'll probably be easiest to make a separate page that links from index.rst, but if this list of models fits naturally somewhere else, lmk and I can put it there. Given that there are only 2 generic models at the moment, it'll be a pretty small page.

[jeromekelleher]

We'd want to list all the species models too though, wouldn't we? We'd need another sphinx directive to do that though. This might be overboard.

How about we add a "Generic models" section to the end of the catalog page, and put a manual table in there linking to the generic models?

[gtsambos]

How about we add a "Generic models" section to the end of the catalog page, and put a manual table in there linking to the generic models?

Sounds good, I'll look into this. I don't think it's as important to list the species models because they're already documented in the catalog. The info I'd be adding would be the equivalent of this documentation for the generic models.

[agladstein]

hmm... I'm afraid having another list of models might be confusing with the Catalog that already exists. I want to see what @gtsambos comes up with, then I'll give some input on if it seems more confusing.
But, I do agree, without having it stated somewhere that there ARE generic models they can use, it might take some digging to discover that.