toytree drawings options¶

The number of styling options available in toytree is enormous and will continue to grow as development on the project continues. If you have a specific styling option that does not appear to be supported please raise a issue on GitHub and we can discuss adding support for it. Below I try to demonstrate the options and usage of each styling option with at least one example.

In [6]:

import toytree
import toyplot
import numpy as np

# a tree to use for examples
url = "https://eaton-lab.org/data/Cyathophora.tre"
rtre = toytree.tree(url).root("~prz") # rooted on outgroup clade

import toytree import toyplot import numpy as np # a tree to use for examples url = "https://eaton-lab.org/data/Cyathophora.tre" rtre = toytree.tree(url).root("~prz") # rooted on outgroup clade

Tip label styling¶

tip_labels¶

Type: boolean or list[str]
Allowed: True, False, or list of str names (length ntips)
Default: True
Description: Shows or hides tip labels (boolean), or replaces tip labels with a user defined list.

In [7]:

# hide tip labels
rtre.draw(tip_labels=False);

# hide tip labels rtre.draw(tip_labels=False);

In [8]:

# get tip labels from tree
tipnames = rtre.get_tip_labels()

# modify list so that names have a "-0" at the end
italicnames = [f"{i}-0".format(i) for i in tipnames]

# enter the list of names to tip_labels (in idx order)
rtre.draw(tip_labels=italicnames);

# get tip labels from tree tipnames = rtre.get_tip_labels() # modify list so that names have a "-0" at the end italicnames = [f"{i}-0".format(i) for i in tipnames] # enter the list of names to tip_labels (in idx order) rtre.draw(tip_labels=italicnames);

tip_labels_align¶

Type: boolean
Allowed: True, False
Default: False
Description: Add lines connecting tips to tip labels. See edge_align_style for ways to style the extra tip lines (colors, etc.).

In [9]:

rtre.draw(tip_labels_align=True);

rtre.draw(tip_labels_align=True);

tip_labels_colors¶

Apply a single color to all tip labels, or different colors to each.

Type: str, list[str], tuple[str, Colormap]
Allowed: Any color argument supported in toyplot colors.
Default: "#262626" (near black)
Description: A single color can be entered to apply to all tip labels, or a list of colors can be entered in idx order to apply different colors to each tip. The special tuple syntax can be used to map colors to feature data extracted from a tree.

In [31]:

# use color from favored toytree color scheme
rtre.draw(
    tip_labels_align=True, 
    tip_labels_colors="orange",
);

# enter a list of colors by name
rtre.draw(
    tip_labels_align=True, 
    tip_labels_colors=(['goldenrod'] * 11) + (["mediumseagreen"] * 2),
);

# make list of hex color values based on tip labels
colorlist = ["#d6557c" if "rex" in tip else "#5384a3" for tip in rtre.get_tip_labels()]
rtre.draw(
    tip_labels_align=True, 
    tip_labels_colors=colorlist
);

# use "tuple format" to colomap a tree data feature
rtre.draw(
    tip_labels_align=True, 
    tip_labels_colors=("idx", "Spectral"),
);

# use color from favored toytree color scheme rtre.draw( tip_labels_align=True, tip_labels_colors="orange", ); # enter a list of colors by name rtre.draw( tip_labels_align=True, tip_labels_colors=(['goldenrod'] * 11) + (["mediumseagreen"] * 2), ); # make list of hex color values based on tip labels colorlist = ["#d6557c" if "rex" in tip else "#5384a3" for tip in rtre.get_tip_labels()] rtre.draw( tip_labels_align=True, tip_labels_colors=colorlist ); # use "tuple format" to colomap a tree data feature rtre.draw( tip_labels_align=True, tip_labels_colors=("idx", "Spectral"), );

tip_labels_style¶

The tip_labels_style dictionary is used to apply CSS styling to all tip labels. Note: fill color arguments here can be overriden by tip_colors.

Type: dictionary of (mostly) CSS styles.
Allowed: See the dict of supported options below.
Default: Defaults are shown below.
Description: Modify the font, color and opacity of tip labels.

In [32]:

# you can view the default options here
rtre.style.tip_labels_style

# you can view the default options here rtre.style.tip_labels_style

Out[32]:

{
    fill: (0.145, 0.145, 0.145, 1.0),
    fill_opacity: None,
    font_size: 12,
    font_weight: 300,
    font_family: 'Helvetica',
    anchor_shift: 15,
    baseline_shift: 0,
    text_anchor: 'start',
}

In [33]:

rtre.draw(
    tip_labels_style={
        "fill": "red", 
        "font-size": "15px", 
        "anchor-shift": "40px", 
    }
);

rtre.draw( tip_labels_style={ "fill": "red", "font-size": "15px", "anchor-shift": "40px", } );

Node labels styling¶

node_labels¶

