Module _utils

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.

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*

: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 the most normal-looking
        phylogram, 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.

Example
-------

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

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.

Plot the given tree using matplotlib (or pylab).

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

: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.