model figures in catalog docs

[agladstein]

In the model docs, it would be nice to include figures of the models so it is easier to understand what they are doing. Could be as easy as taking from the original papers and citing.

sub-issue of #137

[jeromekelleher]

This is tricky --- there are copyright issues. We can't just copy the figure if it's not CC-BY (or whatever). I think a link is the best we can do --- it's too much to expect people to craft figures explaining the models for each model.

[agladstein]

Ah okay.
When msprime has the awesome plotting demography function I've been dreaming about, then we could add that.

[gtsambos]

I'm happy to use my tikz skillz to make some in-house plots of the existing models if you'd like? (A la the one in panel 3 of this poster )

Shouldn't take me too long, esp if I do them all at once, and tbh I find it sortof calming and therapeutic

[jeromekelleher]

On the one hand it would be fantastic to have these @gtsambos, but it's a lot of work to be taking on! Plus, we need to think about the longer term sustainability here. Suppose we have a hundred simulation models --- are we going to have diagrams for them all?

I think it's reasonable to point people back to the original publication here: most users won't care about the fine-grained details of the model, and those who do should go back to the original publication I think.

[agladstein]

Yeah... I think if we had model diagrams, it's best to have an automated way of making them. Or else, you require the submitter of a new model to include a diagram?

On the other hand, I think the best way to understand what the model is, is to see a diagram of it. This is especially the case if target users are people who don't necessarily know model-specific terms, in which case it can be hard to describe what the model is with written words.
Although, I also don't think it is too much of an ask to have people look back at the original.

[apragsdale]

The drawing of arbitrary models is something I've been working on, included in a python program to define models over graphs that automatically parses msprime, dadi, moments simulation inputs, which I described in #136. That code lives on my own github, though I haven't pushed the plotting feature or documentation yet (working on it today and this week). I think this would be useful here, and hopefully save the work of manually drawing each model. The plotting bit of that package should be up and running in a few days.

[gtsambos]

looking forward to seeing it @apragsdale! That does sound like the best solution.

[jeromekelleher]

That sounds great @apragsdale --- once your package is ready for use, let's pick this up again.

[apragsdale]

So at the moment, I think the package is more or less functional (it's here: https://github.com/apragsdale/demography). There are a number of issues on my to do list, both for plotting and implementation of certain details of model specification, but for basic use it is working and decently tested.

Essentially demographies are encoded as graphs, which are then automatically parsed. The package acts as a wrapper to output msprime simulation inputs or run simulations to get tree sequences, compute the frequency spectrum using dadi or moments, or compute multi-population LD statistics using moments. It also can plot the demography, either as a simple graph with arrows indicating relationships between populations, or as an illustration with size changes, migration rates, and pulse admixture events. (see attached)

There are some examples in the examples directory there, including scripts to make these plots I attached here.

LMK what you all think - I think this will be useful for plotting models here, but also you might find it useful for your own projects simulating and refitting models.

ooa.pdf
ooa_archaic_model.pdf

[ndukler]

These plots look awesome!

[agladstein]

I love it!!!!!

[andrewkern]

these are super cool @apragsdale!

[gtsambos]

Very cool 😎

[apragsdale]

For the catalog documentation, I'll go through each model and implement them in this graphical framework and generate figures for each. It will be pretty quick to get them all together. Once I have put some of them together, it would be useful to get some feedback if they need to be tweaked at all, and we can get them into the docs?

[agladstein]

Sounds good.
Were you planning to include the code to generate the figs in this repo?

[apragsdale]

Yeah, I'm happy to. It will use the package I linked to, but I'll share the model and plotting scripts I used for the plots.

[jeromekelleher]

Thanks @apragsdale, this is excellent.

[apragsdale]

Ok - I've got a bunch of the multi-population models scripted up and plotted. They are all here: https://github.com/apragsdale/demography/tree/master/examples/figures. The scripts for the different species models are all in the examples directory there, and plots were output using plot_models.py.

Some look a bit better than others. For example, in the Browning model the admixture occurs just 12 generations ago, and those events get squashed down if plotted on a linear scale. Otherwise, I think they look not too bad, at least for a first pass.

[jeromekelleher]

These are superb @apragsdale --- let's talk about how we can bring them in on the next call.

[apragsdale]

Perfect, sounds good to me. :)

[jeromekelleher]

On the call 17/03 we discussed adding these to the Wiki (#415)

[grahamgower]

After we convert to Demes YAML files (#962), we can add figures to the docs with demesdraw.

[petrelharp]

These are in! I'm going to close this.