ivy.vis package

Submodules

ivy.vis.alignment module

interactive viewers for trees, etc. using matplotlib

class ivy.vis.alignment.Alignment(fig, rect, *args, **kwargs)

Bases: matplotlib.axes._axes.Axes

matplotlib.axes.Axes subclass for rendering sequence alignments.

center_x(x, offset=0.3)

center_y(y)

extract_selected()

highlight_find(substr)

home()

plot_aln()

scroll(x, y)

select_rectangle(e0, e1)

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_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)

class ivy.vis.alignment.AlignmentFigure(aln, name=None, div=0.25, overview=True)

static axes_enter(e)

static axes_leave(e)

connect_events()

initialize_subplots(overview=False)

static onbuttonrelease(e)

static onclick(e)

static ondrag(e)

static onkeypress(e)

static onpick(e)

static onscroll(e)

static onselect(estart, estop)

selected

show()

zoom(factor=0.1)

Zoom both axes by factor (relative display size).

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

Bases: matplotlib.patches.Rectangle

ivy.vis.axes_utils module

ivy.vis.axes_utils.adjust_limits(axes)

ivy.vis.axes_utils.artist_data_extents(axes)

ivy.vis.axes_utils.iter_bboxes(axes)

ivy.vis.bokehtree module

Viewer for trees using Bokeh

class ivy.vis.bokehtree.BokehTree(root, scaled=True, nodelabels=True, tiplabels=True, showplot=True, hover=False)

Bases: object

connectors()

This method draws branches between nodes

drawlabels()

This method draws labels for tips and internal nodes

drawtree(showplot=True)

This method sets the output file and creates the figure

highlight(x=None, color=u'red', width=3)

Highlight selected clade(s)

Parameters:x –

A str or list of strs or node or list of nodes. color (str): The color of the highlighted nodes. Optional,

defaults to red

width (int): The width of the highlighted branches. Optional,

defaults to 3.

layout()

This method calculates the coordinates of the nodes

makehovertool()

set_root(root)

This method sets root, leaves, and nleaves. Detects if tree is scaled or not.

ivy.vis.colors module

ivy.vis.colors.tango()

ivy.vis.events module

Events for tree figures

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

Bases: matplotlib.patches.Rectangle

ivy.vis.events.axes_enter(e)

ivy.vis.events.axes_leave(e)

ivy.vis.events.connect_events(canvas)

ivy.vis.events.onbuttonrelease(e)

ivy.vis.events.onclick(e)

ivy.vis.events.ondrag(e)

ivy.vis.events.onkeypress(e)

ivy.vis.events.onpick(e)

ivy.vis.events.onscroll(e)

ivy.vis.events.onselect(estart, estop)

ivy.vis.hardcopy module

class ivy.vis.hardcopy.TreeFigure(root, relwidth=0.5, leafpad=1.5, name=None, support=70.0, scaled=True, mark_named=True, leaf_fontsize=10, branch_fontsize=10, branch_width=1, branch_color=u'black', highlight_support=True, branchlabels=True, leaflabels=True, layers=[], xoff=0, yoff=0, xlim=None, ylim=None, height=None, width=None, plottype=u'phylogram')

autoheight()

adjust figure height to show all leaf labels

detail

home()

render_multipage(outfile, pagesize=[8.5, 11.0], dims=None, border=0.393701, landscape=False)

Create a multi-page PDF document where the figure is cut into multiple pages. Used for printing large figures.

Parameters:

• outfile (string) – The path to the output file.
• pagesize (list) – Two floats. Page size of each individual page in inches. Defaults to 8.5 x 11.0.
• dims (list) – Two floats. The dimensions of the final figure in inches. Defaults to the original size of the figure.
• border (float) – The amount of overlap (in inches) between each page to make taping them together easier. Defaults to 0.393701 (1 cm)
• landscape (bool) – Whether or not each page will be in landscape orientation. Defaults to false.

savefig(fname, format=u'pdf')

set_relative_width(relwidth)

ivy.vis.layers module

Layer functions to add to a tree plot with the addlayer method

ivy.vis.layers.add_ancestor_noderecon(treeplot, internal_vals, vis=True, colors=None, nregime=None, size=8)

Add piecharts at each node based on probability vector

Parameters:internal_vals –

Array of dimensions [nchar+2, nnodes]. Identical to the

format returned by anc_recon_cat

