@@ -1,20 +1,19 @@

 Package: ggtree

 Type: Package

 Title: a phylogenetic tree viewer for different types of tree annotations

-Version: 1.3.6

+Version: 1.3.7

 Author: Guangchuang Yu and Tommy Tsan-Yuk Lam

 Maintainer: Guangchuang Yu <guangchuangyu@gmail.com>

 Description: ggtree extends the ggplot2 plotting system which implemented the

     grammar of graphics. ggtree is designed for visualizing phylogenetic tree

     and different types of associated annotation data.

 Depends:

-    R (>= 3.1.0),

+    R (>= 3.2.0),

     ggplot2 (>= 2.0.0)

 Imports:

     ape,

     Biostrings,

     colorspace,

-    ggplot2,

     grid,

     gridExtra,

     jsonlite,

@@ -30,6 +29,7 @@ Suggests:

     phytools,

     phangorn,

     rmarkdown,

+    scales,

     testthat

 VignetteBuilder: knitr

 License: Artistic-2.0

@@ -24,7 +24,6 @@ export(Date2decimal)

 export(MRCA)

 export(StatHilight)

 export(add_colorbar)

-export(aes)

 export(annotation_image)

 export(apeBoot)

 export(as.binary)

@@ -61,7 +60,6 @@ export(getRoot)

 export(get_clade_position)

 export(get_heatmap_column_position)

 export(get_taxa_name)

-export(ggplotGrob)

 export(ggtree)

 export(gheatmap)

 export(gplot)

@@ -1,3 +1,12 @@

+CHANGES IN VERSION 1.3.7

+------------------------

+ o split the long vignette to several vignettes

+   + 00 ggtree <2015-12-29, Tue>

+   + 01 tree data import <2015-12-28, Mon>

+   + 02 tree visualization <2015-12-28, Mon>

+   + 03 tree view manipulation <2015-12-28, Mon>

+   + 04 tree annotation <2015-12-29, Tue>

+ 

 CHANGES IN VERSION 1.3.6

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

  o MRCA function for finding Most Recent Common Ancestor among a vector of tips <2015-12-22, Tue>

@@ -11,6 +11,7 @@

 ##' @param fontsize size of text

 ##' @param angle angle of text

 ##' @param geom one of 'text' or 'label'

+##' @param hjust hjust

 ##' @param fill fill label background, only work with geom='label'

 ##' @param ... additional parameter

 ##' @return ggplot layers

@@ -13,12 +13,12 @@

 geom_hilight <- function(node, fill="steelblue", alpha=.5) {

-    data=NULL

-    stat="hilight"

-    position="identity"

-    show.legend=NA

-    na.rm=FALSE

-    inherit.aes=FALSE

+    data = NULL

+    stat = "hilight"

+    position = "identity"

+    show.legend = NA

+    na.rm = FALSE

+    inherit.aes = FALSE

     default_aes <- aes_(x=~x, y=~y, node=~node, parent=~parent, branch.length=~branch.length)

     mapping <- default_aes

@@ -33,15 +33,27 @@ geom_hilight <- function(node, fill="steelblue", alpha=.5) {

         show.legend=show.legend,

         inherit.aes = inherit.aes,

         params = list(node=node,

-            fill=fill, alpha=alpha,

-            na.rm = na.rm)

+                      fill=fill, alpha=alpha,

+                      na.rm = na.rm)

     )

 }

 ##' stat_hilight

-##' @rdname geom_hilight

+##'

+##'

+##' @title stat_hilight

+##' @param mapping aes mapping

+##' @param data data

 ##' @param geom geometric object

+##' @param position position

+##' @param node node number

+##' @param show.legend show legend

+##' @param inherit.aes logical

+##' @param fill fill color

+##' @param alpha transparency

+##' @param ... additional parameter

