Emperor

## Tutorial

### Introduction

This tutorial attempts to cover most of the common use cases with Emperor's graphical user interface. For a tutorial on how to create animations using Emperor, please click here.
The dataset that we will use to exemplify Emperor’s functionality, comes from the Fierer et. al. 2010 article, where three individuals and their keyboards were sampled, Figure 1.
To get started, first download and unzip these files, here you will find a principal coordinates file, and a mapping file. These input files are in the standard format used in QIIME. Before continuing with the tutorial make sure you have the latest version of Google Chrome installed in your computer. The sections described in this tutorial are:

- Command Line Interface
- Graphical User Interface
- Changing The Coloring
- Changing The Opacity
- Color Schemes
- Exporting
- Sharing

### Command Line Interface

Emperor offers a convenient command line interface script (`make_emperor.py`), see the installation notes for further details. The minimum inputs that this interface requires are a coordinates file and a mapping file, it’s worth noting that the script interface offers many options that allow the user to refine the amount of data to visualize or even to change the way it will be presented, calling `make_emperor.py -h` from a terminal window, will display the available options and a concise description for each of these.
Besides the coordinates and mapping file options, we will also use the `-b` option and the `-o` option. The `-b` option allows us to specify the categories that we want displayed in the GUI, it also allows us to combine columns from the mapping file into a single column. The `-o` option allows us to specify the name of the output directory.

    make_emperor.py -i unweighted_unifrac_pc.txt -m mapping_file.txt -b "AGE,HAND,HAND_KEY,BODY_SITE,HOST_SUBJECT_ID,HAND,HAND&&HOST_SUBJECT_ID" -o keyboard

Note: when `&&` is used with the `-b` option, two categories from the mapping file will be combined, in this case the values in `HAND` and the values in `HOST_SUBJECT_ID` will be concatenated.
A new folder named keyboard will be created, as this is the name we gave via `-o`, here you will find two files, these two files will be named the same for all datasets:

- `index.html`
- `emperor_required_resources/`

Opening `index.html` with Google Chrome will present the main GUI, to do so you can right click this file and make sure you open it with Google Chrome.

### Graphical User Interface

Once you open the `index.html` file that was just generated, you should see something similar to the following figure:

For a detailed explanation of the options available from the main interface refer to the description section.

### Changing The Coloring

Spheres drawn in the main canvas are colored by the selected column in the mapping file under the Colors tab, in this example `AGE`. The available metadata categories are sorted in alphabetical order hence `AGE` is the first in this list. To change the coloring scheme click the Colors tab, then in the dropdown menu shown at the top click to select `HOST_SUBJECT_ID`. Now that samples are colored by this grouping, spheres will be colored in three different tints, each corresponding to a different subject.

Modifying the colors used to distinguish between subjects is achieved by clicking the frame by the side of each subject name. For example to change the color of the samples belonging to `232:M9`, click on the green square by the left side of this label (1), a color picker will appear on screen (2), select a new color by pointing and clicking at it with the mouse; to confirm this selection use the `choose` button (3).

### Changing The Opacity

Similarly to the coloring of the samples, opacity is an attribute that can be determined on a per-category basis. To illustrate an example where this is useful, let’s reduce the opacity in the samples without an `AGE` value i. e. the keys of the subject’s keyboard. Begin by navigating to the visibility tab and with the slider under the label that reads `NA`, move it until you reach almost half the opacity. The end result will be similar to the next figure.

### Color Schemes

Frequently you will find that metadata categories have multiple values that are easier to visualize with a color map, on the other side when the values have no sequential relationship, it’s better to use what’s called a discrete set of colors. In this dataset the `HAND&&HOST_SUBJECT_ID` category that we create with the `–b` option is a good example. Switch to the Colors tab and then in the dropdown menu to change the category from `HOST_SUBJECT_ID` to the combination of both the `HAND` and `HOST_SUBJECT_ID` values. Navigate to the View menu and click the “Use gradient colors” checkbox this will let immediately switch the colors used for each of the values under this mapping file header.

Pointing out the location of a sample within the plot, can be achieved by using the Key menu for example let’s indicate where is sample `M9Indr217.140998`. In the Key tab and search for the name either using the text entry box or navigating through the list of values. Once you’ve found it click in the colored square by it’s side and a white arrow will appear on the plot pointing at the place where the sample is located.

Often times PCoA data will span over more than three dimensions, other dimensions can be visualized using the axes menu; just select the three coordinate axes that you want your data to be shaped by and hit the refresh button. In this instance let’s go to the Axes menu select P3 in the Axis 1 drop down menu, P4 in the Axis 2 drop down menu and P5 in the Axis 3 drop down menu, lastly click the refresh button this will redraw the visualization using the coordinate values in each of the selected axes.

Dragging the plot with the left button of the mouse, will let you rotate the plot in the direction that the mouse is being moved. If the right click is pressed instead, the plot will be dragged with all it’s elements. To zoom-in or zoom-out in the plot use the scroll wheel. And note that at any time you can go back to the options tab and click recenter camera to go back to the original position.

### Exporting

Emperor generates publication quality figures in scalable vector graphics (SVG) format. The "Save as SVG" button is found under the "Options" tab, note that if you mark the "Create labels?" checkbox an additional file with legends describing the coloring scheme, a color to category name pair, will be downloaded to your computer.

In this example setting the file name as "figure_example" renames the legends file as "figure_example_labels.svg" and the current view in the visualization canvas as "figure_example.svg".
Converting these figures into other formats can be achieved using external and freely available tools like Inkscape, which conveniently provides a command line utility to convert files into different formats. The following command line call will convert our SVG formatted file to a PDF formatted file.

    inkscape -f figure_example.svg -A figure_example.pdf

More information about the usage of this command line utility can be found here.

### Sharing

Simply compress the output directory (specified by the `-o` option in `make_emperor.py`) and share. The newly created `index.html` file contained within the output directory can then be visualized and manipulated through the Chrome web browser as long as it is accompanied by the `emperor_required_resources` folder.