/
tutorial_index.html
246 lines (232 loc) · 15.7 KB
/
tutorial_index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Emperor</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="">
<link href="bootstrap/css/bootstrap.css" rel="stylesheet">
<style type="text/css">
body {
padding-top: 20px;
padding-bottom: 60px;
}
/* Custom container */
.container {
margin: 0 auto;
max-width: 1000px;
}
.container > hr {
margin: 60px 0;
}
/* Main marketing message and sign up button */
.jumbotron {
margin: 80px 0;
text-align: center;
}
.jumbotron h1 {
font-size: 100px;
line-height: 1;
}
.jumbotron .lead {
font-size: 24px;
line-height: 1.25;
}
.jumbotron .btn {
font-size: 21px;
padding: 14px 24px;
}
/* Supporting marketing content */
.marketing {
margin: 60px 0;
}
.marketing p + h4 {
margin-top: 28px;
}
/* Customize the navbar links to be fill the entire space of the .navbar */
.navbar .navbar-inner {
padding: 0;
}
.navbar .nav {
margin: 0;
display: table;
width: 100%;
}
.navbar .nav li {
display: table-cell;
width: 1%;
float: none;
}
.navbar .nav li a {
font-weight: bold;
text-align: center;
border-left: 1px solid rgba(255,255,255,.75);
border-right: 1px solid rgba(0,0,0,.1);
}
.navbar .nav li:first-child a {
border-left: 0;
border-radius: 3px 0 0 3px;
}
.navbar .nav li:last-child a {
border-right: 0;
border-radius: 0 3px 3px 0;
}
</style>
<link href="bootstrap/css/bootstrap-responsive.css" rel="stylesheet">
<!-- GitHub ribbon -->
<a href="https://github.com/biocore/emperor"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="bootstrap/js/html5shiv.js"></script>
<![endif]-->
<!-- Fav and touch icons -->
<link rel="shortcut icon" href="img/favicon.ico">
</head>
<body>
<div class="container">
<div class="masthead">
<a href="index.html"><p align="center"><img src="img/emperor_heading.png" alt="Emperor Logo"></p></a>
<div class="navbar">
<div class="navbar-inner">
<div class="container">
<ul class="nav">
<li><a href="index.html">Home</a></li>
<li><a href="build/html/index.html">Documentation</a></li>
<li><a href="description_index.html">Description</a></li>
<li class="active"><a href="tutorial_index.html">Tutorial</a></li>
<li><a href="installation_index.html">Installation</a></li>
<li><a href="https://github.com/biocore/emperor/issues">Support</a></li>
</ul>
</div>
</div>
</div><!-- /.navbar -->
</div>
<h2>Tutorial</h2>
<h3 class="muted">Introduction</h3>
<p class="lead" align="justify">
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 <a href="build/html/tutorials/animations.html">here</a>.
<br>
The dataset that we will use to exemplify Emperor’s functionality, comes from the <a href="http://www.pnas.org/content/107/14/6477.long">Fierer et. al. 2010</a> article, where three individuals and their keyboards were sampled, Figure 1.
<br>
To get started, first download and unzip these <a href="files/files.zip">files</a>, here you will find a principal coordinates file, and a mapping file. These input files are in the standard format used in <a href="http://www.qiime.org">QIIME</a>. Before continuing with the tutorial make sure you have the latest version of <a href=" https://www.google.com/intl/en/chrome/browser/">Google Chrome</a> installed in your computer. The sections described in this tutorial are:
<br>
<ul >
<li><a class="lead" href="#section0">Command Line Interface</a></li>
<li><a class="lead" href="#section1">Graphical User Interface</a></li>
<li><a class="lead" href="#section2">Changing The Coloring</a></li>
<li><a class="lead" href="#section3">Changing The Opacity</a></li>
<li><a class="lead" href="#section4">Color Schemes</a></li>
<li><a class="lead" href="#section5">Exporting</a></li>
<li><a class="lead" href="#section6">Sharing</a></li>
</ul>
</p>
<hr>
<h3 class="muted" id="section0">Command Line Interface</h3>
<p class="lead" align="justify">
Emperor offers a convenient command line interface script (<code>make_emperor.py</code>), see the <a href="installation_index.html">installation notes</a> 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 <code>make_emperor.py -h</code> from a terminal window, will display the available options and a concise description for each of these.
<br>
Besides the coordinates and mapping file options, we will also use the <code>-b</code> option and the <code>-o</code> option. The <code>-b</code> 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 <code>-o</code> option allows us to specify the name of the output directory.
</p>
<pre><code>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</code></pre>
<br>
<p class="lead" align="justify">
Note: when <code>&&</code> is used with the <code>-b</code> option, two categories from the mapping file will be combined, in this case the values in <code>HAND</code> and the values in <code>HOST_SUBJECT_ID</code> will be concatenated.
<br>
A new folder named keyboard will be created, as this is the name we gave via <code>-o</code>, here you will find two files, these two files will be named the same for all datasets:
</p>
<p class="lead" align="justify">
<ul>
<li><code>index.html</code></li>
<li><code>emperor_required_resources/</code></li>
</ul>
</p>
<p class="lead" align="justify">
<br>
Opening <code>index.html</code> 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.
</p>
<hr>
<h3 class="muted" id="section1">Graphical User Interface</h3>
<p class="lead" align="justify">
Once you open the <code>index.html</code> file that was just generated, you should see something similar to the following figure:
</p>
<p align="center"><img src="img/tutorial/1.png" alt="GUI 1"></p>
<p class="lead" align="justify">
For a detailed explanation of the options available from the main interface refer to the <a href="description_index.html">description section</a>.
<br>
</p>
<h3 class="muted" id="section2">Changing The Coloring</h3>
<p class="lead" align="justify">
Spheres drawn in the main canvas are colored by the selected column in the mapping file under the Colors tab, in this example <code>AGE</code>. The available metadata categories are sorted in alphabetical order hence <code>AGE</code> 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 <code>HOST_SUBJECT_ID</code>. Now that samples are colored by this grouping, spheres will be colored in three different tints, each corresponding to a different subject.
</p>
<p align="center"><img src="img/tutorial/2.png" alt="HOST_SUBJECT_ID Coloring"></p>
<p class="lead" align="justify">
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 <code>232:M9</code>, 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 <code>choose</code> button (3).
</p>
<p align="center"><img src="img/tutorial/capture_2.png" alt="Three panels"></p>
<h3 class="muted" id="section3">Changing The Opacity</h3>
<p class="lead" align="justify">
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 <code>AGE</code> 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 <code>NA</code>, move it until you reach almost half the opacity. The end result will be similar to the next figure.
</p>
<p align="center"><img src="img/tutorial/6.png" alt="Opacity reduction"></p>
<h3 class="muted" id="section4">Color Schemes</h3>
<p class="lead" align="justify">
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 <code>HAND&&HOST_SUBJECT_ID</code> category that we create with the <code>–b</code> option is a good example. Switch to the Colors tab and then in the dropdown menu to change the category from <code>HOST_SUBJECT_ID</code> to the combination of both the <code>HAND</code> and <code>HOST_SUBJECT_ID</code> 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.
</p>
<p align="center"><img src="img/tutorial/treta.png" alt="To Discrete"></p>
<p class="lead" align="justify">
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 <code>M9Indr217.140998</code>. 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.
</p>
<p align="center"><img src="img/tutorial/10.png" alt="Filter"></p>
<p class="lead" align="justify">
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.
</p>
<p align="center"><img src="img/tutorial/exes.png" alt="Filter"></p>
<p class="lead" align="justify">
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.
</p>
<p align="center"><img src="img/tutorial/rotating_1.png" alt="Filter"></p>
<p align="center"><img src="img/tutorial/rotating_2.png" alt="Filter"></p>
<h3 class="muted" id="section5">Exporting</h3>
<p class="lead" align="justify">
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.
</p>
<p align="center"><img src="img/tutorial/11.png" alt="Export Screenshot"></p>
<p class="lead" align="justify">
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".
<br><br>
Converting these figures into other formats can be achieved using external and freely available tools like <a href="http://inkscape.org">Inkscape</a>, 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.
</p>
<pre><code>inkscape -f figure_example.svg -A figure_example.pdf</code></pre>
<p class="lead" align="justify">
More information about the usage of this command line utility can be found <a href="http://inkscape.org/doc/inkscape-man.html">here</a>.
</p>
<h3 class="muted" id="section6">Sharing</h3>
<p class="lead" align="justify">
Simply compress the output directory (specified by the <code>-o</code> option in <code>make_emperor.py</code>) and share. The newly created <code>index.html</code> 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 <code>emperor_required_resources</code> folder.
</p>
<hr>
<div class="footer">
<a href="https://github.com/biocore/emperor/network/members">
<p align="center">© The Emperor Development Team</p>
</a>
</div>
</div> <!-- /container -->
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="bootstrap/js/jquery.js"></script>
<script src="bootstrap/js/bootstrap-transition.js"></script>
<script src="bootstrap/js/bootstrap-alert.js"></script>
<script src="bootstrap/js/bootstrap-modal.js"></script>
<script src="bootstrap/js/bootstrap-dropdown.js"></script>
<script src="bootstrap/js/bootstrap-scrollspy.js"></script>
<script src="bootstrap/js/bootstrap-tab.js"></script>
<script src="bootstrap/js/bootstrap-tooltip.js"></script>
<script src="bootstrap/js/bootstrap-popover.js"></script>
<script src="bootstrap/js/bootstrap-button.js"></script>
<script src="bootstrap/js/bootstrap-collapse.js"></script>
<script src="bootstrap/js/bootstrap-carousel.js"></script>
<script src="bootstrap/js/bootstrap-typeahead.js"></script>
</body>
</html>