Annotation Precedence
With Iroki, we can quickly color branches and labels independently of one another, remap label names, and use numerical data to create color gradients all on the same tree. To try and keep things clear and explicit, Iroki has strict rules of precedence when applying more than one annotation to the same tree.
- Command line options (
--color-branches,--color-taxa-names) - Color map
- Biom file
Then after all the coloring annotation has been done, the name map is used to map names.
This means that any coloring specifications in the color map will override the color gradient calculated from the biom file.
Command line options have the highest precedence of all. So if you only pass --color-branches then regardless of whether or not the color map or biom file would have added color to labels, Iroki will NOT color the labels.
Any of the tree annotation spec files (color map, name map, or biom file) can omit any of the sequences in the Newick file. This allows for very granular control over annotating the trees. Let's look at an example.
The files for this tutorial can be downloaded from the following links: biom file, color map, name map, newick tree, and the resulting nexus file.
We will pass both --color-branches and --color-taxa-names so that we may focus on the interaction of the three annotation spec files with each other.
The files look like this
This is the iroki command used to generate the Nexus file.
iroki -bte -f annotation_order.newick -o annotation_order.nexus -i annotation_order.biom -c annotation_order.color_map -n annotation_order.name_map
Here is the resulting tree.
There is a lot going on in this example. Let's break it down.
The first thing to notice is that the tree file, the color map, and the biom file all use the same sequence names. This is because the color map and the biom file match to the original names in the tree file as opposed to the new names specified in the name map file.
We can think of the name map as the last annotation that Iroki applies.
Not all sequences in the tree have to be present in the biom file. If a sequence is missing from the biom file, Iroki will ignore that sequence when calculating the color gradient.
Here is where things get interesting. In this example, we are using the color map to override the color gradient Iroki calculated from the biom file.
If the color map was not used, the branch and label of LeBron (James) would be green, the branch and label of s2 would be blue and the branch and label of s3 would be cyan, the label and branch of s4 would be a light green, and the label and branch of s5 would be a light blue.
Because of the color map however, the label of LeBron (James) is purple, the label of s3 is red, the label and branch of s4 is orange, and the label and branch of s5 is black.
In this way, we can combine the color map and the biom file to get cool color schemes like coloring the labels based on abundance while coloring the branches by sampling location for example.