ivy.vis.treevis module

interactive viewers for trees, etc. using matplotlib

Re-written to have a layer-based API

class ivy.vis.treevis.MultiTreeFigure(trees=None, name=None, support=70, scaled=True, branchlabels=False, radial=False)

Bases: ivy.vis.treevis.TreeFigure

Class for drawing multiple trees in one figure

add(data, name=None, support=70, scaled=True, branchlabels=False, leaflabels=True, *args, **kwargs)

Add tree to existing figure

clear()

getplot(x)

home()

ladderize(reverse=False)

on_nodes_selected(treeplot)

picked(e)

redraw()

show()

class ivy.vis.treevis.OverviewTree(*args, **kwargs)

Bases: ivy.vis.treevis.Tree

add_overview_rect()

home()

rectselect(e0, e1)

Zoom to the selected region

redraw()

redraw_keeptemp()

set_target(target)

class ivy.vis.treevis.RadialTree(fig, rect, tf=None, *args, **kwargs)

Bases: ivy.vis.treevis.Tree

Matplotlib axes subclass for rendering radial trees

layout()

class ivy.vis.treevis.Tree(fig, rect, tf=None, *args, **kwargs)

Bases: matplotlib.axes._axes.Axes

Subclass for rendering trees

adjust_xspine()

center_node(node)

Center the canvas on the given node

center_x(x, offset=0.3)

Center the x-axis of the canvas on the given x value

center_y(y)

Center the y-axis of the canvas on the given y value

circle_selected_nodes(color=u'green')

clade_dimensions()

clade_height_pixels()

create_branch_artists()

Use MPL Paths to draw branches

draw_labels(*args)

find(s)

Find node(s) matching pattern s and zoom to node(s)

get_visible_nodes(labeled_only=False)

hardcopy(relwidth=0.5, leafpad=1.5)

home()

layout()

Get coordinates of nodes

leaf_pixelsep()

mark_named()

p2y()

Convert a single display point to y-units

picked(e)

plot_tree(root=None, **kwargs)

Draw branches

rectselect(e0, e1)

redraw(home=False, layout=True)

Replot the tree

scroll(x, y)

select_nodes(nodes=None, add=False)

set_name(name)

set_root(root)

set_scaled(scaled)

window2data(expandx=1.0, expandy=1.0)

return the data coordinates ((x0, y0),(x1, y1)) of the plot window, expanded by relative units of window size

xoffset()

Space below x axis to show tick labels.

ypp()

zoom(x=0.1, y=0.1, cx=None, cy=None)

Zoom the x and y axes in by the specified proportion of the current view.

zoom_clade(anc, border=1.2)

zoom_cxy(x=0.1, y=0.1, cx=None, cy=None)

Zoom the x and y axes in by the specified proportion of the current view, with a fixed data point (cx, cy)

zoom_nodes(nodes, border=1.2)

class ivy.vis.treevis.TreeFigure(data, name=None, scaled=True, div=0.25, branchlabels=True, leaflabels=True, xoff=0, yoff=0, mark_named=True, overview=True, interactive=True, radial=False, leaf_fontsize=10, branch_fontsize=10, direction=u'rightwards')

Bases: object

mpl Figure for plotting trees.

Holds references to all layers:

• Tree (the base layer: the Axes which all other layers are drawn on)
• Node labels
• Tip labels
• Overview
• Decorators
• Etc.

The navigation toolbar at the bottom is provided by matplotlib

