Automatically colouring trees

Overview

This tutorial will show you how you can automatically colour and visualize phylogenies in TreeSAPP reference packages with treesapp colour and iTOL. With its most basic usage, treesapp colour will generate iTOL-compatible colour style and colour strip files to visualize the taxonomies of a reference package. With slightly more sophistication, treesapp colour can generate those files necessary to show phenotypic data on a phylogenetic tree such as enzyme activities, ortholog names, metabolic pathways and more.

Moreover, the files generated by treesapp colour can be used by treesapp layer to add annotations to ORF-level annotations in the classification table made by treesapp assign. Once the ORFs have been annotated with the phenotypic data of your choosing you are able to create your own custom visualizations however you wish.

Supported versions >=0.11.0

---

Ingredients

To use treesapp colour all you really need is one or more reference packages. If you want to see all that we have available, check out our RefPkgs repository. If nothing catches your eye there, you can easily create a new reference package using treesapp create.

If you'd like to create iTOL annotation files to visualize a property of the reference package other than taxonomy, you'll need to first annotate your reference package using treesapp package edit.

Usage

To print the help statement for treesapp colour use:

treesapp colour -h

The most basic usage only requires the path to one or more reference packages. If you used git clone to download TreeSAPP, it comes with several already available in TreeSAPP/treesapp/data/. We'll use the two reference packages treesapp/data/McrA_build.pkl and treesapp/data/McrB_build.pkl in the first few examples.

Colouring by taxonomy

To create the iTOL colour-strip and colours-style files for the McrA reference package, you can simply use the following command.

treesapp colour -r <directory path>/McrA_build.pkl

By default, TreeSAPP uses the Python library seaborn to create a colour palette using 'BrBG' for all unique taxonomic orders. The colour palette can be changed using the '-p/--palette' option.

Suppose you want to colour multiple reference packages such that the taxa have the same colours in both annotation files. All you need to do is provide more reference package paths like so:

treesapp colour -r treesapp/data/McrA_build.pkl treesapp/data/McrB_build.pkl --rank_level class --palette viridis

Additionally, we changed the taxonomic rank to with '-l/--rank_level' class, so all the unique class names will be coloured instead of the orders.

In our example using two difference subunits of the enzyme methyl-coenzyme M-reductase (Mcr), most if not all of the same taxa will be present in both reference packages. However, that may not always be the case and you can control which taxa are included by selecting either the 'union' or 'intersection' between the two sets of unique taxa. This is controlled by the '-s/--taxa_set_operation' argument. If we want only the taxonomic families to be coloured that are present in both reference packages, we'd use the following command.

treesapp colour -r treesapp/data/McrA_build.pkl treesapp/data/McrB_build.pkl --rank_level family --taxa_set_operation i

Other useful options that can be used for removing taxa are:

• -m/--min_proportion to skip annotating taxa that constitute a small part of the reference package
• -f/--filter to prevent annotating taxonomic groups that you're not interested in
• --no_polyphyletic to remove taxa that are present in polyphyletic clades

Colouring by phenotype

To create the iTOL colour files to visualize some property other than taxonomy, we'll need to use the '-n/--attribute' argument with a feature that has been saved to the reference package. You can list a reference package's features using treesapp package view:

treesapp package view feature_annotations -r treesapp/data/McrA_build.pkl

Once identified, you can pass the name of the feature to treesapp colour using the '--attribute' argument.

treesapp colour -r treesapp/data/McrA_build.pkl --palette viridis --attribute Pathway --output McrA_annotations/

As with colouring by taxonomy two files will be written the output directory:

1. McrA_Pathway_colours_style.txt
2. McrA_Pathway_colour_strip.txt

These files begin with the name of the reference package, then the feature name and finally the iTOL-specific suffixes to indicate what information they hold.

iTOL

Now for the very easy part of loading the outputs into iTOL. You'll need to navigate to iTOL and load the JPlace file generated by treesapp assign. You may as well add the labels file too. At that point you can just click-and-drag the outputs (~/Desktop/McrA_Metabolism_colour_strip.txt and ~/Desktop/McrA_Metabolism_colours_style.txt) into the viewing window. Hopefully everything looks good!

With iTOL, you are also able to visualize multiple different colour strips, so you could combine both a phenotype strip with a taxonomic strip like this:

Let us know if you have any questions/comments/concerns in the issues feed!