Browse code

treeVisualization vignette

guangchuang yu authored on 22/12/2017 08:04:02
Showing4 changed files

... ...
@@ -1,6 +1,7 @@
1 1
 # ggtree 1.11.4
2 2
 
3
++ update treeVisualization vignette, with more layout examples added (2017-12-22, Fri)
3 4
 + update vignette (2017-12-21, Thu)
4 5
     - remove ggtreeUtilities.Rmd
5 6
     - merge treeAnnotation and advanceTreeAnnotation
6
-    
7 7
\ No newline at end of file
8
+
... ...
@@ -1469,7 +1469,7 @@ add_angle_slanted <- function(res) {
1469 1469
 
1470 1470
 calculate_branch_mid <- function(res) {
1471 1471
     res$branch <- with(res, (x[match(parent, node)] + x)/2)
1472
-    if (!is.null(res$branch.length)) {
1472
+    if (!is.null(res[['branch.length']])) {
1473 1473
         res$branch.length[is.na(res$branch.length)] <- 0
1474 1474
     }
1475 1475
     res$branch[is.na(res$branch)] <- 0
... ...
@@ -6,7 +6,7 @@ ggtree: an R package for visualization and annotation of phylogenetic trees with
6 6
 
7 7
 [![releaseVersion](https://img.shields.io/badge/release%20version-1.10.0-green.svg?style=flat)](https://bioconductor.org/packages/ggtree) [![develVersion](https://img.shields.io/badge/devel%20version-1.11.4-green.svg?style=flat)](https://github.com/guangchuangyu/ggtree) [![Bioc](http://www.bioconductor.org/shields/years-in-bioc/ggtree.svg)](https://www.bioconductor.org/packages/devel/bioc/html/ggtree.html#since) [![total](https://img.shields.io/badge/downloads-22621/total-blue.svg?style=flat)](https://bioconductor.org/packages/stats/bioc/ggtree) [![month](https://img.shields.io/badge/downloads-1218/month-blue.svg?style=flat)](https://bioconductor.org/packages/stats/bioc/ggtree)
8 8
 
9
-[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active) [![codecov](https://codecov.io/gh/GuangchuangYu/ggtree/branch/master/graph/badge.svg)](https://codecov.io/gh/GuangchuangYu/ggtree) [![Last-changedate](https://img.shields.io/badge/last%20change-2017--12--21-green.svg)](https://github.com/GuangchuangYu/ggtree/commits/master) [![GitHub forks](https://img.shields.io/github/forks/GuangchuangYu/ggtree.svg)](https://github.com/GuangchuangYu/ggtree/network) [![GitHub stars](https://img.shields.io/github/stars/GuangchuangYu/ggtree.svg)](https://github.com/GuangchuangYu/ggtree/stargazers) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://awesome-r.com/#awesome-r-graphic-displays)
9
+[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active) [![codecov](https://codecov.io/gh/GuangchuangYu/ggtree/branch/master/graph/badge.svg)](https://codecov.io/gh/GuangchuangYu/ggtree) [![Last-changedate](https://img.shields.io/badge/last%20change-2017--12--22-green.svg)](https://github.com/GuangchuangYu/ggtree/commits/master) [![GitHub forks](https://img.shields.io/github/forks/GuangchuangYu/ggtree.svg)](https://github.com/GuangchuangYu/ggtree/network) [![GitHub stars](https://img.shields.io/github/stars/GuangchuangYu/ggtree.svg)](https://github.com/GuangchuangYu/ggtree/stargazers) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://awesome-r.com/#awesome-r-graphic-displays)
10 10
 
11 11
 [![platform](http://www.bioconductor.org/shields/availability/devel/ggtree.svg)](https://www.bioconductor.org/packages/devel/bioc/html/ggtree.html#archives) [![Build Status](http://www.bioconductor.org/shields/build/devel/bioc/ggtree.svg)](https://bioconductor.org/checkResults/devel/bioc-LATEST/ggtree/) [![Linux/Mac Travis Build Status](https://img.shields.io/travis/GuangchuangYu/ggtree/master.svg?label=Mac%20OSX%20%26%20Linux)](https://travis-ci.org/GuangchuangYu/ggtree) [![AppVeyor Build Status](https://img.shields.io/appveyor/ci/Guangchuangyu/ggtree/master.svg?label=Windows)](https://ci.appveyor.com/project/GuangchuangYu/ggtree) [![Backers on Open Collective](https://opencollective.com/ggtree/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/ggtree/sponsors/badge.svg)](#sponsors)
12 12
 
... ...
@@ -46,8 +46,7 @@ Biocpkg <- function (pkg) {
46 46
 
47 47
 
48 48
 To view a phylogenetic tree, we first need to parse the tree file into *R*. The
49
-`r Biocpkg('ggtree')` package supports many file formats via the `r
50
-Biocpkg('treeio')` package, including output files of commonly used software
49
+`r Biocpkg('ggtree')` [@yu_ggtree:_2017] package supports many file formats via the `r Biocpkg('treeio')` package, including output files of commonly used software
51 50
 packages in evolutionary biology. For more details, plase refer to
52 51
 the [treeio vignette](https://bioconductor.org/packages/devel/bioc/vignettes/treeio/inst/doc/Importer.html).
53 52
 
... ...
@@ -61,7 +60,7 @@ tree <- read.tree(nwk)
61 60
 
62 61
 # Viewing a phylogenetic tree with *ggtree*
63 62
 
64
-The `r Biocpkg('ggtree')` package extends `r CRANpkg('ggplot2')` package to support viewing phylogenetic tree.
63
+The `r Biocpkg('ggtree')` package extends `r CRANpkg('ggplot2')` [@wickham_ggplot2_2009] package to support viewing phylogenetic tree.
65 64
 It implements `geom_tree` layer for displaying phylogenetic tree, as shown below:
66 65
 
67 66
 
... ...
@@ -102,6 +101,10 @@ for *phylogram* (by default) and *cladogram* if user explicitly setting
102 101
 *branch.length='none'*. Unrooted (equal angle and daylight methods), time-scaled
103 102
 and 2-dimensional layouts are also supported.
104 103
 
104
+
105
+## Phylogram and Cladogram
106
+
107
+
105 108
 ```{r eval=F}
106 109
 library(ggtree)
107 110
 set.seed(2017-02-16)
... ...
@@ -120,37 +123,68 @@ ggtree(tr, layout="daylight", branch.length = 'none')
120 123
 ```{r echo=F,  fig.width=8, fig.height=8, message=FALSE}
121 124
 library(ggtree)
122 125
 set.seed(2017-02-16)
123
-x <- rtree(50)
126
+tr <- rtree(50)
124 127
 library(cowplot)
125 128
 theme_layout <- theme(plot.title = element_text(hjust = 0.5))
126 129
 plot_grid(
127
-    ggtree(x) + ggtitle("rectangular (phylogram)")+ theme_layout,
128
-    ggtree(x, layout="slanted") + ggtitle("slanted (phylogram)")+theme_layout,
129
-    ggtree(x, layout="circular") + ggtitle("circular (phylogram)")+theme_layout,
130
-    ggtree(x, layout="fan", open.angle=120) + ggtitle("fan (phylogram)")+theme_layout,
131
-    ggtree(x, layout="equal_angle")+ ggtitle("equal angle (unrooted)")+theme_layout,
132
-    ggtree(x, layout="daylight")+ ggtitle("daylight (unrooted)")+theme_layout,
133
-    ggtree(x, branch.length='none')+ ggtitle("rectangular (cladogram)")+theme_layout,
134
-    ggtree(x, branch.length='none', layout='circular')+ ggtitle("circular (cladogram)")+theme_layout,
135
-    ggtree(x, layout="daylight", branch.length = 'none')+ ggtitle("daylight (cladogram)")+theme_layout,
130
+    ggtree(tr) + ggtitle("rectangular (phylogram)")+ theme_layout,
131
+    ggtree(tr, layout="slanted") + ggtitle("slanted (phylogram)")+theme_layout,
132
+    ggtree(tr, layout="circular") + ggtitle("circular (phylogram)")+theme_layout,
133
+    ggtree(tr, layout="fan", open.angle=120) + ggtitle("fan (phylogram)")+theme_layout,
134
+    ggtree(tr, layout="equal_angle")+ ggtitle("equal angle (unrooted)")+theme_layout,
135
+    ggtree(tr, layout="daylight")+ ggtitle("daylight (unrooted)")+theme_layout,
136
+    ggtree(tr, branch.length='none')+ ggtitle("rectangular (cladogram)")+theme_layout,
137
+    ggtree(tr, branch.length='none', layout='circular')+ ggtitle("circular (cladogram)")+theme_layout,
138
+    ggtree(tr, layout="daylight", branch.length = 'none')+ ggtitle("daylight (cladogram)")+theme_layout,
136 139
     ncol=3)
137 140
 ```
138 141
 
139 142
 
143
+There are also other possible layouts that can be drawed by modifying
144
+scales/coordination, for examples, reverse label of time
145
+scale^[https://github.com/GuangchuangYu/ggtree/issues/87], repropotion
146
+circular/fan tree
147
+^[https://groups.google.com/d/msgid/bioc-ggtree/6db25ec7-ffb1-4776-bfe4-4a1ba239c8e8%40googlegroups.com], *etc.*.
148
+
149
+```{r eval=FALSE}
150
+ggtree(tr) + scale_x_reverse()
151
+ggtree(tr) + coord_flip()
152
+ggtree(tr) + scale_x_reverse() + coord_flip()
153
+ggtree(tr, layout='slanted') + coord_flip()
154
+ggtree(tr, layout='slanted', branch.length='none') +
155
+    coord_flip() + scale_y_reverse() +scale_x_reverse()
156
+ggtree(tr, layout='circular') + xlim(-10, NA)
157
+ggtree(tr) + scale_x_reverse() + coord_polar(theta='y')
158
+ggtree(tr) + scale_x_reverse(limits=c(10, 0)) + coord_polar(theta='y')
159
+```
160
+
161
+```{r fig.width=8, fig.height = 4, echo=FALSE}
162
+plot_grid(
163
+    ggtree(tr) + scale_x_reverse(),
164
+    ggtree(tr) + coord_flip(),
165
+    ggtree(tr) + scale_x_reverse() + coord_flip(),
166
+    ggtree(tr, layout='slanted') + coord_flip(),
167
+    ggtree(tr, layout='slanted', branch.length='none') + coord_flip() + scale_y_reverse() +scale_x_reverse(),
168
+    ggtree(tr, layout='circular') + xlim(-10, NA),
169
+    ggtree(tr) + scale_x_reverse() + coord_polar(theta='y'),
170
+    ggtree(tr) + scale_x_reverse(limits=c(15, 0)) + coord_polar(theta='y'),
171
+    ncol = 4, labels = LETTERS[1:6])
172
+```
173
+
140 174
 
141 175
 
142 176
 ## Time-scaled tree
143 177
 
144
-A phylogenetic tree can be scaled by time (time-scaled tree) by specifying the parameter, `mrsd` (most recent sampling date).
178
+A phylogenetic tree can be scaled by time (time-scaled tree) by specifying the parameter, *mrsd* (most recent sampling date).
145 179
 
146
-```{r fig.width=9, fig.height=9, fig.align="center"}
180
+```{r fig.width=8, fig.height=4, fig.align="center"}
147 181
 tree2d <- read.beast(system.file("extdata", "twoD.tree", package="treeio"))
148 182
 ggtree(tree2d, mrsd = "2014-05-01") + theme_tree2()
149 183
 ```
150 184
 
151 185
 ## Two dimensional tree
152 186
 
153
-`ggtree` implemented two dimensional tree. It accepts parameter _`yscale`_ to scale the y-axis based on the selected tree attribute. The attribute should be numerical variable. If it is *character*/*category* variable, user should provides a name vector of mapping the variable to numeric by passing it to parameter _`yscale_mapping`_.
187
+`r Biocpkg('ggtree')` implemented two dimensional tree. It accepts parameter *yscale* to scale the y-axis based on the selected tree attribute. The attribute should be numerical variable. If it is *character*/*category* variable, user should provides a name vector of mapping the variable to numeric by passing it to parameter *yscale_mapping*.
154 188
 
155 189
 
156 190
 ```{r fig.width=9, fig.height=4, fig.align="center"}
... ...
@@ -175,35 +209,42 @@ ggtree(tree) + geom_treescale()
175 209
 
176 210
 `geom_treescale()` supports the following parameters:
177 211
 
178
-+ `x` and `y` for tree scale position
179
-+ `width` for the length of the tree scale
180
-+ `fontsize` for the size of the text
181
-+ `linesize` for the size of the line
182
-+ `offset` for relative position of the line and the text
183
-+ `color` for color of the tree scale
212
++ *x* and *y* for tree scale position
213
++ *width* for the length of the tree scale
214
++ *fontsize* for the size of the text
215
++ *linesize* for the size of the line
216
++ *offset* for relative position of the line and the text
217
++ *color* for color of the tree scale
184 218
 
185 219
 
186
-```{r fig.width=4, fig.height=4, fig.align="center"}
187
-ggtree(tree)+geom_treescale(x=0, y=12, width=6, color='red')
220
+```{r eval=F}
221
+ggtree(tree) + geom_treescale(x=0, y=12, width=6, color='red')
222
+ggtree(tree) + geom_treescale(fontsize=8, linesize=2, offset=-1)
188 223
 ```
189 224
 
190
-```{r fig.width=4, fig.height=4, fig.align="center"}
191
-ggtree(tree)+geom_treescale(fontsize=8, linesize=2, offset=-1)
225
+```{r fig.width=8, fig.height=4, fig.align="center", echo=F}
226
+plot_grid(
227
+    ggtree(tree)+geom_treescale(x=0, y=12, width=6, color='red'),
228
+    ggtree(tree)+geom_treescale(fontsize=8, linesize=2, offset=-1),
229
+    ncol = 2, labels = LETTERS[1:2])
192 230
 ```
193 231
 
194 232
 
195
-We can also use `theme_tree2()` to display the tree scale by adding `x axis`.
233
+We can also use `theme_tree2()` to display the tree scale by adding *x axis*.
234
+
196 235
 
197 236
 ```{r fig.width=3, fig.height=3, fig.align="center"}
198 237
 ggtree(tree) + theme_tree2()
199 238
 ```
200 239
 
201
-Tree scale is not restricted to evolution distance, `ggtree` can re-scale the tree with other numerical variable. More details can be found in the [Tree Annotation](treeAnnotation.html) vignette.
240
+
241
+Tree scale is not restricted to evolution distance, `r Biocpkg('ggtree')` can re-scale the tree with other numerical variable. More details can be found in the [Tree Annotation](treeAnnotation.html) vignette.
202 242
 
203 243
 
204 244
 # Displaying nodes/tips
205 245
 
206
-Showing all the internal nodes and tips in the tree can be done by adding a layer of points using _`geom_nodepoint`_,  _`geom_tippoint`_ or _`geom_point`_.
246
+Showing all the internal nodes and tips in the tree can be done by adding a layer of points using `geom_nodepoint`,  `geom_tippoint` or `geom_point`.
247
+
207 248
 
208 249
 ```{r fig.width=3, fig.height=3, fig.align="center"}
209 250
 ggtree(tree)+geom_point(aes(shape=isTip, color=isTip), size=3)
... ...
@@ -216,19 +257,32 @@ p + geom_tippoint(color="#FDAC4F", shape=8, size=3)
216 257
 
217 258
 ## Displaying labels
218 259
 
219
-Users can use _`geom_text`_ to display the node (if available) and tip labels simultaneously or `geom_tiplab` to only display tip labels:
260
+Users can use `geom_text` or `geom_label` to display the node (if available) and tip labels simultaneously or `geom_tiplab` to only display tip labels:
261
+
220 262
 
221 263
 ```{r fig.width=3, fig.height=3, warning=FALSE, fig.align="center"}
222 264
 p + geom_tiplab(size=3, color="purple")
223 265
 ```
224 266
 
225
-For _`circular`_ and _`unrooted`_ layout, `ggtree` supports rotating node labels according to the angles of the branches.
267
+`geom_tiplab` not only supports using *text* or *label* geom to display labels,
268
+it also supports *image* geom to label tip with image files. A corresponding
269
+geom, `geom_nodelab` is also provided for displaying node labels. For details of
270
+label nodes with images, please refer to
271
+the vignette,
272
+[Annotating phylogenetic tree with images](https://cran.r-project.org/web/packages/ggimage/vignettes/ggtree.html).
273
+
274
+
275
+
276
+For *circular* and *unrooted* layout, `r Biocpkg('ggtree')` supports rotating node labels according to the angles of the branches.
277
+
226 278
 
227 279
 ```{r fig.width=6, fig.height=6, warning=FALSE, fig.align="center"}
228 280
 ggtree(tree, layout="circular") + geom_tiplab(aes(angle=angle), color='blue')
229 281
 ```
230 282
 
231
-To make it more readable for human eye, `ggtree` provides a `geom_tiplab2` for `circular` layout (see post [1](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/bioc-ggtree/o35PV3iHO-0) and [2](https://groups.google.com/forum/#!topic/bioc-ggtree/p42R5l8J-14)).
283
+
284
+To make it more readable for human eye, `r Biocpkg('ggtree')` provides a `geom_tiplab2` for `circular` layout (see post [1](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/bioc-ggtree/o35PV3iHO-0) and [2](https://groups.google.com/forum/#!topic/bioc-ggtree/p42R5l8J-14)).
285
+
232 286
 
233 287
 ```{r fig.width=6, fig.height=6, warning=FALSE, fig.align="center"}
234 288
 ggtree(tree, layout="circular") + geom_tiplab2(color='blue')
... ...
@@ -236,12 +290,15 @@ ggtree(tree, layout="circular") + geom_tiplab2(color='blue')
236 290
 
237 291
 By default, the positions are based on the node positions, we can change them to based on the middle of the branch/edge.
238 292
 
293
+
239 294
 ```{r fig.width=4, fig.height=3, warning=FALSE, fig.align="center"}
240 295
 p + geom_tiplab(aes(x=branch), size=3, color="purple", vjust=-0.3)
241 296
 ```
242 297
 
298
+
243 299
 Based on the middle of branch is very useful when annotating transition from parent node to child node.
244 300
 
301
+
245 302
 # update tree view with a new tree
246 303
 
247 304
 In previous example, we have a _`p`_ object that stored the tree viewing of 13 tips and internal nodes highlighted with specific colored big dots. If users want to apply this pattern (we can imaging a more complex one) to a new tree, you don't need to build the tree step by step. `ggtree` provides an operator, _`%<%`_, for applying the visualization pattern to a new tree.
... ...
@@ -251,19 +308,28 @@ For example, the pattern in the _`p`_ object will be applied to a new tree with
251 308
 p %<% rtree(50)
252 309
 ```
253 310
 
254
-Another example can be found in the [Tree Data Import](treeImport.html#rst-file) vignette.
255
-
256 311
 # theme
257 312
 
258
-`theme_tree()` defined a totally blank canvas, while _`theme_tree2()`_ adds phylogenetic distance (via x-axis). These two themes all accept a parameter of _`bgcolor`_ that defined the background color.
313
+`theme_tree()` defined a totally blank canvas, while _`theme_tree2()`_ adds
314
+phylogenetic distance (via x-axis). These two themes all accept a parameter of
315
+_`bgcolor`_ that defined the background color. Users can pass
316
+any [theme components](http://ggplot2.tidyverse.org/reference/theme.html) to the
317
+`theme_tree()` function to modify them.
318
+
259 319
 
260
-```{r fig.width=6, fig.height=3, fig.align="center"}
320
+```{r eval=F}
321
+ggtree(rtree(30), color="red") + theme_tree("steelblue")
322
+ggtree(rtree(20), color="white") + theme_tree("black")
323
+```
324
+
325
+```{r fig.width=8, fig.height=3, fig.align="center", echo=F}
261 326
 cowplot::plot_grid(
262 327
     ggtree(rtree(30), color="red") + theme_tree("steelblue"),
263
-    ggtree(rtree(20), color="white") + theme_tree("black"),
328
+    ggtree(rtree(20), color="purple") + theme_tree("black"),
264 329
     ncol=2)
265 330
 ```
266 331
 
332
+
267 333
 # Visualize a list of trees
268 334
 
269 335
 `ggtree` supports `multiPhylo` object and a list of trees can be viewed simultaneously.