Package Bio :: Package Phylo :: Module _utils
[hide private]
[frames] | no frames]

Module _utils

source code

Utilities for handling, displaying and exporting Phylo trees.

Third-party libraries are loaded when the corresponding function is called.

Functions [hide private]
 
to_networkx(tree)
Convert a Tree object to a networkx graph.
source code
 
draw_graphviz(tree, label_func=<type 'str'>, prog='twopi', args='', node_color='#c0deff', **kwargs)
Display a tree or clade as a graph, using the graphviz engine.
source code
 
draw_ascii(tree, file=sys.stdout, column_width=80)
Draw an ascii-art phylogram of the given tree.
source code
 
draw(tree, label_func=<type 'str'>, do_show=True, show_confidence=True, axes=None, branch_labels=None, *args, **kwargs)
Plot the given tree using matplotlib (or pylab).
source code
Variables [hide private]
  __package__ = 'Bio.Phylo'
Function Details [hide private]

to_networkx(tree)

source code 

Convert a Tree object to a networkx graph.

The result is useful for graph-oriented analysis, and also interactive plotting with pylab, matplotlib or pygraphviz, though the resulting diagram is usually not ideal for displaying a phylogeny.

Requires NetworkX version 0.99 or later.

draw_graphviz(tree, label_func=<type 'str'>, prog='twopi', args='', node_color='#c0deff', **kwargs)

source code 

Display a tree or clade as a graph, using the graphviz engine.

Requires NetworkX, matplotlib, Graphviz and either PyGraphviz or pydot.

The third and fourth parameters apply to Graphviz, and the remaining arbitrary keyword arguments are passed directly to networkx.draw(), which in turn mostly wraps matplotlib/pylab. See the documentation for Graphviz and networkx for detailed explanations.

The NetworkX/matplotlib parameters are described in the docstrings for networkx.draw() and pylab.scatter(), but the most reasonable options to try are: alpha, node_color, node_size, node_shape, edge_color, style, font_size, font_color, font_weight, font_family

Example

>>> import pylab
>>> from Bio import Phylo
>>> tree = Phylo.read('ex/apaf.xml', 'phyloxml')
>>> Phylo.draw_graphviz(tree)
>>> pylab.show()
>>> pylab.savefig('apaf.png')
Parameters:
  • label_func (callable) - A function to extract a label from a node. By default this is str(), but you can use a different function to select another string associated with each node. If this function returns None for a node, no label will be shown for that node.

    The label will also be silently skipped if the throws an exception related to ordinary attribute access (LookupError, AttributeError, ValueError); all other exception types will still be raised. This means you can use a lambda expression that simply attempts to look up the desired value without checking if the intermediate attributes are available:

    >>> Phylo.draw_graphviz(tree, lambda n: n.taxonomies[0].code)
  • prog (string) - The Graphviz program to use when rendering the graph. 'twopi' behaves the best for large graphs, reliably avoiding crossing edges, but for moderate graphs 'neato' looks a bit nicer. For small directed graphs, 'dot' may produce a normal-looking cladogram, but will cross and distort edges in larger graphs. (The programs 'circo' and 'fdp' are not recommended.)
  • args (string) - Options passed to the external graphviz program. Normally not needed, but offered here for completeness.

draw_ascii(tree, file=sys.stdout, column_width=80)

source code 

Draw an ascii-art phylogram of the given tree.

The printed result looks like:

                                _________ Orange
                 ______________|
                |              |______________ Tangerine
  ______________|
 |              |          _________________________ Grapefruit
_|              |_________|
 |                        |______________ Pummelo
 |
 |__________________________________ Apple
Parameters:
  • file (file-like object) - File handle opened for writing the output drawing.
  • column_width (int) - Total number of text columns used by the drawing.

draw(tree, label_func=<type 'str'>, do_show=True, show_confidence=True, axes=None, branch_labels=None, *args, **kwargs)

source code 

Plot the given tree using matplotlib (or pylab).

The graphic is a rooted tree, drawn with roughly the same algorithm as draw_ascii.

Additional keyword arguments passed into this function are used as pyplot options. The input format should be in the form of: pyplot_option_name=(tuple), pyplot_option_name=(tuple, dict), or pyplot_option_name=(dict).

Example using the pyplot options 'axhspan' and 'axvline':

>>> Phylo.draw(tree, axhspan=((0.25, 7.75), {'facecolor':'0.5'}),
...     axvline={'x':'0', 'ymin':'0', 'ymax':'1'})

Visual aspects of the plot can also be modified using pyplot's own functions and objects (via pylab or matplotlib). In particular, the pyplot.rcParams object can be used to scale the font size (rcParams["font.size"]) and line width (rcParams["lines.linewidth"]).

Parameters:
  • label_func (callable) - A function to extract a label from a node. By default this is str(), but you can use a different function to select another string associated with each node. If this function returns None for a node, no label will be shown for that node.
  • do_show (bool) - Whether to show() the plot automatically.
  • show_confidence (bool) - Whether to display confidence values, if present on the tree.
  • axes (matplotlib/pylab axes) - If a valid matplotlib.axes.Axes instance, the phylogram is plotted in that Axes. By default (None), a new figure is created.
  • branch_labels (dict or callable) - A mapping of each clade to the label that will be shown along the branch leading to it. By default this is the confidence value(s) of the clade, taken from the confidence attribute, and can be easily toggled off with this function's show_confidence option. But if you would like to alter the formatting of confidence values, or label the branches with something other than confidence, then use this option.