[Biopython-dev] PhyloXML.BranchColor methods

[Eric Talevich]

On Wed, Apr 7, 2010 at 4:29 PM, Peter <biopython at maubp.freeserve.co.uk>wrote:

> On Wed, Apr 7, 2010 at 7:18 PM, Eric Talevich <eric.talevich at gmail.com>
> wrote:
> > Hi all,
> >
> > There's been some discussion in Bugzilla about using the
> > PhyloXML.BranchColor class to assign colors to Bio.Phylo tree
> > branches.
> > http://bugzilla.open-bio.org/show_bug.cgi?id=3047
> >
> > Currently, one sets the color for a clade by assigning a BranchColor
> > instance to the clade's color attribute:
> >
> > from Bio import Phylo
> > from Bio.Phylo import PhyloXML as PX
> >
> > tree = Phylo.read(..., 'phyloxml')
> > critters = tree.find(name='Rattus')
> > critters.color = PX.BranchColor(0, 128, 0)
> > # or, using HTML/matplotlib color names:
> > critters.color = PX.BranchColor.from_name('green')
> >
>



> > The BranchColor class has these methods:
> >
> >  from_name -- a class method that looks up RGB values in the
> > hard-coded dictionary BranchColor.color_names
>
> We could probably move the lookup table under Bio.Data,
> where it might also be useful for Bio.Graphics. I assume you
> are using standard HTML/CSS color names?
>

OK, that's cool too. I took the color names and values from the HTML
standard and W3Schools:
http://w3schools.com/html/html_colornames.asp

I checked the more exotic names with matplotlib and gcolor2 -- so any name
from this list will also work in matplotlib, and consequently,
draw_graphviz.


 > (See
> http://github.com/biopython/biopython/blob/master/Bio/Phylo/PhyloXML.py)
> >
> > Here are some proposals. Please let me know which of these you like or
> hate.
> >
> > 1. Add a function Bio.Phylo.PhyloXML.color(...) which behaves like the
> > clade.color property Peter suggested earlier:
>
> I was suggesting adding a property to the clade (which could for
> example map color names or RBG triples to the BranchColor
> objects automatically). It would still be:
>
> from Bio import Phylo
> from Bio.Phylo import PhyloXML as PX
> tree = Phylo.read(..., 'phyloxml')
> critters = tree.find(name='Rattus')
> critters.color = PX.BranchColor(0, 128, 0)
>
> BUT, you could choose to allow:
>
> critters.color = (0, 128, 0)
>
> Or a named color,
>
> critters.color = "green"
>
> Or a hex string.
>
> critters.color = "#008000"
>
> and have the property set method convert these into
> the same result, BranchColor(0, 128, 0).
>

It's pretty magical, but the convenience of "critters.color = 'green'" wins.
I'll implement the property to accept a BranchColor, RGB triple, color name,
or hex string, and raise a ValueError otherwise.



>  > 2. Add a class method from_hex_string for constructing BranchColor
> > objects from a hex string like '#FF00AA'
> >
> > This complements the to_hex function (to be renamed to_hex_string,
> > unless someone has a better name for it). The color function given
> > above assumes this method exists.
>
> Hmm, to_hex seems OK to me.
>

My only concern: the builtin hex() returns a string formatted a little
differently. Matching that format would be useless here, but I was worried
about people being confused. But if you're OK with to/from_hex, then I am
too.


 > 3. Drop the to_rgb method; it's confusing and floating-point
> > conversions lead to bugs.
>
> I had assumed to_rgb would give a tuple of ints in the range
> 0 to 255 (following HTML/CSS color conventions). That would
> avoid the rounding issue.
>

Strawmen:
- Should to_rgb be renamed to_tuple, then?
- if we defined BranchColor.__iter__ as "return (self.red, self.green,
self.blue)", then "tuple(clade.color)" would work
- if we defined BranchColor.__hex__, then similarly, "hex(clade.color)"
would work
- ... but those magic methods would hurt discoverability


 > 4. New __repr__ and __str__ methods:
> >
> >>>> critters.color
> > BranchColor(red=0, green=128, blue=0)
> >>>> print critters.color
> > (0, 128, 0)
>
> Personally I would like an HTML style output, hash then a six character
> hex number. Anyone planning to look at the XML should know these
> from HTML and CSS. However, I recognise this isn't universally
> understood.
>

I'm OK with that too. We could also do a reverse lookup in the color_names
table and return the color name instead if there's a match. That would cover
most users -- if you know RGB values, you can probably handle hex, and if
you just use color names instead then you'll get color names back.



>  > I'm don't think any of the other PhyloXML classes warrant a similar
> > treatment -- except possibly PhyloXML.Sequence, which can be built
> > from at SeqRecord using the from_seqrecord class method. Any other
> > suggestions along these lines?
>
> Colors are special enough to warrant special attention. Possibly also
> width would to.
>

Fortunately, width is just a float -- no PhyloXML-specific classes to deal
with.

Cheers,
Eric