@@ -1,5 +1,6 @@

 CHANGES IN VERSION 1.3.8

 ------------------------

+ o update vignettes <2016-01-07, Thu>

  o 05 advance tree annotation vignette <2016-01-04, Mon>

  o export theme_inset <2016-01-04, Mon>

  o inset, nodebar, nodepie functions <2015-12-31, Thu>

@@ -77,7 +77,7 @@ ggtree <- function(tr,

                 branch.length = branch.length,

                 ndigits       = ndigits, ...)

-    p <- p + geom_tree(layout, ...) + xlab(NULL) + ylab(NULL) + theme_tree()

+    p <- p + geom_tree(layout, ...)  + theme_tree()

     if (type == "circular" || type == "radial") {

         p <- p + coord_polar(theta = "y")

@@ -9,6 +9,8 @@

 ##' @importFrom ggplot2 theme

 ##' @importFrom ggplot2 element_blank

 ##' @importFrom ggplot2 %+replace%

+##' @importFrom ggplot2 xlab

+##' @importFrom ggplot2 ylab

 ##' @export

 ##' @return updated ggplot object with new theme

 ##' @author Yu Guangchuang

@@ -17,12 +19,15 @@

 ##' tr <- rtree(10)

 ##' ggtree(tr) + theme_tree()

 theme_tree <- function(bgcolor="white", fgcolor="black", ...) {

-    theme_tree2() %+replace%

-    theme(panel.background=element_rect(fill=bgcolor, colour=bgcolor),

-          axis.line.x = element_blank(),

-          axis.text.x = element_blank(),

-          axis.ticks.x = element_blank(),

-          ...)

+    list(xlab(NULL),

+         ylab(NULL),

+	 theme_tree2_internal() %+replace%

+            theme(panel.background=element_rect(fill=bgcolor, colour=bgcolor),

+            axis.line.x = element_blank(),

+            axis.text.x = element_blank(),

+            axis.ticks.x = element_blank(),

+            ...)

+	 )

 }

 ##' tree2 theme

@@ -46,6 +51,13 @@ theme_tree <- function(bgcolor="white", fgcolor="black", ...) {

 ##' tr <- rtree(10)

 ##' ggtree(tr) + theme_tree2()

 theme_tree2 <- function(bgcolor="white", fgcolor="black", ...) {

+     list(xlab(NULL),

+          ylab(NULL),

+	  theme_tree2_internal(bgcolor, fgcolor, ...)

+	  )

+}

+

+theme_tree2_internal <- function(bgcolor="white", fgcolor="black", ...) {

     theme_bw() %+replace%

     theme(legend.position="none",

           panel.grid.minor=element_blank(),

@@ -42,23 +42,14 @@ To install:

 ## Documentation ##

-+ [viewing and annotating phylogenetic tree with ggtree](http://guangchuangyu.github.io/2014/12/viewing-and-annotating-phylogenetic-tree-with-ggtree/)

-+ [updating a tree view using %<% operator](http://guangchuangyu.github.io/2015/02/ggtree-updating-a-tree-view-using--operator/)

-+ [an example of drawing beast tree using ggtree](http://guangchuangyu.github.io/2015/04/an-example-of-drawing-beast-tree-using-ggtree/)

-+ [flip and rotate branches in ggtree](http://guangchuangyu.github.io/2015/07/flip-and-rotate-branches-in-ggtree/)

-+ [subsetting data in ggtree](http://guangchuangyu.github.io/2015/09/subsetting-data-in-ggtree/)

-+ [ggtree with funny fonts](http://guangchuangyu.github.io/2015/06/ggtree-with-funny-fonts/)

-+ [comic phylogenetic tree with ggtree and comicR](http://guangchuangyu.github.io/2015/09/comic-phylogenetic-tree-with-ggtree-and-comicr/)

-+ [embeding a subplot in ggplot via subview](http://guangchuangyu.github.io/2015/08/subview/)

-+ [annotate phylogenetic tree with local images](http://guangchuangyu.github.io/2015/08/ggtree-annotate-phylogenetic-tree-with-local-images/)

-+ [phylomoji with ggtree](http://guangchuangyu.github.io/2015/12/use-emoji-font-in-r/)

-

-

 To view the vignette of `ggtree` installed in your system, start `R` and enter:

 ```r

 vignette("ggtree", package = "ggtree")

 ```

+More documents can be found in <http://guangchuangyu.github.io/categories/ggtree>.

+

+

 ## Bugs/Feature requests ##

  - If you have any, [let me know](https://github.com/GuangchuangYu/ggtree/issues). Thx!

@@ -2,8 +2,8 @@

 	"tree": "(((((((A:4{1},B:4{2}):6{3},C:5{4}):8{5},D:6{6}):3{7},E:21{8}):10{9},((F:4{10},G:12{11}):14{12},H:8{13}):13{14}):13{15},((I:5{16},J:2{17}):30{18},(K:11{19},L:11{20}):2{21}):17{22}):4{23},M:56{24});",

 	"placements": [

 	{"p":[24, -61371.300778, 0.333344, 0.000003, 0.003887], "n":["AA"]},

-	{"p":[[1, -61312.210786, 0.333335, 0.000001, 0.000003],[2, -61312.210823, 0.333322, 0.000003, 0.000003],[550, -61312.210823, 0.333322, 0.000961, 0.000003]], "n":["BB"]},

-	{"p":[[8, -61312.229128, 0.200011, 0.000001, 0.000003],[9, -61312.229179, 0.200000, 0.000003, 0.000003],[10, -61312.229223, 0.199992, 0.000003, 0.000003]], "n":["CC"]}

+	{"p":[[1, -61312.210786, 0.333335, 0.000001, 0.000003],[2, -61322.210823, 0.333322, 0.000003, 0.000003],[550, -61352.210823, 0.333322, 0.000961, 0.000003]], "n":["BB"]},

+	{"p":[[8, -61312.229128, 0.200011, 0.000001, 0.000003],[9, -61322.229179, 0.200000, 0.000003, 0.000003],[10, -61342.229223, 0.199992, 0.000003, 0.000003]], "n":["CC"]}

 	],

 	"metadata": {"info": "sample file, without any meaning"},

 	"version" : 2,

@@ -35,8 +35,11 @@ library("ggtree")

 # Visualize tree with associated matrix

+<!--

 At first we implemented `gplot` function to visualize tree with heatmap but it has [an issue](https://github.com/GuangchuangYu/ggtree/issues/3) that it can't always guarantee the heatmap aligning to the tree properly, since the line up is between two figures and it's currently not supported internally by ggplot2. I have implemented another function `gheatmap` that can do the line up properly by creating a new layer above the tree.

+-->

+The `gheatmap` function is designed to visualize phylogenetic tree with heatmap of associated matrix.

 In the following example, we visualized a tree of H3 influenza viruses with their associated genotype.

@@ -51,12 +54,14 @@ p <- p + geom_tiplab(size=3)

 gheatmap(p, genotype, offset = 2, width=0.5)

 ```

-The _width_ parameter is to control the width of the heatmap. It supports another parameter _offset_ for controling the distance between the tree and the heatmap, for instance left space for tip labels.

+The _width_ parameter is to control the width of the heatmap. It supports another parameter _offset_ for controling the distance between the tree and the heatmap, for instance to allocate space for tip labels.

-For time scaled tree, as in this example, it's more often to use x axis by using `theme_tree2`. But with this solution, the heatmap is just another layer and will change the `x` axis. To overcome this issue, we implemented `scale_x_ggtree` to set the x axis more reasonable. User can also use `gplot` and tweak the positions of two plot to align properly.

+For time-scaled tree, as in this example, it's more often to use x axis by using `theme_tree2`. But with this solution, the heatmap is just another layer and will change the `x` axis. To overcome this issue, we implemented `scale_x_ggtree` to set the x axis more reasonable. 

-```{r fig.width=20, fig.height=16, fig.align="center"}

+<!-- User can also use `gplot` and tweak the positions of two plot to align properly. -->

+

+```{r fig.width=20, fig.height=16, fig.align="center", warning=FALSE}

 p <- ggtree(beast_tree, mrsd="2013-01-01") + geom_tiplab(size=3, align=TRUE) + theme_tree2()

 pp <- (p + scale_y_continuous(expand=c(0, 0.3))) %>%

     gheatmap(genotype, offset=4, width=0.5, colnames=FALSE) %>%

@@ -66,7 +71,7 @@ pp + theme(legend.position="right")

 # Visualize tree with multiple sequence alignment

-With `msaplot` function, user can visualizes multiple sequence alignment with phylogenetic tree, as demonstrated below:

+With `msaplot` function, user can visualize multiple sequence alignment with phylogenetic tree, as demonstrated below:

 ```{r fig.width=8, fig.height=12, fig.align='center'}

 fasta <- system.file("examples/FluA_H3_AA.fas", package="ggtree")

 msaplot(ggtree(beast_tree), fasta) 

@@ -74,10 +79,13 @@ msaplot(ggtree(beast_tree), fasta)

 A specific slice of the alignment can also be displayed by specific _window_ parameter.

+```{r fig.width=8, fig.height=12, fig.align='center'}

+msaplot(ggtree(beast_tree), fasta, window=c(150, 200)) 

+```

 # Annotate a phylogenetic with insets

-`ggtree` implemented a function, `subview`, that can add subplots into a ggplot2 object. It had successful applied to [plot pie graphs on map](http://stackoverflow.com/questions/10368180/plotting-pie-graphs-on-map-in-ggplot/32380396#32380396).

+`ggtree` implemented a function, `subview`, that can add subplots on a ggplot2 object. It had successful applied to [plot pie graphs on map](http://stackoverflow.com/questions/10368180/plotting-pie-graphs-on-map-in-ggplot/32380396#32380396).

 ```{r fig.width=8, fig.height=8, warning=F}

 set.seed(2016-01-04)

@@ -113,7 +121,7 @@ bars <- nodebar(dat, cols=1:4)

 inset(p, bars)

 ```

-The size of the inset can be ajusted by the paramter *width* and *height*.

+The sizes of the insets can be ajusted by the paramter *width* and *height*.

 ```{r}

 inset(p, bars, width=.03, height=.06)

@@ -190,8 +198,7 @@ d2$panel <- 'Stats'

 d1$panel <- factor(d1$panel, levels=c("Tree", "Stats"))

 d2$panel <- factor(d2$panel, levels=c("Tree", "Stats"))

-p <- ggplot(mapping=aes(x=x, y=y)) + facet_grid(.~panel, scale="free_x") +

-    xlab(NULL)+ylab(NULL)+theme_tree2()

+p <- ggplot(mapping=aes(x=x, y=y)) + facet_grid(.~panel, scale="free_x") + theme_tree2()

 p+geom_tree(data=d1) + geom_point(data=d2, aes(x=tipstats)) 

 ```

@@ -204,13 +211,13 @@ p+geom_tree(data=d1) + geom_point(data=d2, aes(x=tipstats))

 pp <- ggtree(tree) %>% phylopic("79ad5f09-cf21-4c89-8e7d-0c82a00ce728", color="steelblue", alpha = .3)

 print(pp)

 ```

-![](../inst/extdata/phylopic1.png)

+![](figures/phylopic1.png)

 ```{r fig.width=5, fig.height=5, fig.align="center", warning=FALSE, eval=FALSE}

 pp %>% phylopic("67382184-5135-4faa-8e98-eadff02c3e8a", color="#86B875", alpha=.8, node=4) %>%

      phylopic("d3563b54-780f-4711-a49a-7ea051e9dacc", color="darkcyan", alpha=.8, node=17, width=.2)

 ```

-![](../inst/extdata/phylopic2.png)

+![](figures/phylopic2.png)

 Annotate phylogenetic tree with local images is also supported, please refer to the [blog post](http://guangchuangyu.github.io/2015/08/ggtree-annotate-phylogenetic-tree-with-local-images/).

Binary files a/vignettes/figures/ggtree_objects.png and b/vignettes/figures/ggtree_objects.png differ

similarity index 100%

rename from inst/extdata/phylopic1.png

rename to vignettes/figures/phylopic1.png

similarity index 100%

rename from inst/extdata/phylopic2.png

rename to vignettes/figures/phylopic2.png

@@ -61,35 +61,15 @@ The `ggtree` is designed by extending the `ggplot2`[@wickham_ggplot2_2009] packa

 # Getting data into `R`

-Most of the tree viewer software (including `R` packages) focus on `Newick` and `Nexus` file format, while there are file formats from different evolution analysis software that contain supporting evidences within the file that are ready for annotating a phylogenetic tree.

-The `ggtree` package define several parser functions and `S4` classes to store statistical evidences inferred by commonly used software packages. It supports several file format, including:

-

-+ Newick (via `ape`)

-+ Nexus (via `ape`)

-+ New Hampshire eXtended format (NHX)

-+ Jplace

-

-and software output from:

-

-+ [BEAST](http://beast2.org/)[@bouckaert_beast_2014] 

-+ [EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011]

-+ [HYPHY](http://hyphy.org/w/index.php/Main_Page)[@pond_hyphy_2005]

-+ [PAML](http://abacus.gene.ucl.ac.uk/software/paml.html)[@yang_paml_2007]

-+ [PHYLDOG](http://pbil.univ-lyon1.fr/software/phyldog/)[@boussau_genome-scale_2013]

-+ [pplacer](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010]

-+ [r8s](http://loco.biosci.arizona.edu/r8s/)[@marazzi_locating_2012]

-+ [RAxML](http://sco.h-its.org/exelixis/web/software/raxml/)[@stamatakis_raxml_2014]

-+ [RevBayes](http://revbayes.github.io/intro.html)[@hohna_probabilistic_2014]

-

+Most of the tree viewer software (including `R` packages) focus on `Newick` and `Nexus` file format, while there are file formats from different evolution analysis software that contain supporting evidences within the file that are ready for annotating a phylogenetic tree. In addition to `Newick` and `Nexus`, ggtree supports `NHX` and `jplace` file formats. `ggtree` also supports software outputs from [BEAST](http://beast2.org/)[@bouckaert_beast_2014], [EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011], [HYPHY](http://hyphy.org/w/index.php/Main_Page)[@pond_hyphy_2005], [PAML](http://abacus.gene.ucl.ac.uk/software/paml.html)[@yang_paml_2007], [PHYLDOG](http://pbil.univ-lyon1.fr/software/phyldog/)[@boussau_genome-scale_2013], [pplacer](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010], [r8s](http://loco.biosci.arizona.edu/r8s/)[@marazzi_locating_2012], [RAxML](http://sco.h-its.org/exelixis/web/software/raxml/)[@stamatakis_raxml_2014] and [RevBayes](http://revbayes.github.io/intro.html)[@hohna_probabilistic_2014].

 Parsing data from a number of molecular evolution software is not only for visualization in `ggtree`, but also bring these data to `R` users for further analysis (e.g. summarization, visualization, comparision, test, _etc_).

 For more details, please refer to [Tree Data Import](treeImport.html) vignette.

-

 # Tree Visualization and Annotation

-Tree Visualization in `ggtree` is easy, with one line of command `ggtree(tree_object)`. It supports several layout, including `rectangular`, `slanted` and `circular` for `Phylogram` and `Cladogram`, `unrooted` layout, time-scaled and two dimentional phylogenies. [Tree Visualization](treeVisualization.html) vignette describe these feature in details.

+Tree Visualization in `ggtree` is easy, with one line of command `ggtree(tree_object)`. It supports several layouts, including `rectangular`, `slanted` and `circular` for `Phylogram` and `Cladogram`, `unrooted` layout, time-scaled and two dimentional phylogenies. [Tree Visualization](treeVisualization.html) vignette describes these feature in details.

 We implement several functions to manipulate a phylogenetic tree.

@@ -105,13 +85,13 @@ Details and examples can be found in [Tree Manipulation](treeManipulation.html)

 Most of the phylogenetic trees are scaled by evolutionary distance (substitution/site), in `ggtree` a phylogenetic tree can be re-scaled by any numerical variable inferred by evolutionary analysis (e.g. species divergence time, *dN/dS*, _etc_). Numerical and category variable can be used to color a phylogenetic tree.

-The `ggtree` package provides several layers to annotate a phylogenetic tree, including `geom_treescale` for adding a legend of tree scale, `geom_hilight` for highlighting selected clades and `geom_cladelabel` for labelling selected clades.

+The `ggtree` package provides several layers to annotate a phylogenetic tree, including `geom_tiplab` for adding tip labels, `geom_treescale` for adding a legend of tree scale, `geom_hilight` for highlighting selected clades and `geom_cladelabel` for labelling selected clades. 

-It supports annotating phylogenetic trees with analyses by R packages and other commonly used evolutionary software. User's specific annotation (e.g. experimental data) can be integrated to annotate phylogenetic tree. `ggtree` provides `write.jplace` function to combine Newick tree file and user's own data to a single `jplace` file that can be parsed and the data can be used to annotate the tree directly in `ggtree`.

+It supports annotating phylogenetic trees with analyses obtained from R packages and other commonly used evolutionary software. User's specific annotation (e.g. experimental data) can be integrated to annotate phylogenetic trees. `ggtree` provides `write.jplace` function to combine Newick tree file and user's own data to a single `jplace` file that can be parsed and the data can be used to annotate the tree directly in `ggtree`.

 `ggtree` integrates `phylopic` database and silhouette images of organisms can be downloaded and used to annotate phylogenetic directly. `ggtree` also supports using local images to annotate a phylogenetic tree.

-Visualizing an annotated phylogenetic tree with numerical matrix (e.g. genotype table) and multiple sequence alignment is also supported in `ggtree`. Examples of annotating phylogenetic trees can be found in the [Tree Annotation](treeAnnotation.html) vignette.

+Visualizing an annotated phylogenetic tree with numerical matrix (e.g. genotype table), multiple sequence alignment and subplots are also supported in `ggtree`. Examples of annotating phylogenetic trees can be found in the [Tree Annotation](treeAnnotation.html) and [Advance Tree Annotation](advanceTreeAnnotation.html) vignettes.

 # Vignette Entry

@@ -122,11 +102,12 @@ Visualizing an annotated phylogenetic tree with numerical matrix (e.g. genotype

 + [Tree Annotation](treeAnnotation.html)

 + [Advance Tree Annotation](advanceTreeAnnotation.html)

+More documents can be found in <http://guangchuangyu.github.io/categories/ggtree>.

+

 # Bugs/Feature requests

 If you have any, [let me know](https://github.com/GuangchuangYu/ggtree/issues). Thx!

-

 # Session info

 Here is the output of `sessionInfo()` on the system on which this document was compiled:

@@ -37,7 +37,7 @@ library("gridExtra")

 # Rescale tree

-Most of the phylogenetic trees are scaled by evolutionary distance (substitution/site), in `ggtree`, we can re-scale a phylogenetic tree by any numerical variable inferred by evolutionary analysis (e.g. *dN/dS*).

+Most of the phylogenetic trees are scaled by evolutionary distance (substitution/site), in `ggtree`, users can re-scale a phylogenetic tree by any numerical variable inferred by evolutionary analysis (e.g. *dN/dS*).

 ```{r fig.width=10, fig.height=5}

@@ -96,7 +96,8 @@ ggtree(beast_tree, aes(color=rate)) +

 User can use any feature (if available), including clade posterior and *dN/dS* _etc._, to scale the color of the tree.

 ## Annotate clades

-`ggtree` implements _`geom_cladelabel`_ layer to annotate a selected clade with a bar indicating that clade with a corresponding label.

+

+`ggtree` implements _`geom_cladelabel`_ layer to annotate a selected clade with a bar indicating the clade with a corresponding label.

 The _`geom_cladelabel`_ layer accepts a selected internal node number. To get the internal node number, please refer to [Tree Manipulation](treeManipulation.html#internal-node-number) vignette.

@@ -110,35 +111,35 @@ p+geom_cladelabel(node=45, label="test label") +

     geom_cladelabel(node=34, label="another clade") 

 ```

-We can set the parameter, `align = TRUE`, to align the clade label, and use the parameter, `offset`, to adjust the position.

+Users can set the parameter, `align = TRUE`, to align the clade label, and use the parameter, `offset`, to adjust the position.

 ```{r}

 p+geom_cladelabel(node=45, label="test label", align=TRUE, offset=.5) +

     geom_cladelabel(node=34, label="another clade", align=TRUE, offset=.5)

 ```

-We can change the color of the clade label via the parameter `color`.

+Users can change the color of the clade label via the parameter `color`.

 ```{r}

 p+geom_cladelabel(node=45, label="test label", align=T, color='red') +

     geom_cladelabel(node=34, label="another clade", align=T, color='blue')

 ```

-We can change the `angle` of the clade label text and the relative position from text to bar via the parameter `offset.text`.

+Users can change the `angle` of the clade label text and relative position from text to bar via the parameter `offset.text`.

 ```{r}

 p+geom_cladelabel(node=45, label="test label", align=T, angle=270, hjust='center', offset.text=.5) +

     geom_cladelabel(node=34, label="another clade", align=T, angle=45) 

 ```

-We can change the size of the bar and text via the parameters `barsize` and `fontsize` respectively.

+The size of the bar and text can be changed via the parameters `barsize` and `fontsize` respectively.

 ```{r}

 p+geom_cladelabel(node=45, label="test label", align=T, angle=270, hjust='center', offset.text=.5, barsize=1.5) +

     geom_cladelabel(node=34, label="another clade", align=T, angle=45, fontsize=8) 

 ```

-We can also use `geom_label` to label the text.

+Users can also use `geom_label` to label the text.

 ```{r}

 p+ geom_cladelabel(node=34, label="another clade", align=T, geom='label', fill='lightblue') 

@@ -146,7 +147,7 @@ p+ geom_cladelabel(node=34, label="another clade", align=T, geom='label', fill='

 # Highlight clades

-`ggtree` implements _`geom_hilight`_ layer, that an internal node number and add a layer of rectangle to highlight the selected clade.

+`ggtree` implements _`geom_hilight`_ layer, that accepts an internal node number and add a layer of rectangle to highlight the selected clade.

 ```{r fig.width=5, fig.height=5, fig.align="center", warning=FALSE}

 nwk <- system.file("extdata", "sample.nwk", package="ggtree")

@@ -214,18 +215,16 @@ In `ggtree`, we implemented several parser functions to parse output from common

 + [RAxML](http://sco.h-its.org/exelixis/web/software/raxml/)[@stamatakis_raxml_2014]

 + [RevBayes](http://revbayes.github.io/intro.html)[@hohna_probabilistic_2014]

-Evolutionary evidences inferred by these software packages can be used for further analysis in `R` and annotate phylogenetic tree directly in `ggtree`. For more details, please refer to the [Tree Data Import](treeImport.html) vignette.

+Evolutionary evidences inferred by these software packages can be used for further analysis in `R` and annotating phylogenetic tree directly in `ggtree`. For more details, please refer to the [Tree Data Import](treeImport.html) vignette.

 # Tree annotation with user specific annotation

 ## the `%<+%` operator

-We provides several functions to parse and store information from common software output.

-

-Here, we would like to demonstrate how to inject user specific annotation data in a tree.

+In addition to parse commonly used software output, `ggtree` also supports annotating a phylogenetic tree using user's own data.

-Suppose we have the following data that associated with the tree and would like to attach the data in the tree.

+Suppose we have the following data that associate with the tree and would like to attach the data in the tree.

 ```{r}

 nwk <- system.file("extdata", "sample.nwk", package="ggtree")

@@ -233,7 +232,7 @@ tree <- read.tree(nwk)

 p <- ggtree(tree)

 dd <- data.frame(taxa  = LETTERS[1:13], 

-      		 place = c(rep("GZ", 5), rep("HK", 3), rep("CZ", 4), NA),

+                 place = c(rep("GZ", 5), rep("HK", 3), rep("CZ", 4), NA),

                  value = round(abs(rnorm(13, mean=70, sd=10)), digits=1))

 ## you don't need to order the data

 ## data was reshuffled just for demonstration

@@ -248,38 +247,32 @@ print(dd)

 knitr::kable(dd)

 ```

-We can imaging that the _`place`_ column is the place we isolated the species and _`value`_ column stored numerical values for example bootstrap values.

+We can imaging that the _`place`_ column stores the location we isolated the species and _`value`_ column stores numerical values (e.g. bootstrap values).

-We have shown using the operator, _`%<%`_, to update a tree view with a new tree. Here, we will introduce another operator, _`%<+%`_, that attaches annotation data to a tree view. The only requirement of the input data is that its first column should be matched with the node/tip labels of the tree.

+We have demonstrated using the operator, _`%<%`_, to update a tree view with a new tree. Here, we will introduce another operator, _`%<+%`_, that attaches annotation data to a tree view. The only requirement of the input data is that its first column should be matched with the node/tip labels of the tree.

-After attaching the annotation data to the tree by _`%<+%`_, all the columns in the data are visible to _`ggplot2`_. As an example, here we attach the above annotation data to the tree view, _`p`_, and add a layer that showing the tip labels and colored them by the isolation site stored in _`place`_ column.

+After attaching the annotation data to the tree by _`%<+%`_, all the columns in the data are visible to _`ggtree`_. As an example, here we attach the above annotation data to the tree view, _`p`_, and add a layer that showing the tip labels and colored them by the isolation site stored in _`place`_ column.

 ```{r fig.width=6, fig.height=5, warning=FALSE, fig.align="center"}

-p <- p %<+% dd + geom_text(aes(color=place, label=label), hjust=-0.5) + 

+p <- p %<+% dd + geom_tiplab(aes(color=place)) + 

        geom_tippoint(aes(size=value, shape=place, color=place), alpha=0.25)

 p+theme(legend.position="right")

 ```

-Once the data was attached, it is always attached. So we can add another layer to display the isolation sites easily.

-```{r fig.width=6, fig.height=5, warning=FALSE, fig.align="center"}

-p <- p + geom_text(aes(color=place, label=place), hjust=1, vjust=-0.4, size=3)

-print(p)

-```

-

-And another layer showing numerical values:

+Once the data was attached, it is always attached. So that we can add other layers to display these information easily. 

 ```{r fig.width=6, fig.height=5, warning=FALSE, fig.align="center"}

-p <- p + geom_text(aes(color=place, label=value), hjust=1, vjust=1.4, size=3)

-print(p)

+p + geom_text(aes(color=place, label=place), hjust=1, vjust=-0.4, size=3) +

+  geom_text(aes(color=place, label=value), hjust=1, vjust=1.4, size=3)

 ```

 ## jplace file format

-In `ggtree`, we provide `write.jplace` function to store user's own data and associated newick tree to a single `jplace` file, which can be parsed directly in `ggtree` and user's data can be used to annotate the tree directly. For more detail, please refer to the [Tree Data Import](treeImport.html#jplace-file-format) vignette.

+`ggtree` provides `write.jplace()` function to store user's own data and associated newick tree to a single `jplace` file, which can be parsed directly in `ggtree` and user's data can be used to annotate the tree directly. For more detail, please refer to the [Tree Data Import](treeImport.html#jplace-file-format) vignette.

 # Advance tree annotation

-Advance tree annotation including visualizing tree with associated matrix, multiple sequence alignment, subplots and images (especially PhyloPic). For details and examples, please refer to the [Advance Tree Annotation](advanceTreeAnnotation.html) vignette.

+Advance tree annotation including visualizing phylogenetic tree with associated matrix and multiple sequence alignment; annotating tree with subplots and images (especially PhyloPic). For details and examples, please refer to the [Advance Tree Annotation](advanceTreeAnnotation.html) vignette.

 # References

@@ -33,7 +33,7 @@ library("ggtree")

 ```

-The `ggtree` package should not be viewed solely as a standalone software. While it is useful for viewing, annotating and manipulating phylogenetic trees, it is also an infrastructure that enables evolutionary evidences that inferred by commonly used software packages in the field to be used in `R`. For instance, *dN/dS* values or ancestral sequences inferred by [CODEML](http://abacus.gene.ucl.ac.uk/software/paml.html)[@yang_paml_2007], *clade support values (posterior)* inferred by [BEAST](http://beast2.org/)[@bouckaert_beast_2014] and short read placement by [EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011] and [pplacer](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010]. These evolutionary evidences are not only used in annotating phylogenetic tree in  `ggtree` but can also be further analyzed in `R`.

+The `ggtree` package should not be viewed solely as a standalone software. While it is useful for viewing, annotating and manipulating phylogenetic trees, it is also an infrastructure that enables evolutionary evidences that inferred by commonly used software packages in the field to be used in `R`. For instance, *dN/dS* values or ancestral sequences inferred by [CODEML](http://abacus.gene.ucl.ac.uk/software/paml.html)[@yang_paml_2007], clade support values (posterior) inferred by [BEAST](http://beast2.org/)[@bouckaert_beast_2014] and short read placement by [EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011] and [pplacer](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010]. These evolutionary evidences are not only used in annotating phylogenetic tree in  `ggtree` but can also be further analyzed in `R`.

 # Supported File Formats

@@ -66,14 +66,14 @@ The `ggtree` package implement several parser functions, including:

 + `read.codeml_mlc` for parsing `mlc` file (output of `CODEML`)

 + `read.hyphy` for parsing output of [HYPHY](http://hyphy.org/w/index.php/Main_Page)

 + `read.jplace` for parsing `jplace` file including output from [EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html) and [pplacer](http://matsen.fhcrc.org/pplacer/)

-+ `read.nhx` for parsing `NHX` file including output from [PHYLODOG](http://pbil.univ-lyon1.fr/software/phyldog/) and RevBayes](http://revbayes.github.io/intro.html)

++ `read.nhx` for parsing `NHX` file including output from [PHYLODOG](http://pbil.univ-lyon1.fr/software/phyldog/) and [RevBayes](http://revbayes.github.io/intro.html)

 + `read.paml_rst` for parsing `rst` file (output of `BASEML` and `CODEML`)

 + `read.r8s` for parsing output of [r8s](loco.biosci.arizona.edu/r8s/)

 + `read.raxml` for parsing output of [RAxML](http://sco.h-its.org/exelixis/web/software/raxml/)

 # S4 classes

-Correspondingly, `ggtree` define several `S4` classes to store evolutionary evidences inferred by these software packages, including:

+Correspondingly, `ggtree` defines several `S4` classes to store evolutionary evidences inferred by these software packages, including:

 + _`apeBootstrap`_ for bootstrap analysis of `ape::boot.phylo()`[@paradis_ape_2004], output of `apeBoot()` defined in `ggtree`

 + _`beast`_ for storing output of `read.beast()`

@@ -82,7 +82,7 @@ Correspondingly, `ggtree` define several `S4` classes to store evolutionary evid

 + _`hyphy`_ for storing output of `read.hyphy()`

 + _`jplace`_ for storing output of `read.jplace()`

 + _`nhx`_ for storing output of `read.nhx()`

-+ _`paml_rst`_ for _`rst`_ file obtained by [PAML], including _`BASEML`_ and _`CODEML`_.

++ _`paml_rst`_ for _`rst`_ file obtained by [PAML](http://abacus.gene.ucl.ac.uk/software/paml.html), including _`BASEML`_ and _`CODEML`_.

 + _`phangorn`_ for storing ancestral sequences inferred by `R` package `phangorn`[@schliep_phangorn_2011], output of `phyPML()` defined in `ggtree`

 + _`r8s`_ for storing output of `read.r8s()`

 + _`raxml`_ for storing output of `read.raxml()`

@@ -95,7 +95,7 @@ Here is an overview of these `S4` classes:

 ![](figures/ggtree_objects.png)

-In addition, `ggtree` also supports _`phylo`_ (defined by `ape`[@paradis_ape_2004]) and _`phylo4`_ (defined by `phylobase`).

+In addition, `ggtree` also supports _`phylo`_, _`multiPhylo`_ (defined by `ape`[@paradis_ape_2004]) and _`phylo4`_ (defined by `phylobase`).

 In `ggtree`, tree objects can be merged and evidences inferred from different phylogenetic analyses can be combined or compared and visualized.

@@ -128,11 +128,11 @@ get.fields(beast)

 Users can use `ggtree(beast)` to visualize the tree and add layer to annotate it.

-```{r warning=FALSE}

+```{r warning=FALSE, fig.width=10, fig.height=10}

 ggtree(beast, ndigits=2, branch.length = 'none') + geom_text(aes(x=branch, label=length_0.95_HPD), vjust=-.5, color='firebrick')

 ```

-With `ggtree`, evolutionary evidences inferred by commonly used software packages (`BEAST` in this example) can be easily obtained in a tidy `data.frame` by `fortify` method.

+With `ggtree`, evolutionary evidences inferred by commonly used software packages (`BEAST` in this example) can be easily transformed to a tidy `data.frame` by `fortify` method.

 ```{r}

 beast_data <- fortify(beast)

@@ -145,7 +145,7 @@ head(beast_data)

 The _`read.paml_rst`_ function can parse `rst` file from `BASEML` and `CODEML`. The only difference is the space in the sequences. For `BASEML`, each ten bases are separated by one space, while for `CODEML`, each three bases (triplet) are separated by one space.

-```{r fig.width=8, width=60, warning=FALSE, fig.align="center"}

+```{r fig.width=12, fig.height=10, warning=FALSE, fig.align="center"}

 brstfile <- system.file("extdata/PAML_Baseml", "rst", package="ggtree")

 brst <- read.paml_rst(brstfile)

 brst

@@ -163,9 +163,9 @@ crst

 ```

-In `ggtree`, we define the `update` operator, `%<%`, that can update a tree view (applying the same pattern of visualization and annotation) with another tree object.

+`ggtree` defines the `update` operator, `%<%`, that can update a tree view (applying the same pattern of visualization and annotation) with another tree object.

-```{r fig.width=8, width=60, warning=FALSE, fig.align="center"}

+```{r fig.width=12, fig.height=10, warning=FALSE, fig.align="center"}

 p %<% crst

 ```

@@ -189,7 +189,7 @@ Please aware that _`/`_ and _`*`_ are not valid characters in _`names`_, they we

 So _`dN_vs_dS`_ is _`dN/dS`_, _`N_x_dN`_ is _`N*dN`_, and _`S_x_dS`_ is _`S*dS`_.

-```{r fig.width=8, width=60, warning=FALSE, fig.align="center"}

+```{r fig.width=8, fig.height=8, warning=FALSE, fig.align="center"}

 ggtree(mlc) + geom_text(aes(x=branch, label=dN_vs_dS), color='blue', vjust=-.2)

 ```

@@ -207,9 +207,7 @@ ggtree(mlc, branch.length = "dN_vs_dS", aes(color=dN_vs_dS)) +

     theme_tree2(legend.position=c(.9, .5))

 ```

-We can also plot the _`dN`_ or _`dS`_ tree and others. 

-

-#### rst and mlc files

+We can also plot the _`dN`_ or _`dS`_ tree and others. More examples (including evidences inferred by BEAST) can be found in the [Tree Annotation](treeAnnotation.html) vignette.  

 #### _`CODEML`_ output: rst and mlc files\

@@ -239,7 +237,7 @@ hy <- read.hyphy(nwk, ancseq, tipfas)

 hy

 ```

-```{r fig.width=12, fig.height=10, width=60, warning=FALSE, fig.align="center"}

+```{r fig.width=14, fig.height=10, warning=FALSE, fig.align="center"}

 ggtree(hy) + geom_text(aes(x=branch, label=AA_subs), vjust=-.5)

 ```

@@ -248,7 +246,7 @@ ggtree(hy) + geom_text(aes(x=branch, label=AA_subs), vjust=-.5)

 [r8s](http://loco.biosci.arizona.edu/r8s/) output contains 3 trees, namely `TREE`, `RATO` and `PHYLO` for time tree, rate tree and absolute substitution tree respectively.

-```{r fig.width=4, fig.height=6, width=60, warning=FALSE, fig.align="center")

+```{r fig.width=4, fig.height=6, width=60, warning=FALSE, fig.align="center"}

 r8s <- read.r8s(system.file("extdata/r8s", "H3_r8s_output.log", package="ggtree"))

 ggtree(r8s, branch.length="TREE", mrsd="2014-01-01") + theme_tree2()

 ```

@@ -259,7 +257,7 @@ ggtree(r8s, branch.length="TREE", mrsd="2014-01-01") + theme_tree2()

 User can also view 3 trees simultaneously.

-```{r fig.width=16, fig.height=10, width=60, warning=FALSE, fig.align="center")

+```{r fig.width=16, fig.height=10, width=60, warning=FALSE, fig.align="center"}

 ggtree(get.tree(r8s), aes(color=.id)) + facet_wrap(~.id, scales="free_x")

 ```

@@ -289,7 +287,7 @@ ggtree(nhx) + geom_tiplab() + geom_point(aes(color=S), size=5, alpha=.5) +

 ## Parsing EPA and pplacer output

-[EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011] and [PPLACER](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010] have common output file format, `jplace`. 

+[EPA](http://sco.h-its.org/exelixis/web/software/epa/index.html)[@berger_EPA_2011] and [PPLACER](http://matsen.fhcrc.org/pplacer/)[@matsen_pplacer_2010] have common output file format, `jplace`, which can be parse by `read.jplace()` function. 

 ```{r}

 jpf <- system.file("extdata/sample.jplace",  package="ggtree")

@@ -340,13 +338,13 @@ merged_tree

 head(fortify(merged_tree))

 ```

-After merging, all evidences inferred from different tools can be used to annotate the tree simultaneously. In this example, we used 'dN/dS' inferred by CodeML to color the tree and annotate the tree with 'posterior' inferred by BEAST.

+After merging, all evidences inferred from different tools can be used to annotate the tree simultaneously. In this example, we used `dN/dS` inferred by CodeML to color the tree and annotate the tree with `posterior` inferred by BEAST.

 ```{r fig.width=20, fig.height=26, warning=FALSE}

-ggtree(merged_tree, aes(color=dN), mrsd="2013-01-01", ndigits = 3) +

+ggtree(merged_tree, aes(color=dN_vs_dS), mrsd="2013-01-01", ndigits = 3) +

     geom_text(aes(label=posterior), vjust=.1, hjust=-.1, size=5, color="black") + 

     scale_color_continuous(name='dN/dS', limits=c(0, 1.5),

-                           oob=scales::squish, low="darkgreen", high="red")+

+                           oob=scales::squish, low="green", high="red")+

     theme_tree2(legend.position="right")

 ```	

@@ -370,13 +368,13 @@ outfile <- tempfile()

 write.jplace(tree, data, outfile)

 ```

-Then _`read.jplace`_ function was designed to read the _`jplace`_ file and store the information to a _`jplace`_ object.

+The _`read.jplace`_ function was designed to read the _`jplace`_ file and store the information to a _`jplace`_ object.

 ```{r}

 jp <- read.jplace(outfile)

 print(jp)

 ```

-Now we know the _`jp`_ object stored the tree and the associated amino acid substitution and GC content information, we can view the tree and display the associated annotation data on it directly by _`ggtree`_.

+Now we know the _`jp`_ object that stores the tree and the associated amino acid substitution and GC content information, we can view the tree and display the associated annotation data on it directly by _`ggtree`_.

 ```{r fig.width=12, fig.height=12, warning=FALSE, fig.align="center"}

 ggtree(jp) + 

@@ -37,7 +37,7 @@ expand <- ggtree::expand

 # Internal node number

-Some of the functions works with clade and accepts a parameter of internal node number. To get the internal node number, user can use `geom_text2` to display it:

+Some of the functions in `ggtree` works with clade and accepts a parameter of internal node number. To get the internal node number, user can use `geom_text2` to display it:

 ```{r}

 nwk <- system.file("extdata", "sample.nwk", package="ggtree")

@@ -56,7 +56,7 @@ p <- ggtree(tree)

 MRCA(p, tip=c('A', 'E'))

 ```

-# groupClade

+# group Clades

 The `ggtree` package defined several functions to manipulate tree view. _`groupClade`_ and _`groupOTU`_ methods for clustering clades or related OTUs. _`groupClade`_ accepts an internal node or a vector of internal nodes to cluster clade/clades.

@@ -78,7 +78,7 @@ With `groupClade` and `groupOTU`, it's easy to highlight selected taxa and easy

 ```{r fig.width=5, fig.height=5, fig.align="center", warning=FALSE}

 tree <- groupClade(tree, node=c(21, 17))

-ggtree(tree, aes(color=group, linetype=group)) + geom_text2(aes(subset=(group==2), label=label), hjust=-.5)

+ggtree(tree, aes(color=group, linetype=group)) + geom_tiplab(aes(subset=(group==2)))

 ```

@@ -104,16 +104,20 @@ cls <- list(c1=c("A", "B", "C", "D", "E"),

 tree <- groupOTU(tree, cls)

 library("colorspace")

-ggtree(tree, aes(color=group, linetype=group)) + geom_text(aes(label=label),  hjust=-.25) +

+ggtree(tree, aes(color=group, linetype=group)) + geom_tiplab() +

      scale_color_manual(values=c("black", rainbow_hcl(4))) + theme(legend.position="right")

 ```

+_`groupOTU`_ also work with graphic object.

+

 ```{r fig.width=5, fig.height=5, fig.align="center", warning=FALSE}

 p <- ggtree(tree)

 groupOTU(p, LETTERS[1:5]) + aes(color=group) + geom_tiplab() + scale_color_manual(values=c("black", "firebrick"))

 ```

+The following example use `groupOTU` to display taxa classification.

+

 ```{r fig.width=14, fig.height=14}

 library("ape")

 data(chiroptera)

@@ -179,7 +183,7 @@ grid.arrange(p1, p2, p3, p4, p5, ncol=5)

 # scale clade

-We have illustrated how to collapse selected clades. Another approach is to zoom out clade to a small scale.

+Collpase selected clades can save some space, another approach is to zoom out clade to a small scale.

 ```{r fig.width=12, fig.height=6, warning=F}

 grid.arrange(ggtree(tree) + geom_hilight(21, "steelblue"),

@@ -48,7 +48,7 @@ It implements _`geom_tree`_ layer for displaying phylogenetic trees, as shown be

 ```{r fig.width=3, fig.height=3, fig.align="center"}

-ggplot(tree, aes(x, y)) + geom_tree() + theme_tree() + xlab(NULL) + ylab(NULL)

+ggplot(tree, aes(x, y)) + geom_tree() + theme_tree()

 ```

 The function, _`ggtree`_, was implemented as a short cut to visualize a tree, and it works exactly the same as shown above.

@@ -58,12 +58,12 @@ _`ggtree`_ takes all the advantages of _`ggplot2`_. For example, we can change t

 ggtree(tree, color="firebrick", size=1, linetype="dotted")

 ```

-By default, the tree is viewing in ladderize form, user can set the parameter _`ladderize = FALSE`_ to disable it.

+By default, the tree is viewed in ladderize form, user can set the parameter _`ladderize = FALSE`_ to disable it.

 ```{r fig.width=3, fig.height=3, fig.align="center"}

 ggtree(tree, ladderize=FALSE)

 ```

-The _`branch.length`_ is used to scale the edge, user can set the parameter _`branch.length = "none"`_ to only viewing the tree topology (cladogram) or other numerical variable to scale the tree (e.g. _dN/dS_).

+The _`branch.length`_ is used to scale the edge, user can set the parameter _`branch.length = "none"`_ to only view the tree topology (cladogram) or other numerical variable to scale the tree (e.g. _dN/dS_, see also in [Tree Annotation](treeAnnotation.html) vignette).

 ```{r fig.width=3, fig.height=3, fig.align="center"}

 ggtree(tree, branch.length="none")

@@ -71,14 +71,14 @@ ggtree(tree, branch.length="none")

 # Layout

-Currently, _`ggtree`_ supports several layout, including:

+Currently, _`ggtree`_ supports several layouts, including:

 + `rectangular` (by default)

 + `slanted`

 + `fan` or `circular`

-for `Phylogram` (by default).

-`Cladogram` if user explicitly setting `branch.length='none'` and `unrooted` layout are also supported. 

+for `Phylogram` (by default) and `Cladogram` if user explicitly setting `branch.length='none'`.

+`ggtree` also supports `unrooted` layout.

 ## Phylogram

@@ -133,14 +133,14 @@ ggtree(tree, layout="unrooted") + ggtitle("unrooted layout")

 A phylogenetic tree can be scaled by time (time-scaled tree) by specifying the parameter, `mrsd` (most recent sampling date).

-```{r fig.width=9, fig.height=4, fig.align="center"}

+```{r fig.width=9, fig.height=9, fig.align="center"}

 tree2d <- read.beast(system.file("extdata", "twoD.tree", package="ggtree"))

 ggtree(tree2d, mrsd = "2014-05-01") + theme_tree2()

 ```

 ## Two dimensional tree

-`ggtree` implemented 2 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`_.

+`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`_.

 ```{r fig.width=9, fig.height=4, fig.align="center"}

@@ -188,9 +188,12 @@ We can also use `theme_tree2()` to display the tree scale by adding `x axis`.

 ggtree(tree) + theme_tree2()

 ```

+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.

+

+

 # Displaying nodes/tips

-Show 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`_.

+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`_.

 ```{r fig.width=3, fig.height=3, fig.align="center"}

 ggtree(tree)+geom_point(aes(shape=isTip, color=isTip), size=3)

@@ -223,9 +226,9 @@ p + geom_tiplab(aes(x=branch), size=3, color="purple", vjust=-0.3)

 Based on the middle of branch is very useful when annotating transition from parent node to child node.

-# update tree viewing with a new tree

+# update tree view with a new tree

-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 applied 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.

+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.

 For example, the pattern in the _`p`_ object will be applied to a new tree with 50 tips as shown below:

 ```{r fig.width=3, fig.height=3, fig.align="center"}

@@ -236,7 +239,7 @@ Another example can be found in the [Tree Data Import](treeImport.html#rst-file)

 # theme

-`theme_tree()` defined a totally blank canvas, while _`theme_tree2()`_ add phylogenetic distance (via x-axis). These two themes all accept a parameter of _`bgcolor`_ that defined the background color.

+`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.

 ```{r fig.width=6, fig.height=3, fig.align="center"}

 grid.arrange(