+##' @return layer

 ##' @importFrom ggplot2 layer

 ##' @export

 stat_hilight <- function(mapping=NULL, data=NULL, geom="rect",

@@ -4,7 +4,6 @@

 ##' @title ggtree

 ##' @param tr phylo object

 ##' @param mapping aes mapping

-##' @param showDistance add distance legend, logical

 ##' @param layout one of 'rectangular', 'slanted', 'fan'/'circular', 'radial' or 'unrooted'

 ##' @param mrsd most recent sampling date

 ##' @param as.Date logical whether using Date class in time tree

@@ -461,15 +460,6 @@ add_colorbar <- function(p, color, x=NULL, ymin=NULL, ymax=NULL, font.size=4) {

 }

-

-

-

-

-

-

-

-

-

 ##' get taxa name of a selected node

 ##'

 ##' 

deleted file mode 100644

@@ -1,43 +0,0 @@

-##' @rdname groupOTU-methods

-##' @exportMethod groupOTU

-setMethod("groupOTU", signature(object="phylo"),

-          function(object, focus, group_name="group") {

-              groupOTU.phylo(object, focus, group_name)

-          })

-

-##' @rdname groupOTU-methods

-##' @exportMethod groupOTU

-##' @param tree which tree selected

-setMethod("groupOTU", signature(object="r8s"),

-          function(object, focus, group_name="group", tree="TREE") {

-              groupOTU_(get.tree(object)[[tree]], focus, group_name)

-          }

-          )

-

-

-##' @rdname groupOTU-methods

-##' @exportMethod groupOTU

-setMethod("groupOTU", signature(object="codeml"),

-          function(object, focus, group_name="group") {

-              groupOTU_(object, focus, group_name)

-          }

-          )

-

-

-##' @rdname groupOTU-methods

-##' @exportMethod groupOTU

-setMethod("groupOTU", signature(object="codeml_mlc"),

-          function(object, focus, group_name="group") {

-              groupOTU_(object, focus, group_name)

-          }

-          )

-

-

-##' @rdname groupOTU-methods

-##' @exportMethod groupOTU

-setMethod("groupOTU", signature(object="paml_rst"),

-          function(object, focus, group_name="group") {

-              groupOTU_(object, focus, group_name)

-          }

-          )

-

@@ -103,7 +103,7 @@ merge_tree <- function(obj1, obj2) {

     info2$parent <- node_map.df[info2$parent, 2]

     cn <- colnames(info2)

-    i <- match(c("x", "y", "isTip", "label", "branch", "branch.length"), cn)

+    i <- match(c("x", "y", "isTip", "label", "branch", "branch.length", "angle"), cn)

     i <- i[!is.na(i)]

     info2 <- info2[, -i]

@@ -105,14 +105,16 @@ rm.singleton.newick <- function(nwk, outfile = NULL) {

 ##' @method fortify beast

 ##' @export

 fortify.beast <- function(model, data,

-                          layout    = "rectangular",

-                          yscale    = "none",

-                          ladderize = TRUE,

-                          right     =FALSE,

-                          ndigits   = NULL,

+                          layout        = "rectangular",

+                          yscale        = "none",

+                          ladderize     = TRUE,

+                          right         = FALSE,

+                          branch.length = "branch.length",

+                          ndigits       = NULL,

                           mrsd = NULL, ...) {

-    phylo <- get.tree(model)

+    phylo <- set_branch_length(model, branch.length)

+

     df    <- fortify(phylo, layout=layout,

                      ladderize=ladderize, right=right, mrsd = mrsd, ...)

@@ -258,11 +260,9 @@ fortify.codeml <- function(model, data,

         phylo <- get.tree(model@rst)

     } else {

         if (length == "mlc.branch.length") {

-            length = "branch.length"

+            length <- "branch.length"

         }

-        phylo <- fortify.codeml_mlc_(model@mlc, data, layout,

-                                     ladderize, right,

-                                     branch.length = length, ...)

+        phylo <- set_branch_length(model@mlc, length)

     }

     df <- fortify(phylo, data, layout, ladderize, right,

@@ -271,7 +271,7 @@ fortify.codeml <- function(model, data,

     res <- merge_phylo_anno.codeml_mlc(df, dNdS, ndigits)

     df <- merge_phylo_anno.paml_rst(res, model@rst)

     df <- scaleY(phylo, df, yscale, layout, ...)

-

+    

     append_extraInfo(df, model)

 }

@@ -287,11 +287,11 @@ fortify.codeml_mlc <- function(model, data,

                                ndigits       = NULL,

                                mrsd          = NULL,

                                ...) {

+

+    phylo <- set_branch_length(model, branch.length)

-    phylo <- fortify.codeml_mlc_(model, data, layout,

-                                 ladderize, right,

-                                 branch.length, mrsd=mrsd, ...)

-    df <- fortify(phylo, data, layout, ladderize, right, branch.length=branch.length, ...)

+    df <- fortify(phylo, data, layout, ladderize, right,

+                  branch.length=branch.length, mrsd=mrsd, ...)

     dNdS <- model@dNdS

@@ -325,26 +325,10 @@ fortify.codeml_mlc_ <- function(model, data,

                                 right         = FALSE,

                                 branch.length = "branch.length",

                                 ...) {

-    dNdS <- model@dNdS

-    length <- match.arg(branch.length, c("none", "branch.length",

-                                         colnames(dNdS)[-c(1,2)]))

-    phylo <- get.tree(model)

-    if (! length %in%  c("branch.length", "none")) {

-        edge <- as.data.frame(phylo$edge)

-        colnames(edge) <- c("parent", "node")

-        

-        dd <- merge(edge, dNdS,

-                    by.x  = c("node", "parent"),

-                    by.y  = c("node", "parent"),

-                    all.x = TRUE)

-        dd <- dd[match(edge$node, dd$node),]

-        phylo$edge.length <- dd[, length]

-    }

-

-    return(phylo)

 }

+

 ##' @method fortify paml_rst

 ##' @export

@@ -1,3 +1,29 @@

+

+##' @rdname groupClade-methods

+##' @exportMethod groupClade

+setMethod("groupClade", signature(object="phylo"),

+          function(object, node, group_name="group") {

+              groupClade.phylo(object, node, group_name)

+          })

+

+groupClade.phylo <- function(object, node, group_name) {

+    if (length(node) == 1) {

+        clade <- extract.clade(object, node)

+        tips <- clade$tip.label

+    } else {

+        tips <- lapply(node, function(x) {

+            clade <- extract.clade(object, x)

+            clade$tip.label

+        })

+    }

+    

+    groupOTU.phylo(object, tips, group_name)

+}

+

+

+

+

+

 ##' group selected clade

 ##'

 ##' 

@@ -1,3 +1,26 @@

+##' group OTU

+##'

+##' 

+##' @title groupOTU.phylo

+##' @param phy tree object

+##' @param focus tip list

+##' @param group_name name of the group

+##' @return phylo object

+##' @author ygc

+groupOTU.phylo <- function(phy, focus, group_name="group") {

+    attr(phy, group_name) <- NULL

+    if ( is(focus, "list") ) {

+        for (i in 1:length(focus)) {

+            phy <- gfocus(phy, focus[[i]], group_name)

+        } 

+    } else {

+        phy <- gfocus(phy, focus, group_name)

+    }

+    attr(phy, group_name) <- factor(attr(phy, group_name))

+    return(phy)

+}

+

+

 ##' group tree based on selected OTU, will traceback to MRCA

 ##'

 ##' 

@@ -8,6 +31,7 @@ setMethod("groupOTU", signature(object="phylo"),

               groupOTU.phylo(object, focus, group_name)

           })

+

 ##' @rdname groupOTU-methods

 ##' @exportMethod groupOTU

 setMethod("groupOTU", signature(object="apeBootstrap"),

@@ -39,49 +39,4 @@ setMethod("scale_color", signature(object="phylo"),

-##' group OTU

-##'

-##' 

-##' @title groupOTU.phylo

-##' @param phy tree object

-##' @param focus tip list

-##' @param group_name name of the group

-##' @return phylo object

-##' @author ygc

-groupOTU.phylo <- function(phy, focus, group_name="group") {

-    attr(phy, group_name) <- NULL

-    if ( is(focus, "list") ) {

-        for (i in 1:length(focus)) {

-            phy <- gfocus(phy, focus[[i]], group_name)

-        } 

-    } else {

-        phy <- gfocus(phy, focus, group_name)

-    }

-    attr(phy, group_name) <- factor(attr(phy, group_name))

-    return(phy)

-}

-

-##' @rdname groupClade-methods

-##' @exportMethod groupClade

-setMethod("groupClade", signature(object="phylo"),

-          function(object, node, group_name="group") {

-              groupClade.phylo(object, node, group_name)

-          })

-

-groupClade.phylo <- function(object, node, group_name) {

-    if (length(node) == 1) {

-        clade <- extract.clade(object, node)

-        tips <- clade$tip.label

-    } else {

-        tips <- lapply(node, function(x) {

-            clade <- extract.clade(object, x)

-            clade$tip.label

-        })

-    }

-    

-    groupOTU.phylo(object, tips, group_name)

-}

-

-

-

@@ -869,3 +869,44 @@ calculate_branch_mid <- function(res) {

     res$branch[is.na(res$branch)] <- 0

     return(res)

 }

+

+

+set_branch_length <- function(tree_object, branch.length) {

+    phylo <- get.tree(tree_object)

+    

+    if (branch.length %in%  c("branch.length", "none")) {

+        return(phylo)

+    }

+

+

+    ## if (is(tree_object, "codeml")) {

+    ##     tree_anno <- tree_object@mlc@dNdS

+    ## } else

+    

+    if (is(tree_object, "codeml_mlc")) {

+        tree_anno <- tree_object@dNdS

+    } else if (is(tree_object, "beast")) {

+        tree_anno <- tree_object@stats

+    }

+    

+    length <- match.arg(branch.length, c("none", "branch.length",

+                                         colnames(tree_anno)[-c(1,2)]))

+

+  

+    edge <- as.data.frame(phylo$edge)

+    colnames(edge) <- c("parent", "node")

+    

+    dd <- merge(edge, tree_anno,

+                by.x  = "node",

+                by.y  = "node",

+                all.x = TRUE)

+    dd <- dd[match(edge$node, dd$node),]

+    len <- unlist(dd[, length])

+    len <- as.numeric(len)

+    len[is.na(len)] <- 0

+    

+    phylo$edge.length <- len

+

+    return(phylo)

+}

+

deleted file mode 100644

@@ -1,27 +0,0 @@

-% Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/ggplot2.R

-\name{aes}

-\alias{aes}

-\title{creates a lists of unevaluated expressions}

-\source{

-This is just the imported function

-from the ggplot2 package. The documentation you should

-read for the aes function can be found here: \link[ggplot2]{aes}

-}

-\usage{

-aes(x, y, ...)

-}

-\arguments{

-\item{x}{name values}

-

-\item{y}{name values}

-

-\item{...}{additional name values}

-}

-\description{

-creates a lists of unevaluated expressions

-}

-\seealso{

-\link[ggplot2]{aes}

-}

-

@@ -27,6 +27,8 @@ geom_cladelabel(node, label, offset = 0, offset.text = 0, align = FALSE,

 \item{geom}{one of 'text' or 'label'}

+\item{hjust}{hjust}

+

 \item{fill}{fill label background, only work with geom='label'}

 \item{...}{additional parameter}

@@ -2,14 +2,9 @@

 % Please edit documentation in R/geom_hilight.R

 \name{geom_hilight}

 \alias{geom_hilight}

-\alias{stat_hilight}

 \title{geom_hilight}

 \usage{

 geom_hilight(node, fill = "steelblue", alpha = 0.5)

-

-stat_hilight(mapping = NULL, data = NULL, geom = "rect",

-  position = "identity", node, show.legend = NA, inherit.aes = FALSE,

-  fill, alpha, ...)

 }

 \arguments{

 \item{node}{selected node to hilight}

@@ -17,16 +12,12 @@ stat_hilight(mapping = NULL, data = NULL, geom = "rect",

 \item{fill}{color fill}

 \item{alpha}{alpha (transparency)}

-

-\item{geom}{geometric object}

 }

 \value{

 ggplot2

 }

 \description{

 layer of hilight clade with rectangle

-

-stat_hilight

 }

 \author{

 Guangchuang Yu

deleted file mode 100644

@@ -1,23 +0,0 @@

-% Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/ggplot2.R

-\name{ggplotGrob}

-\alias{ggplotGrob}

-\title{generate a ggplot2 plot grob}

-\source{

-This is just the imported function

-from the ggplot2 package. The documentation you should

-read for the ggplotGrob function can be found here: \link[ggplot2]{ggplotGrob}

-}

-\usage{

-ggplotGrob(x)

-}

-\arguments{

-\item{x}{ggplot2 object}

-}

-\description{

-generate a ggplot2 plot grob

-}

-\seealso{

-\link[ggplot2]{ggplotGrob}

-}

-

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

 \title{visualizing phylogenetic tree and heterogenous associated data based on grammar of graphics

 \code{ggtree} provides functions for visualizing phylogenetic tree and its associated data in R.}

 \usage{

-ggtree(tr, mapping = NULL, showDistance = FALSE, layout = "rectangular",

-  mrsd = NULL, as.Date = FALSE, yscale = "none", yscale_mapping = NULL,

+ggtree(tr, mapping = NULL, layout = "rectangular", mrsd = NULL,

+  as.Date = FALSE, yscale = "none", yscale_mapping = NULL,

   ladderize = TRUE, right = FALSE, branch.length = "branch.length",

   ndigits = NULL, ...)

 }

@@ -18,8 +18,6 @@ ggtree(tr, mapping = NULL, showDistance = FALSE, layout = "rectangular",

 \item{mapping}{aes mapping}

-\item{showDistance}{add distance legend, logical}

-

 \item{layout}{one of 'rectangular', 'slanted', 'fan'/'circular', 'radial' or 'unrooted'}

 \item{mrsd}{most recent sampling date}

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/AllGenerics.R, R/RAxML.R, R/ape.R, R/beast.R, R/codeml.R, R/codeml_mlc.R, R/hyphy.R, R/jplace.R, R/method-groupClade.R, R/paml_rst.R, R/phangorn.R, R/phylo.R, R/r8s.R

+% Please edit documentation in R/AllGenerics.R, R/RAxML.R, R/ape.R, R/beast.R, R/codeml.R, R/codeml_mlc.R, R/hyphy.R, R/jplace.R, R/method-groupClade.R, R/paml_rst.R, R/phangorn.R, R/r8s.R

 \docType{methods}

 \name{groupClade}

 \alias{groupClade}

@@ -35,6 +35,8 @@ groupClade(object, node, group_name = "group", ...)

 \S4method{groupClade}{jplace}(object, node, group_name = "group")

+\S4method{groupClade}{phylo}(object, node, group_name = "group")

+

 \S4method{groupClade}{nhx}(object, node, group_name = "group")

 \S4method{groupClade}{ggplot}(object, node, group_name)

@@ -45,8 +47,6 @@ groupClade(object, node, group_name = "group", ...)

 \S4method{groupClade}{phangorn}(object, node, group_name = "group")

-\S4method{groupClade}{phylo}(object, node, group_name = "group")

-

 \S4method{groupClade}{r8s}(object, node, group_name = "group",

   tree = "TREE")

 }

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/AllGenerics.R, R/RAxML.R, R/groupOTU.R, R/hyphy.R, R/jplace.R, R/method-groupOTU.R

+% Please edit documentation in R/AllGenerics.R, R/RAxML.R, R/hyphy.R, R/jplace.R, R/method-groupOTU.R

 \docType{methods}

 \name{groupOTU}

 \alias{groupOTU}

@@ -23,16 +23,6 @@ groupOTU(object, focus, group_name = "group", ...)

 \S4method{groupOTU}{raxml}(object, focus, group_name = "group")

-\S4method{groupOTU}{phylo}(object, focus, group_name = "group")

-

-\S4method{groupOTU}{r8s}(object, focus, group_name = "group", tree = "TREE")

-

-\S4method{groupOTU}{codeml}(object, focus, group_name = "group")

-

-\S4method{groupOTU}{codeml_mlc}(object, focus, group_name = "group")

-

-\S4method{groupOTU}{paml_rst}(object, focus, group_name = "group")

-

 \S4method{groupOTU}{hyphy}(object, focus, group_name = "group")

 \S4method{groupOTU}{jplace}(object, focus, group_name = "group")

@@ -69,8 +59,6 @@ codeml_mlc, codeml, jplace, beast, hyphy}

 \item{...}{additional parameter}

-\item{tree}{which tree selected}

-

 \item{tree}{which tree selected}

 }

 \value{

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/phylo.R

+% Please edit documentation in R/method-groupOTU.R

 \name{groupOTU.phylo}

 \alias{groupOTU.phylo}

 \title{groupOTU.phylo}

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

 \title{Class "r8s"

 This class stores output info from r8s}

 \description{

-Class "r8s"

-This class stores output info from r8s

-

 Class "r8s"

 This class stores output info from r8s

 }

@@ -23,21 +20,9 @@ This class stores output info from r8s

 \item{\code{phylo}}{multiPhylo, time tree, rate tree and absolute substitution tree}

-\item{\code{extraInfo}}{extra information}

-

-\item{\code{file}}{input file}

-

-\item{\code{fields}}{available feature}

-

-\item{\code{treetext}}{tree text}

-

-\item{\code{phylo}}{multiPhylo, time tree, rate tree and absolute substitution tree}

-

 \item{\code{extraInfo}}{extra information}

 }}

 \author{

-Guangchuang Yu \url{http://ygc.name}

-

 Guangchuang Yu \url{http://ygc.name}

 }

 \keyword{classes}

new file mode 100644

@@ -0,0 +1,38 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/geom_hilight.R

+\name{stat_hilight}

+\alias{stat_hilight}

+\title{stat_hilight}

+\usage{

+stat_hilight(mapping = NULL, data = NULL, geom = "rect",

+  position = "identity", node, show.legend = NA, inherit.aes = FALSE,

+  fill, alpha, ...)

+}

+\arguments{

+\item{mapping}{aes mapping}

+

+\item{data}{data}

+

+\item{geom}{geometric object}

+

+\item{position}{position}

+

+\item{node}{node number}

+

+\item{show.legend}{show legend}

+

+\item{inherit.aes}{logical}

+

+\item{fill}{fill color}

+

+\item{alpha}{transparency}

+

+\item{...}{additional parameter}

+}

+\value{

+layer

+}

+\description{

+stat_hilight

+}

+

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/ggtree.R

+% Please edit documentation in R/theme.R

 \name{theme_transparent}

 \alias{theme_transparent}

 \title{theme_transparent}

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/ggtree.R

+% Please edit documentation in R/theme.R

 \name{theme_tree}

 \alias{theme_tree}

 \title{theme_tree}

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

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/ggtree.R

+% Please edit documentation in R/theme.R

 \name{theme_tree2}

 \alias{theme_tree2}

 \title{theme_tree2}

@@ -17,7 +17,7 @@ test_that("convert polytomy to binary tree", {

     expect_equal(is.binary.tree(bt), TRUE)

 })

-df <- ggtree:::fortify.phylo(rtree(10))

+df <- fortify(rtree(10))

 child <- ggtree:::getChild.df(df, 11)

 test_that("root node should not be included in its ancestor node list", {

     expect_equal(11 %in% child, FALSE)

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

new file mode 100644

@@ -0,0 +1,139 @@

+---

+title: "ggtree: a phylogenetic tree viewer for different types of tree annotations"

+author: "\\

+

+	Guangchuang Yu (<guangchuangyu@gmail.com>) and Tommy Tsan-Yuk Lam (<ttylam@hku.hk>)\\

+

+        School of Public Health, The University of Hong Kong"

+date: "`r Sys.Date()`"

+bibliography: ggtree.bib

+csl: nature.csl

+output: 

+  BiocStyle::html_document:

+    toc: true

+  BiocStyle::pdf_document:

+    toc: true

+vignette: >

+  %\VignetteIndexEntry{00 ggtree introduction}

+  %\VignetteEngine{knitr::rmarkdown}

+  %\usepackage[utf8]{inputenc}

+---

+

+```{r style, echo=FALSE, results="asis", message=FALSE}

+BiocStyle::markdown()

+knitr::opts_chunk$set(tidy = FALSE,

+		   message = FALSE)

+```

+

+

+```{r echo=FALSE, results="hide", message=FALSE}

+library("colorspace")

+library("Biostrings")

+library("ape")

+library("ggplot2")

+library("gridExtra")

+library("ggtree")

+library("phangorn")

+```

+

+

+

+> You can't even begin to understand biology, you can't understand life, unless you understand what it's all there for, how it arose - and that means evolution.

+> --- Richard Dawkins

+

+

+# Citation

+If you use `r Biocpkg("ggtree")` in published research, please cite:

+

+```

+G Yu, D Smith, H Zhu, Y Guan, TTY Lam,

+ggtree: an R package for visualization and annotation of phylogenetic tree with different types of meta-data.

+revised.

+```

+

+# Introduction

+

+This project arose from our needs to annotate nucleotide substitutions in the phylogenetic tree, and we found that there is no tree visualization software can do this easily. Existing tree viewers are designed for displaying phylogenetic tree, but not annotating it. Although some tree viewers can displaying bootstrap values in the tree, it is hard/impossible to display other information in the tree. Our first solution for displaying nucleotide substituitions in the tree is to add this information in the node/tip names and use traditional tree viewer to show it. We displayed the information in the tree successfully, but we believe this indirect approach is inefficient.

+

+In the old day, phylogenetic tree is often small. At that time, as we almost didn't have a need to annotate a tree; displaying the evolution relationships is mostly enough. Nowadays, we can obtain a lot of data from different experiments, and we want to associate our data, for instance antigenic change, with the evolution relationship. Visualizing these associations in the phylogenetic tree can help us to identify evolution patterns. We believe we need a next generation tree viewer that should be programmable and extensible. It can view a phylogenetic tree easily as we did with classical software and support adding annotation data in a layer above the tree. This is the objective of developing the `r Githubpkg("GuangchuangYu/ggtree")`. Common tasks of annotating a phylogenetic tree should be easy and complicated tasks can be possible to achieve by adding multiple layers of annotation.

+

+The `r Githubpkg("GuangchuangYu/ggtree")` is designed by extending the `r CRANpkg("ggplot2")`[@wickham_ggplot2_2009] package. It is based on the grammar of graphics and takes all the good parts of `r CRANpkg("ggplot2")`. There are other R packages that implement tree viewer using `r CRANpkg("ggplot2")`, including `r CRANpkg("OutbreakTools")`, `r Biocpkg("phyloseq")`[@mcmurdie_phyloseq_2013] and `r Githubpkg("gjuggler/ggphylo")`; they mostly create complex tree view functions for their specific needs. Internally, these packages interpret a phylogenetic as a collection of `lines`, which makes it hard to annotate diverse user input that are related to node (taxa). The `r Githubpkg("GuangchuangYu/ggtree")` is different to them by interpreting a tree as a collection of `taxa` and allowing general flexibilities of annotating phylogenetic tree with diverse types of user inputs. 

+

+

+# 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 `r Githubpkg("GuangchuangYu/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]

+

+

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

+

+We implement several functions to manipulate a phylogenetic tree.

+

++ taxa can be clustered together using `groupClade` or `groupOTU` functions

++ clades can be collapsed via `collapse` function

++ collapsed clade can be expanded by using `expand` function

++ clade can be re-scale to zoom in or zoom out by `scaleClade` function

++ selected clade can be rotated by 180 degree using `rotate` function

++ position of two selected clades (should share a same parent) can be exchanged by `flip` function

+

+Details and examples can be found in [Tree Manipulation](treeManipulation.html) vignette.

+

+

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

+

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

+

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

+

+

+# Vignette Entry

+

++ [Tree Data Import](treeImport.html)