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 subtree 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
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 1.0.

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

source code 

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

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

Example:

>>> import pylab
>>> from Bio import Phylo
>>> tree = Phylo.read('ex/apaf.xml', 'phyloxml')
>>> Phylo.draw_graphviz(tree)
>>> pylab.show()
>>> pylab.savefig('apaf.png')

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

Parameters:
  • label_func - 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 - 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 the most normal-looking phylogram, but will cross and distort edges in larger graphs. (The programs 'circo' and 'fdp' are not recommended.)
  • args - String of 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 handle opened for writing the output drawing.
  • column_width - Total number of text columns used by the drawing.