[Biopython-dev] Enhancements to Phylo.draw; pyplot best practices

[Eric Talevich]

Hi all,

I'm considering some enhancements to the Phylo.draw function to make it
more customizable for power users. Since the function is based on
matplotlib/pylab/pyplot, it's possible for quite a bit to be left to the
user; however, I'm not fully versed in what pyplot is capable of.

Relevant feature request in Redmine:
https://redmine.open-bio.org/issues/3336

Ideas:

1. Make the draw function return a mapping of clades to a collection of
pyplot graphical elements -- the objects emitted by pyplot during each step
of rendering the plot. Each clade in the tree is mapped to a horizontal
line, a vertical line, a text label (taxon name, normally), and another
text label for the branch (confidence/support, normally). The user can then
set the attributes of these objects as they wish, minimizing the need for
futher extensions to Phylo.draw.

Example:
{<Bio.Phylo.PhyloXML.Clade>: {
        "hline": <matplotlib.collections.LineCollection>,
        "vline": <matplotlib.collections.LineCollection>,
        "taxon_label": <matplotlib.text.Text>,
        "branch_label": <matplotlib.text.Text> },
 ...

If the user needs access to the figure or axis object as well, it's already
easy enough to create these beforehand and pass the 'axis' object to
Phylo.draw.



2. Add an argument 'branch_labels' to Phylo.draw. This will accept either
(a) a dict which maps the tree's Clade objects to string labels, or (b) a
function which accepts a Clade object and returns a string. Default: a
function that formats the clade's 'confidence' or 'confidences' attribute,
matching the current behavior.

Examples:
>>> draw(mytree, branch_labels={mytree.root: "Root", ...})
>>> draw(mytree, branch_labels=lambda clade: "%d" % clade.confidence)
>>> draw(mytree, branch_labels=lambda clade: clade.taxonomy.rank)



3. Accept **kwargs in Phylo.draw; pass it right along to pyplot at some
point.

Question: What basic pyplot function accepts **Ikwargs? pyplot.figure and
pyplot.set_subplot don't seem appropriate. An alternative is to use
pyplot.rcParams, either leaving it all to the user or treating the **kwargs
keys as the corresponding entries in rcParams. Syntax gets a little tricky.

(Not a top priority for me, actually, since rcParams works.)



Thoughts? All clear?

Thanks,
Eric