[Drawing] Add a TreeSequence.draw() method?

[jeromekelleher]

trafficstars

We're getting some very powerful tools with the new draw_svg() functions, but we're missing a simple way to annotate a tree sequence (like say, node colours) without having to be an SVG/CSS guru.

What if we add a .draw() method to TreeSequence that mirrors the API of Tree.draw()?

I would say we keep most options, except format. Then, the advice is

• Use draw_text if you want to draw text.
• Use draw if you want SVG output to have quick styling, with some simple options.
• Use draw_svg if you want SVG output with full control

We could then deprecate format="unicode" in Tree.draw()?

[jeromekelleher]

This would be very handy in the msprime tutorial, for example, where we want to show tree sequences with node colours corresponding to different populations.

[hyanwong]

The other option, since the params to draw_svg are all keyword-only, is to add the extra simple options to draw_svg. The advantage is only a single function to remember, and more complex options can be used to override the simple ones. The disadvantage is that we start inflating the number of params in draw_svg, which could easily become unwieldy.

[hyanwong]

With my suggestion in https://github.com/tskit-dev/tskit/pull/587#issuecomment-625742648 , colouring nodes by population would simply be a case of applying a particular style sheet. In fact, there's no reason not to have some sensible defaults in the standard style sheet so that nodes from different populations always appear in different predefined colours. Or the "simple" version would just give the option to switch between a set of different pre-defined style sheets.

[jeromekelleher]

These are great ideas @hyanwong, but I think we should keep the focus of draw_svg clear, and not muddy it with extra jobs to do. It'll be a very complicated function anyway.

Since we've already got a Tree.draw() function, and we're committed to supporting it (we have to, it's used in loads of places and in print now), I don't think there's any real cost to providing a similar TreeSequence.draw() function.

[hyanwong]

Just returning to this, as I'm sketching out the viz tutorial. One (simple) possibility is that TreeSequence.draw() differs only from TreeSequence.draw_svg() in the stylesheet that it uses. We can define a more complex stylesheet that pre-defines the a set of node colours (or perhaps a palette) for each of the populations in the tree sequence.

I think if possible it would be better to encode formatting changes via css (even if this is done automatically) than by hard coding parameters such as node colour into the drawing code itself.

Either way, it would be useful to sketch out what a simple TreeSequence.draw() command would produce, and what is user-configurable. For instance, could a user specify which colours are used for each population, or would that require using the full draw_svg() function. Should there be the ability to specify x-limits (I would say "yes") or axis labels (no?)? Should the time axis be shown, and if so, what should the tickmarks be? etc etc. Perhaps @benjeffery would like to weigh in as an independent observer?

[benjeffery]

I'm still not sure about having draw and draw_svg. It feels like this is confusing as the difference isn't clear from the names. But I agree that if we can do all we want via styling then that's great, but I think the API needs thought - maybe a helper function that creates styles?

[hyanwong]

A helper function for population colours might be good. @gtsambos flagged this up recently, and perhaps has ideas of what would be most intuitive? I don't know if that would extend to something that produced a legend too, although I'm not sure we want to go down the route of becoming a fully-fledged plotting package! Perhaps that could be farmed out to a function in tsviz?