(http://matplotlib.sf.net/users/navigation_toolbar.html). Its pan/zoom button and zoom-rectangle button provide different modes of mouse interaction with the figure. When neither of these buttons are checked, the default mouse bindings are as follows:

• button 1 drag: select nodes - retrieve by calling fig.selected
• button 3 drag: pan view
• scroll up/down: zoom in/out
• scroll up/down with Control key: zoom y-axis
• scroll up/down with Shift key: zoom x-axis
• scroll up/down with ‘d’ key: pan view up/down
• scroll up/down with ‘e’ key: pan view left/right
• click on overview will center the detail pane on that region

Default keybindings:

• t: zoom out to full extent
• +/-: zoom in/out

Useful attributes and methods (assume an instance named fig):

• fig.root - the root node (see [Node methods])
• fig.highlight(s) - highlight and trace nodes with substring s
• fig.zoom_clade(anc) - zoom to view node anc and all its descendants
• fig.toggle_overview() - toggle visibility of the overview pane
• fig.toggle_branchlabels() - ditto for branch labels
• fig.toggle_leaflabels() - ditto for leaf labels
• fig.decorate(func) - decorate the tree with a function (see decorating TreeFigures)

add_layer(func, *args, **kwargs)

Add a new layer. New layers include:

• Labels
• Overview
• Dataplot
• Decorations

Parameters:func (function) – Function that takes a TreePlot (self.tree) as input and returns (and draws) an Artist Keyword Arguments:  store (str) – Name of layer. If given, the layer is stored in self.layers and called upon every redraw

axes

cbar(nodes, *args, **kwargs)

Convenience function for adding clade bar along y axis

Draw a ‘clade’ bar (i.e., along the y-axis) indicating a clade. nodes are assumed to be one or more nodes in the tree. If just one, it should be the internal node representing the clade of interest; otherwise, the clade of interest is the most recent common ancestor of the specified nodes. label is an optional string to be drawn next to the bar, offset by the specified number of display units. If label is None then the clade’s label is used instead.

Parameters:

• nodes – Node or list of nodes or string or list of strings.
• color (str) – Color of the bar. Optional, defaults to None. If None, will cycle through a color palette
• label (str) – Optional label for bar. If None, the clade’s label is used instead. Defaults to None.
• width (float) – Width of bar
• xoff (float) – Offset from label to bar
• showlabel (bool) – Whether or not to draw the label
• mrca (bool) – Whether to draw the bar encompassing all descendants of the MRCA of nodes

find(x)

Find nodes

Parameters:x (str) – String to search Returns:A list of node objects found with the Node findall() method Return type:list

hardcopy(fname=None, relwidth=None, leafpad=1.5)

highlight(x, *args, **kwargs)

Convenience function for highlighting nodes

Parameters:

• x – Str or list of Strs or Node or list of Nodes
• width (float) – Width of highlighted lines. Defaults to 5
• color (str) – Color of highlighted lines. Defaults to red
• vis (bool) – Whether or not the object is visible. Defaults to true

home()

Return plot to initial size and location.

initialize_subplots(overview=True, leaf_fontsize=10, branch_fontsize=10)

Initialize treeplot (a matplotlib.axes.Axes) and add it to the figure. Also initialize overview. If overview=False, toggle off overview.

ladderize(rev=False)

Ladderize and redraw the tree

on_nodes_selected(treeplot)

picked(e)

redraw(keeptemp=False, *args, **kwargs)

Replot the figure and overview

remove_layer(layername)

Remove a layer by name.

Parameters:layername (str) – Name of the layer to remove. See all layers with self.layers

reorder_layers(neworder)

Reorder layers and redraw figure

Parameters:neworder (list) – New order of layers. Must include all layers currently in the figure. See all layers with fig.layers

select_nodes(nodes=None)

Select nodes on the plot

Parameters:nodes – A node or list of ndoes

Notes

If only one node is given, all of the node’s ancestors are also selected. If a list of nodes is given (even if it has only one node), only the given node(s) are selected.

selected

set_positions()

show()

Plot the figure in a new window

tipstates(chars, nodes=None, colors=None, *args, **kwargs)

Convenience function for drawing color-coded circles at tips indicating character states.

Parameters:

• chars (dict) –

  Dict mapping character states to tip labels. Character states should be coded 0,1,2...

  Can also be a list with tip states in preorder sequence

• nodes (list) – List of nodes or node labels. Optional, defaults to all tip labels in preorder sequence
• colors (list) – List of strs of the same length as the number of unique characters. Optional, defaults to tango colorscheme

toggle_branchlabels(val=None)

Toggle visibility of branchlabels (equivalent to toggle_layer(“branchlabels”))

toggle_layer(layername, val=None)

Set a layer to be visible/invisible (but still stored in self.layers)

Parameters:layername (str) – Name of the layer to toggle. See all layers with self.layers.

toggle_leaflabels(val=None)

Toggle visibility of leafabels (equivalent to self.toggle_layer(“leaflabels”))

toggle_overview(val=None)

Toggle overview

zoom(factor=0.1)

Zoom both axes by factor (relative display size).

zoom_clade(x)

Zoom to fit a node x and all its descendants in the view.

Parameters:x – Node or str that matches the label of a node

zx(factor=0.1)

Zoom x axis by factor.

zy(factor=0.1)

Zoom y axis by factor.

class ivy.vis.treevis.UpdatingRect(xy, width, height, angle=0.0, **kwargs)

Bases: matplotlib.patches.Rectangle