Drawing Trees

Topiary allows users to generate their own plots with customized formatting using the topiary python API. Users can control all aspects of phylogenetic tree drawing from a the topiary.draw.tree function. The following python generates the following output

import topiary
topiary.draw.tree("05_reconcile-bootstraps")
Topiary tree drawing

Description of arguments

You have a lot of control over how the tree is drawn depending on the arguments you pass into topiary.draw.tree.

topiary.draw.tree("05_reconcile-bootstraps",
                  output_file=None,
                  bs_color={50:"#ffffff",100:"#000000"},
                  pp_color={0.7:"#ffffff",1.0:"#DC801A"},
                  event_color={"D":"#64007F","L":"#BAD316","T":"#407E98"},
                  bs_label=False,
                  pp_label=False,
                  event_label=False,
                  anc_label=True,
                  tip_columns=None,
                  tip_name_separator="|",
                  disambiguate_tip_names=True,
                  node_color=None,
                  node_size=None,
                  font_size=15,
                  tip_text_style=None,
                  label_text_style=None,
                  label_position="right",
                  label_position_offset=None,
                  label_color="gray",
                  stroke_width=2,
                  vertical_pixels_per_tip=25,
                  min_height=300,
                  df=None,
                  anc_link_path=None,
                  return_canvas=False,
                  **kwargs)

General plot features

  • output_file. Output file. Type is determined by file extension. Allowed extensions are pdf, svg, and png. If this is not specified and you are running in a jupyter notebook, the tree will be written out to the screen only.

  • font_size. Controls overall font size for the document. This is the size assigned to the tip labels. Node labels are given a 0.75 this size unless a specific label size is given using label_text_style.

  • stroke_width. Stroke width, in pixels, for the tree.

  • vertical_pixels_per_tip. How many vertical pixels to assign each tip on the tree. This controls the height of the plot.

  • min_height. Make sure the plot is at least this many pixels high.

  • return_canvas. Return the toyplot canvas even if not in a Jupyter notebook. (Canvas is always returned in a Jupyter notebook.)

Internal nodes (ancestors)

Labels

  • What labels to draw?

    • bs_label. Draw bootstrap labels (True or False)

    • pp_label. Draw posterior probability labels (True or False)

    • event_label. Draw reconciliation event labels (True or False)

    • anc_label. Draw ancestral name labels (True or False)

  • How to format labels?

    • label_position. Where to position the labels relative to the node. (“top-left”, “top”, “top-right”, “right”, “bottom-right”, “bottom”, “bottom-left”, or “left”.)

    • label_position_offset. How far, in pixels, to shift the position of the label in the direction indicated by label position.

    • label_color. Label color. For details on how to specify color, see the colors section below.

    • label_text_style. This gives detailed control over the node label styling. This is a dictionary that contains css properties for the text. For details see the CSS section below.

    • anc_link_path. This string lets you specify that the ancestor labels should be links. For example, you could set this to: "<a href="{anc_label}.html">{anc_label}</a>" so each ancestor is labeled by anc_label as a hyperlink to an html file called anc_label.html.

Colors

  • bs_color. Branch support color map. Should be a dictionary with two elements that keys bootstrap values to color. For example, bs_color={50:"white",100:"black"} would create a color gradient between white and black for bootstrap values between 50 and 100. Values above and below the input bootstrap values are set to the color of the relevant input value. In this case, a bootstrap value of 20 would be colored white. For details on how to specify color, see the colors section below.

  • pp_color. Posterior probability color map. See description of bs_color for format.

  • event_color. Color nodes according to the reconciliation event. This should be a dictionary keying events to colors. Allowable events are speciation (S), duplication (D), loss (L), and lateral transfer (T). For example, event_color={"D":"pink"} would color all nodes that are duplications pink. Events that have no key in the dictionary will not be colored. For details on how to specify color, see the colors section below.

  • node_color. Set single color to all nodes. This overrides all other color arguments. For details on how to specify color, see the colors section below.

Size

  • node_size. Set size of nodes in pixels

Tree tips (modern proteins)

How to construct names?

  • tip_columns. Which columns from the dataframe to use to build tip the tip labels.

  • tip_name_separator. What to place between the tip column values. This can be any character (i.e. "|", ",", etc.).

  • disambiguate_tip_names. Whether or not to append uid to duplicate tip names to make them unique (True or False).

The defaults are tip_columns=["species","recip_paralog"] and tip_name_separator="|", which gives tip names like “Homo sapiens|LY96”.

How to format tip labels?

  • tip_text_style. This gives detailed control over the tip label styling. This is a dictionary that contains css properties for the text. For details see the CSS section below.

Even more customization

The topiary.draw.tree object is a wrapper that constructs a topiary.draw.PrettyTree object. Advanced users can create custom instances of this object to further customize tree outputs. Please see the PrettyTree API docs for details.

Topiary draws trees using the toytree library, which is built on the toyplot library. The topiary.draw.tree function returns a toyplot canvas object. Advanced users can thus further manipulate the plot by editing that canvas as described in the toyplot and toytree documentation.

General considerations

Because topiary trees are ultimately built using toyplot, any customizations of color or styling via css accepted by toyplot are available to topiary users. For full details, see the toyplot documentation. We summarize the most commonly used options here.

Colors

Colors can be specified in three different ways:

  • RGBA tuples. Examples: (255,255,255,255) would be white; (255,0,0,255) would be red; (0,255,0,125) would be half-opaque green.

  • Named colors. To get a full list of the colors available, you can run the following code in a jupyter notebook or python session.

    import toyplot
print(toyplot.color.css.names)

  • Hexadecimal strings. Examples include "#407E98" (a slate blue), "#FFFFFF" (white), "#000000" (black).

For a complete discussion of the color options, see the toyplot documentation.

CSS

CSS (Cascading Style Sheets) is the language used to format html in web pages. The toyplot library, that topiary uses under the hood can a fair number of css properties and apply them to text. For an up-to-date list of available properties, see the toyplot documentation. As of toyplot 1.02, the following css properties can be set:

  • “alignment-baseline”

  • “baseline-shift”

  • “fill”

  • “fill-opacity”

  • “font-family”

  • “font-size”

  • “font-weight”

  • “line-height”

  • “opacity”

  • “stroke”

  • “stroke-opacity”

  • “stroke-width”

  • “text-anchor”

  • “text-decoration-line”

  • “text-shadow”

For information on each of these css properties, there are css references online (i.e. w3schools).