colors: List of length = nchar. The colors for each character. Optional. nregime: Number of regimes. If given and colors = None, function will automatically color-code characters by regime. (NOT IMPLEMENTED)

ivy.vis.layers.add_ancrecon(treeplot, liks, vis=True, width=2)

Plot ancestor reconstruction for a binary mk model

ivy.vis.layers.add_ancrecon_hrm(treeplot, liks, vis=True, width=2)

Color branches on tree based on likelihood of being in a state based on ancestral state reconstruction of a two-character, two-regime hrm model.

ivy.vis.layers.add_branchstates(treeplot, vis=True, colors=None)

Add simulated branch states.

Treeplot must have simulated states as attributes

ivy.vis.layers.add_cbar(treeplot, nodes, vis=True, color=None, label=None, x=None, width=8, xoff=10, showlabel=True, mrca=True, leaf_valign=u'center', leaf_halign=u'left', leaf_fontsize=10, leaf_offset=4)

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
• x (float) – Distance from tip of tree to bar. Optional, if None, calculated based on leaf labels.
• 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

ivy.vis.layers.add_circles(treeplot, nodes, colors=u'g', size=15, xoff=0, yoff=0, vis=True)

Draw circles on plot at nodes

Parameters:

• nodes – A node object or list of Node objects or label or list of labels
• colors – Str or list of strs. Colors of the circles. Optional, defaults to ‘g’ (green)
• size (float) – Size of the circles. Optional, defaults to 15
• yoff (xoff,) – X and Y offset. Optional, defaults to 0.

ivy.vis.layers.add_circles_branches(treeplot, nodes, distances, colors=u'g', size=15, xoff=0, yoff=0, vis=True)

Draw circles on branches

Parameters:

• nodes – A node object or list of Node objects or label or list of labels
• distances – Float or list of floats indicating the distance from the parent node the branch should be drawn on.
• colors – Str or list of strs. Colors of the circles. Optional, defaults to ‘g’ (green)
• size (float) – Size of the circles. Optional, defaults to 15
• yoff (xoff,) – X and Y offset. Optional, defaults to 0.

ivy.vis.layers.add_highlight(treeplot, x=None, vis=True, width=5, color=u'red')

Highlight 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

ivy.vis.layers.add_hrm_hiddenstate_recon(treeplot, liks, nregime, vis=True, width=2, colors=None)

Color branches based on likelihood of being in hidden states.

Parameters:liks (np.array) – The output of anc_recon run as a hidden-rates reconstruction.

ivy.vis.layers.add_image(treeplot, x, imgfiles, maxdim=100, border=0, xoff=4, yoff=4, halign=0.0, valign=0.5, xycoords=u'data', boxcoords=u'offset points')

Add images to a plot at the given nodes.

Parameters:

• x – Node/label or list of nodes/labels.
• imgfiles – String or list of strings of image files

Note

x and imgfiles must be the same length

ivy.vis.layers.add_label(treeplot, labeltype, vis=True, leaf_offset=4, leaf_valign=u'center', leaf_halign=u'left', leaf_fontsize=10, branch_offset=-5, branch_valign=u'center', branch_halign=u'right', fontsize=u'10')

Add text labels to tree

Parameters:

• treeplot – treeplot (fig.tree)
• labeltype (str) – “leaf” or “branch”

ivy.vis.layers.add_legend(treeplot, colors, labels, shape=u'rectangle', loc=u'upper left', **kwargs)

Add legend mapping colors/shapes to labels

Parameters:

• colors (list) – List of colors
• labels (list) – List of labels
• shape (str) – Shape of label icon. Either rectangle or circle
• loc (str) – Location of label. Defaults to upper left

ivy.vis.layers.add_mkmr_heatmap(treeplot, locations, vis=True, seglen=0.02)

Heatmap that shows which portions of the tree are most likely to contain a switchpoint

To be used with the output from mk_multi_bayes.

Parameters:

• locations (list) – List of lists containing node and distance. The output from the switchpoint stochastic of mk_multi_bayes.
• seglen (float) – The size of segments to break the tree into. MUST BE the same as the seglen used in mk_multi_bayes.

ivy.vis.layers.add_node_heatmap(treeplot, nodelist, vis=True)

Plot circles on nodes with colors indicating how frequently each node appears in nodelist. For use with plotting potential regime shift locations

Parameters:nodelist (list) – list of node objects. Repeats allowed (and expected)