The node_labels argument is used to provide labels at node positions, and is often used to show support or trait values. If node markers are plotted the labels are drawn on top of the node markers which makes them easier to see.

Type: boolean, str, or list of strings or ints.
Allowed: True, False, string name of features (e.g., "idx", "support"), or list that is the same length as the number of nodes.
Default: False
Description: If True then the node index labels are used.

In [34]:

# shows node labels (default feature to show is 'idx' labels)
rtre.draw(node_labels=True);

# shows node labels (default feature to show is 'idx' labels) rtre.draw(node_labels=True);

In [35]:

# suppreses node labels
rtre.draw(node_labels=False);

# suppreses node labels rtre.draw(node_labels=False);

In [36]:

# suppresses node labels, but using node_sizes ensures nodes are still shown
rtre.draw(node_labels=False, node_sizes=10);

# suppresses node labels, but using node_sizes ensures nodes are still shown rtre.draw(node_labels=False, node_sizes=10);

In [37]:

# select a data feature ("support") of Nodes to extract and show on node labels 
rtre.draw(node_labels="support");

# select a data feature ("support") of Nodes to extract and show on node labels rtre.draw(node_labels="support");

In [38]:

# build (or extract) a list of values in idx order for plotting on nodes
sups = rtre.get_node_data("support")

# enter node labels as a list in idx node order
rtre.draw(node_labels=sups);

# build (or extract) a list of values in idx order for plotting on nodes sups = rtre.get_node_data("support") # enter node labels as a list in idx node order rtre.draw(node_labels=sups);

node_labels_style¶

The node_labels_style argument is a dictionary that can apply CSS styling to all node labels. This includes options to change the font-size, and the fill and stroke color and opacity.

Type: dictionary.
Allowed: CSS values supported for text by toyplot.
Default: fill: near-black, font-size: '11px'.
Description: A dictionary of CSS style options applied to text of node labels.

In [39]:

# default options can be seen from the tree style dict
rtre.style.node_labels_style

# default options can be seen from the tree style dict rtre.style.node_labels_style

Out[39]:

{
    fill: (0.145, 0.145, 0.145, 1.0),
    fill_opacity: 1.0,
    font_size: 9,
    font_weight: 300,
    font_family: 'Helvetica',
    anchor_shift: 0,
    baseline_shift: 0,
    text_anchor: 'middle',
}

In [40]:

rtre.draw(
    node_labels='idx',
    node_sizes=15,
    node_colors="white",
    node_labels_style={      ## <- entered as a dict
        "fill": "red",
        "font-size": "8px",
    }
);

