Color Map
Table of Contents
- Making The Color Map File
The color map file is where the magic of Iroki happens! In this tutorial we will explain how to make and use color maps with Iroki.
- The color map file is a plain text file with two or three tab-separated columns.
- Any line in the file that begins with a
#will be treated as a comment and ignored. - Color names and hex codes are case insensitive.
- Hex codes must begin with a
#.
The default color is black.
This has a few implications.
- If a cell in the color map is empty or missing, Iroki will assume that you want that item to be black. If you want to be more explicit, you can but
blackin any blank cell in the following examples. - If there are sequences in the tree that are NOT in the color map file, these sequences will also remain black.
Each of the examples for the two column color map will add color annotations to the following tree:
(s1,(s2,(s3,(s4,(s5,(s6,s7))))));
The newick file is available for download here.
In its simplest form, the color map has two columns name and color. The name refers to the label name of a leaf of the tree. The color can be specified as hex codes (e.g., #00FF00 for green) or as the name of a color. For a complete list of colors available to use in the color map file, see this page.
| #Name | Color |
|---|---|
| s1 | red |
| s2 | blue |
The color map file is available for download here.
In the above color map, the labels and branches of the sequences named "s1" and "s2" would be matched. However, whether label only, branches only, or both labels and branches are colored depends on the command line options passed in to the Iroki program.
Note: See here for more details on all available command line options.
To color both labels and branches, use these options
--color-branches
--color-taxa-names
and tree will look like this. (download it)
To color labels only, use these options
--color-taxa-names
and tree will look like this. (download it)
To color branches only, use these options
--color-branches
and tree will look like this. (download it)
The three column color map is used when you want to color labels and branches separately.
The three column color map has the following columns: name, label color, and branch color.
The following examples will all use the following Newick file.
(s1,(s2,(s3,(s4,(s5,(s6,(s7,s8)))))));
You can download the file here.
As in the two column color maps, we can specify whether to color labels, branches, or both at the command line. These options have a higher precedence than the color map itself. This means that the command line coloring options will override anything that is in the color map file. For example, if s1 is specified to have its label colored blue, and its branch colored red, but only the --color-branches option is passid to Iroki, any color specifications for labels in the color map will be ignored. The examples that follow will help illustrate this behavior.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | red | green |
| s2 | blue | red |
In this example, the label of s1 will be red while the branch will be green. Similarly, the label for s2 will be blue and the branch will be red.
Command line options: --color-branches --color-taxa-names.
Command line options: --color-taxa-names.
Command line options: --color-branches.
The last example was a simple one, but the color map is actually pretty flexible in the different ways that you can specify colors. Let's take a look.
Iroki will infer whether you want the label or the branch to be colored based on the column.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | blue | red |
| s2 | red | blue |
| s3 | blue | |
| s4 | red | |
| s5 | red | |
| s6 | blue |
Command line options: --color-branches --color-taxa-names.
Command line options: --color-taxa-names.
Command line options: --color-branches.
Sometimes it is better to be explicit about what you are doing. Therefore you can use tags you can use tags to clarify things.
Regardless of the column that a color specification is in, if it has a tag, Iroki will use the tag to infer whether to color the label or the branch.
The following are all valid tags:
label:redlabel:#ff0000branch:redbranch:#ff0000
Here is an example of using tags.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | label:blue | branch:red |
| s2 | label:red | branch:blue |
| s3 | branch:blue | label:red |
| s4 | branch:red | label:blue |
| s5 | label:blue | |
| s6 | label:red | |
| s7 | branch:red | |
| s8 | branch:blue |
Command line options: --color-branches --color-taxa-names.
Command line options: --color-taxa-names.
Command line options: --color-branches.
You can mix specifying colors with tags and without tags, and Iroki will know what to do.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | label:blue | red |
| s2 | label:red | blue |
| s3 | blue | branch:red |
| s4 | red | branch:blue |
Command line options: --color-branches --color-taxa-names.
Command line options: --color-taxa-names.
Command line options: --color-branches.
This color map is valid, but each row has redundant color specification.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | blue | label:blue |
| s2 | branch:blue | blue |
| s3 | label:blue | label:blue |
| s4 | branch:blue | branch:blue |
This color map has rows which are all invalid because of ambiuguous color specification.
| #Name | Label Color | Branch Color |
|---|---|---|
| s1 | blue | label:red |
| s2 | label:blue | label:red |
| s3 | branch:blue | red |
| s4 | branch:blue | branch:red |
| s5 | label:blue | |
| s6 | branch:blue |
Here are the reasons why each row is invalid...
-
s1ands2specify bothblueandredfor label color -
s3ands4specify bothblueandredfor branch color -
s5specifies bothblueandblackfor label color -
s6specifies bothblueandblackfor branch color
Iroki will raise an error if your color map has any of the above ambiguities.