ivy.vis.layers.add_phylorate(treeplot, rates, nodeidx, vis=True)

Add phylorate plot generated from data analyzed with BAMM (http://bamm-project.org/introduction.html)

Parameters:

• rates (array) – Array of rates along branches created by r_funcs.phylorate
• nodeidx (array) – Array of node indices matching rates (also created by r_funcs.phylorate)

Warning

Ladderizing the tree can cause incorrect assignment of Ape node index numbers. To prevent this, call this function or root.ape_node_idx() before ladderizing the tree to assign correct Ape node index numbers.

ivy.vis.layers.add_pie(treeplot, node, values, colors=None, size=16, norm=True, xoff=0, yoff=0, halign=0.5, valign=0.5, xycoords=u'data', boxcoords=u'offset points', vis=True)

Draw a pie chart

Args: node (Node): A single Node object or node label values (list): A list of floats. colors (list): A list of strings to pull colors from. Optional. size (float): Diameter of the pie chart norm (bool): Whether or not to normalize the values so they

add up to 360

xoff, yoff (float): X and Y offset. Optional, defaults to 0 halign, valign (float): Horizontal and vertical alignment within

box. Optional, defaults to 0.5

ivy.vis.layers.add_squares(treeplot, nodes, colors=u'r', size=15, xoff=0, yoff=0, alpha=1.0, vis=True)

Draw a square at given node

Parameters:

• p – A node or list of nodes or string or list of strings
• colors – Str or list of strs. Colors of squares to be drawn. Optional, defaults to ‘r’ (red)
• size (float) – Size of the squares. Optional, defaults to 15
• yoff (xoff,) – Offset for x and y dimensions. Optional, defaults to 0.
• alpha (float) – between 0 and 1. Alpha transparency of squares. Optional, defaults to 1 (fully opaque)
• zorder (int) – The drawing order. Higher numbers appear on top of lower numbers. Optional, defaults to 1000.

ivy.vis.layers.add_text(treeplot, x, y, s, color=u'black', xoff=0, yoff=0, valign=u'center', halign=u'left', fontsize=10)

Add text to the plot.

Parameters:

• y (x,) – x and y coordinates to place the text
• s (str) – The text to write
• color (str) – The color of the text. Optional, defaults to “black”
• yoff (xoff,) – x and y offset
• valign (str) – Vertical alignment. Can be: ‘center’, ‘top’, ‘bottom’, or ‘baseline’. Defaults to ‘center’.
• halign (str) – Horizontal alignment. Can be: ‘center’, ‘right’, or ‘left’. Defaults to ‘left’
• fontsize (float) – Font size. Optional, defaults to 10

ivy.vis.layers.add_tipstates(treeplot, chars, nodes=None, colors=None, *args, **kwargs)

ivy.vis.layers.add_tree_heatmap(treeplot, locations, vis=True, color=(1, 0, 0))

Plot how often tree coordinates appear in locations

Parameters:locations (list) – List of tuples where first item is node, second item is how far from the node’s parent the location is.

ivy.vis.layers.color_blender_1(value, start, end)

Smooth transition between two values

value (float): Percentage along color map start: starting value of color map end: ending value of color map

ivy.vis.layers.color_map(value, col1, col2)

Return RGB for value based on minimum and maximum colors

ivy.vis.layers.colorbar_legend(ax, values, cmap, vis=True)

Add a vertical colorbar legend to a plot

ivy.vis.layers.gradient_segment_horz(p1, p2, c1, c2, width=4)

Create a horizontal segment that is filled with a gradient

Parameters:

• p1 (tuple) – XY coordinates of first point
• p2 (tuple) – XY coordinates of second point Y coord must be same as p1
• c1 (tuple) – RGB of color at point 1
• c2 (tuple) – RGB of color at point 2

Returns:

list of segs and colors to be added to a LineCollection

Return type:

list

ivy.vis.layers.twoS_colormaker(lik)

Given node likelihood, return approrpiate color

ivy.vis.layers.twoS_twoR_colormaker(lik)

Given node likelihood, return appropriate color

State 0 corresponds to red, state 1 corresponds to blue Regime 1 corresponds to grey, regime 2 corresponds to highly saturated

ivy.vis.layers.xy(plot, p)

Get xy coordinates of a node

Parameters:

• plot (TreeSubplot) – treeplot
• p – node or node label (or list of nodes/node labels)

ivy.vis.matplot module

ivy.vis.tree module

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

Module contents