rtre.draw( node_labels='idx', node_sizes=15, node_colors="white", node_labels_style={ ## <- entered as a dict "fill": "red", "font-size": "8px", } );

Node styling¶

node_sizes¶

The node_sizes argument sets the size of node markers. All can be set to the same size, or different sizes.

Type: int, float, list[int], list[float], tuple[feature, min, max].
Allowed: Reasonable values in units of pixels are typically from 0-50.
Default: 0
Description: The size of node markers.

In [41]:

rtre.draw(node_sizes=10);

rtre.draw(node_sizes=10);

In [42]:

# draw random values between 5-15
rtre.draw(node_sizes=np.random.uniform(5, 15, rtre.nnodes));

# draw random values between 5-15 rtre.draw(node_sizes=np.random.uniform(5, 15, rtre.nnodes));

In [43]:

# use tuple format to range-map values of a data feature between min max sizes
rtre.draw(node_sizes=("height", 5, 15));

# use tuple format to range-map values of a data feature between min max sizes rtre.draw(node_sizes=("height", 5, 15));

node_colors¶

Apply a single color to all node markers, or different colors to each.

Type: str, list[str], tuple[str, Colormap]
Allowed: Any color argument supported in toyplot colors.
Default: rgba(40.0%,76.1%,64.7%,1.000) (the first color from colormap 'Set2' (cyan))
Description: A single color can be entered to apply to all node markers, or a list of colors can be entered in idx order to apply different colors to each node. The special tuple syntax can be used to map colors to feature data extracted from a tree.

In [58]:

# set a single color for all nodes
rtre.draw(node_sizes=10, node_colors="red");

# set a single color for all nodes rtre.draw(node_sizes=10, node_colors="red");

In [66]:

# create a list of colors (e.g., red or blue randomly sampled nnodes times)
colors = np.random.choice(["red", "blue"], size=rtre.nnodes)
rtre.draw(node_sizes=10, node_colors=colors);

# create a list of colors (e.g., red or blue randomly sampled nnodes times) colors = np.random.choice(["red", "blue"], size=rtre.nnodes) rtre.draw(node_sizes=10, node_colors=colors);

In [67]:

# colormap data from a tree feature to a colormap using tuple format
rtre.draw(node_sizes=10, node_colors=("height", "Greys"));

# colormap data from a tree feature to a colormap using tuple format rtre.draw(node_sizes=10, node_colors=("height", "Greys"));

node_markers¶

See toyplot markers for available options.

In [71]:

# default marker is a circle
rtre.draw(node_sizes=10, node_markers="o");

# default marker is a circle rtre.draw(node_sizes=10, node_markers="o");

In [74]:

# alternative shapes are available (see options above)
rtre.draw(node_sizes=10, node_markers="s");

# alternative shapes are available (see options above) rtre.draw(node_sizes=10, node_markers="s");

Rectangular markers can be drawn in many dimensions. Designate "r2x1" for a box that is twice as wide as it is tall.

In [76]:

# rectangles for nodes
rtre.draw(node_sizes=10, node_markers="r2x1.25");

# rectangles for nodes rtre.draw(node_sizes=10, node_markers="r2x1.25");

node_style¶

The node_style argument can be used to set CSS styles to the node markers to style fill and stroke color and opacity, and stroke width.

In [88]:

# default options can be viewed here
rtre.style.node_style

# default options can be viewed here rtre.style.node_style

Out[88]:

{
    fill: (0.4, 0.7607843137254902, 0.6470588235294118, 1.0),
    fill_opacity: None,
    stroke: '#262626',
    stroke_width: 1.5,
    stroke_opacity: None,
}

In [89]:

rtre.draw(
    node_sizes=10,
    node_style={
        "fill": "orange",
        "fill-opacity": 0.5,
        "stroke": "black",
        "stroke-opacity": 0.5,
        "stroke-width": 3,
    }
);

rtre.draw( node_sizes=10, node_style={ "fill": "orange", "fill-opacity": 0.5, "stroke": "black", "stroke-opacity": 0.5, "stroke-width": 3, } );

node_hover¶

Enables interactive hover over nodes so that you can see all features associated with each.

In [91]:

# hover over the nodes
rtre.draw(node_hover=True, node_sizes=15);

# hover over the nodes rtre.draw(node_hover=True, node_sizes=15);

Layout¶

layout¶

Type: str
Allowed: 'right', 'r'; 'left', 'l'; 'down', 'd'; 'up', 'u'; 'unrooted', 'unr'; 'circular', 'c'; Default: 'r'
Description: The layout orients the direction of tip labels. Options include linear trees facing right, left, up, down, as well as circular and unrooted trees.

In [102]:

rtre.draw(layout='d');

rtre.draw(layout='d');

In [103]:

rtre.draw(layout='l');

rtre.draw(layout='l');

In [104]:

# unrooted
rtre.draw(layout='unr');

# unrooted rtre.draw(layout='unr');

todo¶

Type:
Allowed:
Default:
Description:

Aligned Edge Styling¶

edge_align_style¶

Type:
Allowed:
Default:
Description:

In [106]:

# view the allowed and default options
rtre.style.edge_align_style

# view the allowed and default options rtre.style.edge_align_style

Out[106]:

{
    stroke: (0.66, 0.66, 0.66, 1),
    stroke_width: 2,
    stroke_opacity: 0.75,
    stroke_linecap: 'round',
    stroke_dasharray: '2,4',
}

In [108]:

rtre.draw(
    tip_labels_align=True, 
    edge_align_style={
        "stroke": "violet",
        "stroke-width": 3.5,
        "stroke-dasharray": "2,5"    # size of dash, spacing of dashes
    });

rtre.draw( tip_labels_align=True, edge_align_style={ "stroke": "violet", "stroke-width": 3.5, "stroke-dasharray": "2,5" # size of dash, spacing of dashes });

Built in tree_style¶

A number of built-in tree_style options are avilable. These allow you to enter just a single option to set the base style of the drawing, which affects many styles. Any additional drawing arguments that you add will be applied on top of this base style. The arg ts can be used as a shortcut for tree_style. The default style is 'n' (normal).

In [112]:

rtre.draw(tree_style='c');

rtre.draw(tree_style='c');

In [114]:

rtre.draw(tree_style='r');

rtre.draw(tree_style='r');

In [115]:

rtre.draw(tree_style='s');

rtre.draw(tree_style='s');

Scale_bar¶

You can add a scale_bar to any tree plot with the draw argument scale_bar=True. When creating a drawing (which return three objects) you can store the middle object (axes) to further set styling options on it. You can also optionally enter a float value such as scale_bar=1e6 to add a scale_bar where branch lengths will be returned in units divided by 1e4. This can help to make units of millions of years listed as integers instead of many zeros.

Type: boolean or float Allowed: True, False, float Default: False Description: Add a scale bar and optionally set the scalebar unit by entering a float.

In [116]:

# add scale bar
rtre.draw(scale_bar=True);

# add scale bar rtre.draw(scale_bar=True);

In [117]:

# add scale bar with units scaling
rtre.draw(scale_bar=1e-2);

# add scale bar with units scaling rtre.draw(scale_bar=1e-2);