@@ -2,7 +2,7 @@

 ##'

 ##'

 ##' @title as.polytomy

-##' @param tree tree object

+##' @param tree tree object, 'phylo' object only

 ##' @param feature selected feature

 ##' @param fun function to select nodes to collapse

 ##' @return polytomy tree

@@ -12,15 +12,20 @@ vexpand <- function(ratio, direction = 1) {

     ggexpand(ratio, direction, side = 'v')

 }

-##' expand xlim (ylim) by ratio of x (y) range

+##' expand xlim (ylim) by ratio of x (y) axis range

 ##'

 ##'

 ##' @rdname ggexpand

-##' @param ratio expand x (y) limits by amount of xrange (yrange) * ratio

-##' @param direction expand x limit at right hand side if direction is 1, or left hand side if direction is -1

-##' @param side one of 'h' for horizontal and 'v' for vertical or 'hv' for both.

+##' @param ratio expand x (y) axis limits by amount of xrange (yrange) * ratio

+##' @param direction expand x axis limit at right hand side if direction is 1 (default), or left hand side if direction is -1

+##' @param side one of 'h' for horizontal and 'v' for vertical or 'hv' for both (default).

 ##' @return ggexpand object

 ##' @export

+##' @examples

+##' x <- rtree(20)

+##' x$tip.label <- paste0('RRRRREEEEEAAAAALLLLLYYYYY_Long_Lable_', x$tip.label)

+##' p1 <- ggtree(x) + geom_tiplab()

+##' p1 + ggexpand(1.5, side = "h")

 ##' @author Guangchuang Yu

 ggexpand <- function(ratio, direction = 1, side = 'hv') {

     side <- match.arg(side, c('h', 'v', 'hv'))

@@ -30,13 +35,21 @@ ggexpand <- function(ratio, direction = 1, side = 'hv') {

 }

-##' set x axis limits for Tree panel

+##' set x axis limits specially for Tree panel

 ##'

 ##'

 ##' @title xlim_tree

-##' @param xlim xlim

+##' @param xlim x axis limits 

 ##' @return updated tree view

 ##' @export

+##' @examples

+##' x <- rtree(30)

+##' p <- ggtree(x) + geom_tiplab()

+##' d <- data.frame(label = x$tip.label, 

+##'                 value = rnorm(30))

+##' p2 <- p + geom_facet(panel = "Dot", data = d, 

+##'             geom = geom_point, mapping = aes(x = value))

+##' p2 + xlim_tree(6)

 ##' @author Guangchuang Yu

 xlim_tree <- function(xlim) {

     xlim_expand(xlim, panel='Tree')

@@ -47,11 +60,19 @@ xlim_tree <- function(xlim) {

 ##'

 ##'

 ##' @title xlim_expand

-##' @param xlim xlim

-##' @param panel panel

+##' @param xlim x axis limits

+##' @param panel name of the panel to expand

 ##' @return updated tree view

 ##' @importFrom ggplot2 geom_blank

 ##' @export

+##' @examples

+##' x <- rtree(30)

+##' p <- ggtree(x) + geom_tiplab()

+##' d <- data.frame(label = x$tip.label, 

+##'                 value = rnorm(30))

+##' p2 <- p + geom_facet(panel = "Dot", data = d, 

+##'             geom = geom_point, mapping = aes(x = value))

+##' p2 + xlim_expand(c(-10, 10), 'Dot')

 ##' @author Guangchuang Yu

 xlim_expand <- function(xlim, panel) {

     structure(list(x = xlim, panel = panel), class = "facet_xlim")

@@ -61,23 +82,36 @@ xlim_expand <- function(xlim, panel) {

 ##' add second x-axis for geom_range

 ##'

+##' notice that the first axis is disabled in the default theme thus users need to enable it first before using scale_x_range

 ##'

 ##' @title scale_x_range

 ##' @return ggtree object

 ##' @export

+##' @references

+##' For demonstration of this function ,please refer to chapter 5.2.4 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 ##' @author Guangchuang Yu

 scale_x_range <- function() {

     structure(list(), class = "range_xaxis")

 }

-##' reverse timescle x-axis

+##' reverse timescle x-axis by setting the most recent tip to 0

+##'

+##' 'scale_x_continuous(labels=abs)' is required if users want to set the x-axis lable to absolute value

 ##'

 ##'

 ##' @title revts

-##' @param treeview treeview

-##' @return updated treeview

+##' @param treeview original tree view

+##' @return updated tree view

 ##' @export

+##' @examples

+##' tr <- rtree(10)

+##' p <- ggtree(tr) + theme_tree2()

+##' p2 <- revts(p) 

+##' p3 <- p2 + scale_x_continuous(labels=abs)

+##' plot_list(p, p2, p3, ncol=3, tag_levels="A")

 ##' @author Guangchuang Yu

 revts <- function(treeview) {

     x <- treeview$data$x

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

 ##' This function extract an ordered vector of the tips from selected clade or the whole tree

 ##' based on the ggtree() plot. 

 ##' @title get_taxa_name

-##' @param tree_view tree view (i.e. the ggtree object). If tree_view is NULL, the last ggplot will be used.

+##' @param tree_view tree view (i.e. the ggtree object). If tree_view is NULL, the last ggplot object will be used.

 ##' @param node internal node number to specify a clade. If NULL, using the whole tree

 ##' @return ordered taxa name vector

 ##' @importFrom tidytree offspring

@@ -35,17 +35,22 @@ get_taxa_name <- function(tree_view=NULL, node=NULL) {

 }

-##' view a clade of tree

+##' view a selected clade of tree, clade can be selected by specifying a node number or 

+##' determined by the most recent common ancestor of selected tips

 ##'

 ##'

 ##' @title viewClade

 ##' @inheritParams get_taxa_name

-##' @param xmax_adjust adjust xmax

+##' @param xmax_adjust adjust the max range of x axis

 ##' @return clade plot

 ##' @importFrom ggplot2 ggplot_build

 ##' @importFrom ggplot2 coord_cartesian

 ##' @importFrom aplot xrange

 ##' @export

+##' @examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab()

+##' viewClade(p, 18, xmax_adjust = 0.)

 ##' @author Guangchuang Yu

 viewClade <- function(tree_view=NULL, node, xmax_adjust=0) {

     tree_view %<>% get_tree_view

@@ -70,20 +75,26 @@ is.viewClade <- function(tree_view) {

-##' collapse a clade

+##' collapse a selected clade, which can later be expanded with the 'expand()' fuction if necessary

 ##'

 ##'

 ##' @title collapse-ggtree

 ##' @rdname collapse

 ##' @param x tree view (i.e. the ggtree object). If tree_view is NULL, the last ggplot will be used.

 ##' @param node internal node number 

-##' @param mode one of 'none', 'max', 'min' and 'mixed'

-##' @param clade_name set clade name. If clade_name = NULL, do nothing

-##' @param ... additional parameters

+##' @param mode one of 'none'(default), 'max', 'min' and 'mixed'. 'none' would simply collapse the clade as 'tip' and 

+##' the rest will display a triangle, whose shape is determined by the farest/closest tip of the collapsed clade to indicate it

+##' @param clade_name set a name for the collapsed clade. If clade_name = NULL, do nothing

+##' @param ... additional parameters to set the color or transparency of the triangle

 ##' @return tree view

 ##' @method collapse ggtree

 ##' @importFrom ggplot2 geom_polygon

 ##' @export

+##' @examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab()

+##' p

+##' p1 <- collapse(p, node = 17, mode = "mixed", clade_name = "cclade", alpha = 0.8, color = "grey", fill = "light blue")

 ##' @seealso expand

 ##' @author Guangchuang Yu

 collapse.ggtree <- function(x=NULL, node, mode = "none", clade_name = NULL, ...) {

@@ -173,13 +184,18 @@ collapse.ggtree <- function(x=NULL, node, mode = "none", clade_name = NULL, ...)

     tree_view

 }

-##' expand collased clade

+##' expand collapsed clade

 ##'

 ##'

 ##' @title expand

 ##' @inheritParams get_taxa_name

 ##' @return tree view

 ##' @export

+##' examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab()

+##' p1 <- collapse(p, 17)

+##' expand(p1, 17)

 ##' @seealso collapse

 ##' @author Guangchuang Yu

 expand <- function(tree_view=NULL, node) {

@@ -230,13 +246,17 @@ expand <- function(tree_view=NULL, node) {

     return(tree_view)

 }

-##' rotate 180 degree of a selected branch

+##' rotate selected clade by 180 degree

 ##'

 ##'

 ##' @title rotate

 ##' @inheritParams get_taxa_name

 ##' @return ggplot2 object

 ##' @export

+##' @examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab()

+##' rotate(p, 17)

 ##' @author Guangchuang Yu

 rotate <- function(tree_view=NULL, node) {

     tree_view %<>% get_tree_view

@@ -271,15 +291,19 @@ rotate <- function(tree_view=NULL, node) {

-##' flip position of two selected branches

+##' exchange the position of 2 clades

 ##'

 ##'

 ##' @title flip

 ##' @param tree_view tree view (i.e. the ggtree object). If tree_view is NULL, the last ggplot will be used.

-##' @param node1 node number of branch 1

-##' @param node2 node number of branch 2

-##' @return ggplot2 object

+##' @param node1 node number of clade 1. It should share a same parent node with node2

+##' @param node2 node number of clade 2. It should share a same parent node with node1

+##' @return ggplot object

 ##' @export

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab() +

+##'   geom_nodelab(aes(subset=!isTip, label=node), hjust = -.1, color = "red")

+##' flip(p, 19, 20)   ## Depends on the condition of your tree

 ##' @author Guangchuang Yu

 flip <- function(tree_view=NULL, node1, node2) {

     tree_view %<>% get_tree_view

@@ -342,17 +366,22 @@ flip <- function(tree_view=NULL, node1, node2) {

 }

-##' scale clade

+##' zoom out/in a selected clade to emphasize or de-emphasize it

 ##'

 ##'

 ##' @title scaleClade

 ##' @inheritParams get_taxa_name

-##' @param scale scale

-##' @param vertical_only logical. If TRUE, only vertical will be scaled.

+##' @param scale the scale of the selected clade. The clade will be zoom in when scale > 1,

+##' and will be zoom out when scale < 1

+##' @param vertical_only logical. If TRUE (default), only vertical will be scaled.

 ##' If FALSE, the clade will be scaled vertical and horizontally.

-##' TRUE by default.

 ##' @return tree view

 ##' @export

+##' @examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab() +

+##'   geom_nodelab(aes(subset=!isTip, label=node), hjust = -.1, color = "red")

+##' scaleClade(p, 24, scale = .1)

 ##' @author Guangchuang Yu

 scaleClade <- function(tree_view=NULL, node, scale=1, vertical_only=TRUE) {

     tree_view %<>% get_tree_view

@@ -431,15 +460,20 @@ reassign_y_from_node_to_root <- function(df, node) {

 }

-##' zoom selected clade of a tree

+##' zoom in on a selected clade of a tree, while showing its on the full view of tree as a seperated panel for reference

 ##'

 ##' 

 ##' @title zoomClade

 ##' @inheritParams get_taxa_name

-##' @param xexpand numeric, extend x, meaning the ratio of range of original x,

+##' @param xexpand numeric, expend the xlim of the zoom area.

 ##' default is NULL.

 ##' @return full tree with zoom in clade

 ##' @author Guangchuang Yu

+##' @examples

+##' x <- rtree(15)

+##' p <- ggtree(x) + geom_tiplab() +

+##'   geom_nodelab(aes(subset=!isTip, label=node), hjust = -.1, color = "red")

+##' zoomClade(p, 21, xexpand = .2)

 ##' @export

 zoomClade <- function(tree_view = NULL, node, xexpand=NULL) {

     p <- get_tree_view(tree_view)

@@ -1,9 +1,9 @@

-##' label facet_plot output

+##' function to relable selected panels created by 'geom_facet' or 'facet-plot'

 ##'

 ##' 

 ##' @title facet_labeller

 ##' @param p facet_plot output

-##' @param label labels of facet panels

+##' @param label new labels of facet panels

 ##' @return ggplot object

 ##' @importFrom ggplot2 as_labeller

 ##' @export

@@ -2,11 +2,13 @@

 ##' zoom selected clade of a tree

 ##'

+##' 'geom_zoom_clade' zooms in on a selected clade of a tree, 

+##' while showing its on the full view of tree as a seperated panel for reference

 ##'

 ##' @title geom_zoom_clade

-##' @param node internal node number

-##' @param xexpand numeric, extend x, meaning the ratio of range of original x, 

-##' default is NULL.

+##' @param node internal node number to zoom in its corresponding clade

+##' @param xexpand numeric, extend x, meaning the ratio of range of the xlim of the original tree, 

+##' defaults to NULL.

 ##' @return updated tree view

 ##' @author Guangchuang Yu

 ##' @export

@@ -4,20 +4,32 @@

 #' correspond to multichotomies will not be displayed.

 #'

 #' @title geom_balance

-#' @param node selected node (balance) to highlight

-#' @param fill color fill

-#' @param color color to outline highlights and divide balance

-#' @param alpha alpha (transparency)

-#' @param extend extend xmax of the rectangle

-#' @param extendto extend xmax to extendto

+#' @param node selected node (balance) to highlight its two direct descendant

+#' @param fill color to fill in the highlight rectangle, default to "steelblue"

+#' @param color color to outline highlight rectangle and divide balance, defaults to "white"

+#' @param alpha alpha (transparency) for the highlight rectangle, defaults to 0.5

+#' @param extend extend xmax of the highlight rectangle by the value of extend

+#' @param extendto extend xmax of the highlight rectangle to the value of extendto

 #' @return ggplot2

 #' @export

 #' @importFrom ggplot2 aes_

 #' @importFrom ggplot2 GeomRect

 #' @importFrom utils packageVersion

 #' @author Justin Silverman and modified by Guangchuang Yu

-#' @references J. Silverman, et al. *A phylogenetic transform enhances

-#'   analysis of compositional microbiota data*. (in preparation)

+#' @examples 

+#' library(ggtree)

+#' set.seed(123)

+#' tr<- rtree(15)

+#' x <- ggtree(tr)

+#' x + geom_balance(17)

+#' 

+#' @references 

+#' J. Silverman, et al. *A phylogenetic transform enhances

+#' analysis of compositional microbiota data*. (in preparation)   

+#'    

+#' For more detailed demonstration, please refer to chapter 5.2.2 of 

+#' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+#' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_balance <- function(node, fill="steelblue", color='white', alpha=.5, extend=0, extendto=NULL) {

   data = NULL

@@ -3,30 +3,30 @@

 ##' @title geom_cladelab

 ##' @param node selected node to annotate, when data and mapping is NULL, it is required.

 ##' @param label character, character to be showed, when data and mapping is NULL, it is required.

-##' @param data data.frame, the data to be displayed in the annotation, default is NULL.

-##' @param mapping Set of aesthetic mappings, default is NULL. The detail see the following explanation.

+##' @param data data.frame, the data to be displayed in the annotation, defaults to NULL.

+##' @param mapping Set of aesthetic mappings, defaults to NULL. The detail see the following explanation.

 ##' @param geom character, one of 'text', 'label', 'shadowtext', 'image' and 'phylopic', 

-##' default is 'text', and the parameter see the Aesthetics For Specified Geom.

-##' @param parse logical, whether parse label to emoji font, default is FALSE.

+##' defaults to 'text', and the parameter see the Aesthetics For Specified Geom.

+##' @param parse logical, whether parse label to emoji font, defaults to FALSE.

 ##' @param ... additional parameters, see also following section.

 ##'

 ##' additional parameters can refer the following parameters.

 ##'     \itemize{

 ##'        \item \code{offset} distance bar and tree, offset of bar and text from 

-##'         the clade, default is 0.

+##'         the clade, defaults to 0.

 ##'        \item \code{offset.text} distance bar and text, offset of text from bar, 

-##'         default is 0.

-##'        \item \code{align} logical, whether align clade lab, default is FALSE.

-##'        \item \code{extend} numeric, extend the length of bar, default is 0.

+##'         defaults to 0.

+##'        \item \code{align} logical, whether align clade lab, defaults to FALSE.

+##'        \item \code{extend} numeric, extend the length of bar, defaults to 0.

 ##'        \item \code{angle} numeric or 'auto', if angle is auto, the angle of text will 

-##'         be calculated automatically, which is useful for the circular etc layout, default is 0.

-##'        \item \code{horizontal} logical, whether set label to horizontal, default is TRUE.

-##'        \item \code{barsize} the width of line, default is 0.5.

-##'        \item \code{barcolour} the colour of line, default is 'black'.

-##'        \item \code{fontsize} the size of text, default is 3.88.

-##'        \item \code{textcolour} the colour of text, default is 'black'.

-##'        \item \code{imagesize} the size of image, default is 0.05.

-##'        \item \code{imagecolor} the colour of image, default is NULL, when

+##'         be calculated automatically, which is useful for the circular etc layout, defaults to 0.

+##'        \item \code{horizontal} logical, whether set label to horizontal, defaults to TRUE.

+##'        \item \code{barsize} the width of line, defaults to 0.5.

+##'        \item \code{barcolour} the colour of line, defaults to 'black'.

+##'        \item \code{fontsize} the size of text, defaults to 3.88.

+##'        \item \code{textcolour} the colour of text, defaults to 'black'.

+##'        \item \code{imagesize} the size of image, defaults to 0.05.

+##'        \item \code{imagecolor} the colour of image, defaults to NULL, when

 ##'        geom="phylopic", it should be required.

 ##'     }

 ##' The parameters also can be set in mapping, when data is provided. Note: the barsize, barcolour,

@@ -40,16 +40,16 @@

 ##'     \itemize{

 ##'        \item \strong{\code{node}} selected node to hight light, it is required.

 ##'        \item \strong{\code{label}} labels showed, it is required.

-##'        \item \code{colour} the colour of text, default is "black".

-##'        \item \code{size} the size of text, default is 3.88.

-##'        \item \code{angle} the angle of text, default is 0.

-##'        \item \code{hjust} A numeric vector specifying horizontal justification, default is 0.

-##'        \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5.

-##'        \item \code{alpha} the transparency of text, default is NA.

-##'        \item \code{family} the family of text, default is 'sans'.

-##'        \item \code{fontface} the font face of text, default is 1 (plain), others are  

+##'        \item \code{colour} the colour of text, defaults to "black".

+##'        \item \code{size} the size of text, defaults to 3.88.

+##'        \item \code{angle} the angle of text, defaults to 0.

+##'        \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0.

+##'        \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5.

+##'        \item \code{alpha} the transparency of text, defaults to NA.

+##'        \item \code{family} the family of text, defaults to 'sans'.

+##'        \item \code{fontface} the font face of text, defaults to 1 (plain), others are  

 ##'         2 (bold), 3 (italic), 4 (bold.italic).

-##'        \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 .

+##'        \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 .

 ##'     }

 ##'  when the colour, size are not be set in mapping, and user want to modify the colour of text,

 ##'  they should use textcolour, fontsize to avoid the confusion with bar layer annotation.

@@ -59,17 +59,17 @@

 ##'     \itemize{

 ##'        \item \strong{\code{node}} selected node to hight light, it is required.

 ##'        \item \strong{\code{label}} labels to be showed, it is required.

-##'        \item \code{colour} the colour of text, default is "black".

-##'        \item \code{fill} the background colour of the label, default is "white".

-##'        \item \code{size} the size of text, default is 3.88.

-##'        \item \code{angle} the angle of text, default is 0.

-##'        \item \code{hjust} A numeric vector specifying horizontal justification, default is 0.

-##'        \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5.

-##'        \item \code{alpha} the transparency of text, default is NA.

-##'        \item \code{family} the family of text, default is 'sans'.

-##'        \item \code{fontface} the font face of text, default is 1 (plain), others are

+##'        \item \code{colour} the colour of text, defaults to "black".

+##'        \item \code{fill} the background colour of the label, defaults to "white".

+##'        \item \code{size} the size of text, defaults to 3.88.

+##'        \item \code{angle} the angle of text, defaults to 0.

+##'        \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0.

+##'        \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5.

+##'        \item \code{alpha} the transparency of text, defaults to NA.

+##'        \item \code{family} the family of text, defaults to 'sans'.

+##'        \item \code{fontface} the font face of text, defaults to 1 (plain), others are

 ##'         2 (bold), 3 (italic), 4 (bold.italic).

-##'        \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 .

+##'        \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 .

 ##'     }

 ##'  when the colour, size are not be set in mapping, and user want to modify the colour of text,

 ##'  they should use textcolour, fontsize to avoid the confusion with bar layer annotation.

@@ -79,18 +79,18 @@

 ##'     \itemize{

 ##'        \item \strong{\code{node}} selected node to hight light, it is required.

 ##'        \item \strong{\code{label}} labels to be showed, it is required.

-##'        \item \code{colour} the colour of text, default is "black".

-##'        \item \code{bg.colour} the background colour of text, default is 'black'.

-##'        \item \code{bg.r} the width of background text, default is 0.1.

-##'        \item \code{size} the size of text, default is 3.88.

-##'        \item \code{angle} the angle of text, default is 0.

-##'        \item \code{hjust} A numeric vector specifying horizontal justification, default is 0.

-##'        \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5.

-##'        \item \code{alpha} the transparency of text, default is NA.

-##'        \item \code{family} the family of text, default is 'sans'.

-##'        \item \code{fontface} the font face of text, default is 1 (plain), others are

+##'        \item \code{colour} the colour of text, defaults to "black".

+##'        \item \code{bg.colour} the background colour of text, defaults to 'black'.

+##'        \item \code{bg.r} the width of background text, defaults to 0.1.

+##'        \item \code{size} the size of text, defaults to 3.88.

+##'        \item \code{angle} the angle of text, defaults to 0.

+##'        \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0.

+##'        \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5.

+##'        \item \code{alpha} the transparency of text, defaults to NA.

+##'        \item \code{family} the family of text, defaults to 'sans'.

+##'        \item \code{fontface} the font face of text, defaults to 1 (plain), others are

 ##'         2 (bold), 3 (italic), 4 (bold.italic).

-##'        \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 .

+##'        \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 .

 ##'     }

 ##'  when the colour, size are not be set in mapping, and user want to modify the colour of text,

 ##'  they should use textcolour, fontsize to avoid the confusion with bar layer annotation.

@@ -102,9 +102,9 @@

 ##'        \item \strong{\code{label}} labels to be showed, it is required.

 ##'        \item \strong{\code{image}} the image to be annotated, when geom="phylopic", 

 ##'         the uid of phylopic databases, it is required.

-##'        \item \code{colour} the color of image, default is NULL.

-##'        \item \code{size} the size of image, default is 0.05.

-##'        \item \code{alpha} the alpha of image, default is 0.8.

+##'        \item \code{colour} the color of image, defaults to NULL.

+##'        \item \code{size} the size of image, defaults to 0.05.

+##'        \item \code{alpha} the alpha of image, defaults to 0.8.

 ##'     }

 ##'  when the colour, size are not be set in mapping, and user want to modify the colour of image,

 ##'  they should use imagecolour, imagesize to avoid the confusion with bar layer annotation.

@@ -18,7 +18,7 @@

 ##' @param family sans by default, can be any supported font

 ##' @param parse logical, whether parse label

 ##' @param horizontal logical, whether set label to horizontal, 

-##' default is TRUE.

+##' defaults to TRUE.

 ##' @param ... additional parameter

 ##' @return ggplot layers

 ##' @export

@@ -5,10 +5,10 @@

 #'

 #' @title geom_hilight 

 #' @rdname geom-hilight

-#' @param data data.frame, The data to be displayed in this layer, default is NULL.

-#' @param mapping Set of aesthetic mappings, default is NULL.

+#' @param data data.frame, The data to be displayed in this layer, defaults to NULL.

+#' @param mapping Set of aesthetic mappings, defaults to NULL.

 #' @param node selected node to hilight, when data and mapping is NULL, it is required.

-#' @param type the type of layer, default is `auto`, meaning rectangular, circular,

+#' @param type the type of layer, defaults to `auto`, meaning rectangular, circular,

 #' slanted, fan, inward_circular, radial, equal_angle, ape layout tree will use rectangular layer,

 #' unrooted and daylight layout tree use will use encircle layer. You can specify this parameter to

 #' `rect` (rectangular layer) or `encircle` (encircle layer), 'gradient' (gradient color), 

@@ -18,39 +18,39 @@

 #'        \item \code{align} control the align direction of the edge of high light rectangular.

 #'          Options is 'none' (default), 'left', 'right', 'both'. This argument only work when the

 #'          'geom_hilight' is plotting using geom_hilight(mapping=aes(...)).

-#'        \item \code{gradient.direction} character, the direction of gradient color, default is 'rt'

+#'        \item \code{gradient.direction} character, the direction of gradient color, defaults to 'rt'

 #'          meaning the locations of gradient color is from root to tip, options are 'rt' and 'tr'.

 #'        \item \code{gradient.length.out} integer, desired length of the sequence of gradient color,

-#'          default is 2.

+#'          defaults to 2.

 #'        \item \code{roundrect.r} numeric, the radius of the rounded corners, when \code{roundrect=TRUE},

-#'          default is 0.05.

+#'          defaults to 0.05.

 #'     }

 #' @section Aesthetics:

 #' \code{geom_hilight()} understands the following aesthetics for rectangular layer (required 

 #' aesthetics are in bold):

 #'     \itemize{

 #'        \item \strong{\code{node}} selected node to hight light, it is required.

-#'        \item \code{colour} the colour of margin, default is NA.

-#'        \item \code{fill} the colour of fill, default is 'steelblue'.

-#'        \item \code{alpha} the transparency of fill, default is 0.5.

-#'        \item \code{extend} extend xmax of the rectangle, default is 0.

-#'        \item \code{extendto} specify a value, meaning the rectangle extend to, default is NULL.

-#'        \item \code{linetype} the line type of margin, default is 1.

-#'        \item \code{size} the width of line of margin, default is 0.5.

+#'        \item \code{colour} the colour of margin, defaults to NA.

+#'        \item \code{fill} the colour of fill, defaults to 'steelblue'.

+#'        \item \code{alpha} the transparency of fill, defaults to 0.5.

+#'        \item \code{extend} extend xmax of the rectangle, defaults to 0.

+#'        \item \code{extendto} specify a value, meaning the rectangle extend to, defaults to NULL.

+#'        \item \code{linetype} the line type of margin, defaults to 1.

+#'        \item \code{size} the width of line of margin, defaults to 0.5.

 #'     }

 #' \code{geom_hilight()} understands the following aesthethics for encircle layer (required 

 #' aesthetics are in bold):

 #'     \itemize{

 #'        \item \strong{\code{node}} selected node to hight light, it is required.

-#'        \item \code{colour} the colour of margin, default is 'black'.

-#'        \item \code{fill} the colour of fill, default is 'steelblue'.

-#'        \item \code{alpha} the transparency of fill, default is 0.5.

-#'        \item \code{expand} expands the xspline clade region, default is 0.

+#'        \item \code{colour} the colour of margin, defaults to 'black'.

+#'        \item \code{fill} the colour of fill, defaults to 'steelblue'.

+#'        \item \code{alpha} the transparency of fill, defaults to 0.5.

+#'        \item \code{expand} expands the xspline clade region, defaults to 0.

 #'        \item \code{spread} control the size, when only one point.

-#'        \item \code{size} the width of line of margin, default is 0.5.

-#'        \item \code{linetype} the line type of margin, default is 1.

-#'        \item \code{s_shape} the shape of the spline relative to the control points, default is 0.5.

-#'        \item \code{s_open}  whether the spline is a line or a closed shape, default is FALSE.

+#'        \item \code{size} the width of line of margin, defaults to 0.5.

+#'        \item \code{linetype} the line type of margin, defaults to 1.

+#'        \item \code{s_shape} the shape of the spline relative to the control points, defaults to 0.5.

+#'        \item \code{s_open}  whether the spline is a line or a closed shape, defaults to FALSE.

 #'     }

 #' @return a list object.

 #' @author Guangchuang Yu and Shuangbin Xu

@@ -74,6 +74,10 @@

 #' # display the high light layer with round rectangular.

 #' p8 <- p + geom_hilight(data=dat, mapping=aes(node=id, fill=type), type = "roundrect", alpha=0.68)

 #' p2/ p3/ p4/ p5 / p6/ p7/ p8

+#' @references  

+#' For more detailed demonstration, please refer to chapter 5.2.2 of 

+#' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+#' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_hilight <- function(data=NULL,

                          mapping=NULL,

                          node=NULL,

@@ -1,30 +1,41 @@

 ##' geom_label2 support aes(subset) via setup_data

 ##'

+##' 'geom_label2' is a modified version of geom_label, with subset aesthetic supported

 ##'

 ##' @title geom_label2

-##' @param mapping the aesthetic mapping

+##' @param mapping Set of aesthetic mappings, defaults to NULL.

 ##' @param data A layer specific dataset -

 ##'             only needed if you want to override the plot defaults.

-##' @param ... other arguments passed on to 'layer'

-##' @param stat Name of stat to modify data

-##' @param position The position adjustment to use for overlapping points on this layer

-##' @param family sans by default, can be any supported font

-##' @param parse if TRUE, the labels will be parsed as expressions

-##' @param nudge_x horizontal adjustment

-##' @param nudge_y vertical adjustment

-##' @param label.padding Amount of padding around label.

-##' @param label.r Radius of rounded corners.

-##' @param label.size Size of label border, in mm

-##' @param na.rm logical

-##' @param show.legend logical

-##' @param inherit.aes logical

+##' @param ... other arguments passed on to 'layer'.

+##' @param stat Name of the stat to modify data.

+##' @param position The position adjustment to use for overlapping points on this layer.

+##' @param family "sans" by default, can be any supported font.

+##' @param parse if 'TRUE', the labels will be parsed as expressions, defaults to 'FALSE'.

+##' @param nudge_x adjust the horizontal position of the labels.

+##' @param nudge_y adjust the vertical position of the labels.

+##' @param label.padding Amount of padding around label, defaults to 'unit(0.25, "lines")'.

+##' @param label.r Use to set the radius of rounded corners of the label, defaults to 'unit(0.15, "lines")'.

+##' @param label.size Size of label border, in mm, defaults to 0.25.

+##' @param na.rm If "FALSE" (default), missing values are removed with a warning. If "TRUE", missing values are silently removed, logical.

+##' @param show.legend Whether to show legend, logical, defaults to "NA".

+##' @param inherit.aes Whether to inherit aesthetic mappings, logical, defaults to "TRUE".

 ##' @return label layer

 ##' @importFrom ggplot2 layer

 ##' @importFrom ggplot2 position_nudge

+##' @examples

+##' library(ggtree)

+##' set.seed(123)

+##' tr<- rtree(15)

+##' x <- ggtree(tr)

+##' x + geom_label2(aes(label = node, subset = isTip == FALSE))

 ##' @export

 ##' @seealso

 ##' [geom_label][ggplot2::geom_label]

 ##' @author Guangchuang Yu

+##' @references

+##' For more detailed demonstration of this function, please refer to chapter A.4.5 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_label2 <- function(mapping = NULL, data = NULL,

                         ...,

                         stat = "identity",

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

-##' add node label layer

+##' add node label layer for a tree

 ##'

 ##'

 ##' @title geom_nodelab

-##' @param mapping aes mapping

-##' @param nudge_x horizontal adjustment to nudge label

-##' @param nudge_y vertical adjustment to nudge label

+##' @param mapping aesthetic mappings, defaults to NULL

+##' @param nudge_x horizontal adjustment to nudge labels, defaults to 0

+##' @param nudge_y vertical adjustment to nudge labels, defaults to 0

 ##' @param geom one of 'text', "shadowtext", 'label', 'image' and 'phylopic'

-##' @param hjust horizontal alignment, one of 0, 0.5 or 1

+##' @param hjust horizontal alignment, defaults to 0.5

 ##' @param node a character indicating which node labels will be displayed,

 ##' it should be one of 'internal', 'external' and 'all'. If it is set to 'internal'

 ##' will display internal node labels, 'external' will display the tip labels,

@@ -17,6 +17,10 @@

 ##' @return geom layer

 ##' @export

 ##' @author Guangchuang Yu

+##' @references    

+##'  For demonstration of this function, please refer to chapter A.4.5 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_nodelab <- function(mapping = NULL, nudge_x = 0, nudge_y = 0, geom = "text", hjust = 0.5, node="internal",...) {

     p <- geom_tiplab(mapping, offset = nudge_x, nudge_y = nudge_y, geom = geom, hjust = hjust, ...)

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

-##' add tip point

+##' add tip point layer for a tree

 ##'

 ##'

 ##' @title geom_tippoint

@@ -7,6 +7,15 @@

 ##' @return tip point layer

 ##' @export

 ##' @author Guangchuang Yu

+##' @examples

+##' library(ggtree)

+##' tr<- rtree(15)

+##' x <- ggtree(tr)

+##' x + geom_tippoint()

+##' @references

+##' For more detailed demonstration, please refer to chapter 4.3.2 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_tippoint <- function(mapping = NULL, data = NULL,

                        position = "identity", na.rm = FALSE,

                           show.legend = NA, inherit.aes = TRUE, ...) {

@@ -49,7 +58,7 @@ geom_tippoint <- function(mapping = NULL, data = NULL,

 ## }

-##' add node point

+##' add node point layer to a tree

 ##'

 ##'

 ##' @title geom_nodepoint

@@ -58,6 +67,14 @@ geom_tippoint <- function(mapping = NULL, data = NULL,

 ##' @importFrom ggplot2 aes_string

 ##' @export

 ##' @author Guangchuang Yu

+##' library(ggtree)

+##' tr<- rtree(15)

+##' x <- ggtree(tr)

+##' x + geom_nodepoint()

+##' @references

+##' For more detailed demonstration, please refer to chapter 4.3.2 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_nodepoint <- function(mapping = NULL, data = NULL,

                        position = "identity", na.rm = FALSE,

                        show.legend = NA, inherit.aes = TRUE, ...) {

@@ -80,9 +97,9 @@ geom_nodepoint <- function(mapping = NULL, data = NULL,

 }

-##' geom_rootpoint is used to add root point

+##' geom_rootpoint is used to add root point layer to a tree

 ##'

-##' geom_rootpoint inherit from geom_point2, it is used to display and customize the points on the root

+##' geom_rootpoint inherit from geom_point2, and it is used to display and customize the points on the root

 ##'

 ##' @title geom_rootpoint

 ##' @inheritParams geom_point2

@@ -136,13 +153,13 @@ geom_rootpoint <- function(mapping = NULL, data = NULL,

 #' If `inherit.aes = TRUE`, the mapping can be inherited from the plot mapping as

 #' specified in the call to `ggplot()`.

 #' @param data The data to be displayed in this layer. If 'NULL' (the default),

-#' the data is inherited from the plot data as specified in the call to 'ggplot()',

+#' the data is inherited from the plot data as specified in the call to `ggplot()`.

 #' @param stat Name of the statistical transformation to be used on the data for this layer.

 #' @param position Position adjustment.

-#' @param na.rm logical. If 'FALSE' (the default), missing values are removed with a warning. If 'TRUE', missing values are silently removed.

+#' @param na.rm logical. If 'FALSE' (default), missing values are removed with a warning. If 'TRUE', missing values are silently removed.

 #' @param show.legend logical. Should this layer be included in the legends?

 #' 'NA', the default, includes if any aesthetics are mapped. 'FALSE' never includes, and 'TRUE' always includes.

-#' @param inherit.aes logical (default is 'TRUE'). If 'FALSE', overrides the default aesthetics,

+#' @param inherit.aes logical (defaults to 'TRUE'). If 'FALSE', overrides the default aesthetics,

 #' rather then combining with them.

 #' @param ... addtional parameters that passed on to this layer. These are often aesthetics, used to set an aesthetic to a fixed value, like `colour = "red"` or `size = 3`.

 #' @importFrom ggplot2 layer

@@ -150,12 +167,12 @@ geom_rootpoint <- function(mapping = NULL, data = NULL,

 #' \code{geom_point2()} understands the following aesthetics

 #'     \itemize{

 #'        \item \code{subset} logical expression indicating elements or rows to keep: missing values are taken as false; should be in aes().

-#'        \item \code{colour} the colour of point, default is black.

-#'        \item \code{fill} the colour of fill, default is black.

-#'        \item \code{alpha} the transparency of fill, default is 1.

-#'        \item \code{size} the size of point, default is 1.5.

-#'        \item \code{shape} specify a shape, default is 19.

-#'        \item \code{stroke} control point border thickness of point, default is 0.5.

+#'        \item \code{colour} the colour of point, defaults to "black".

+#'        \item \code{fill} the colour of fill, defaults to "black".

+#'        \item \code{alpha} the transparency of fill, defaults to 1.

+#'        \item \code{size} the size of point, defaults to 1.5.

+#'        \item \code{shape} specify a shape, defaults to 19.

+#'        \item \code{stroke} control point border thickness of point, defaults to 0.5.

 #'     }

 #' @seealso

 #'  [geom_point][ggplot2::geom_point]; 

@@ -1,14 +1,18 @@

-##' bar of range (HPD, range etc) to present uncertainty of evolutionary inference

+##' horizontal bar of range (HPD, range etc) on nodes to present uncertainty of evolutionary inference

 ##'

 ##'

 ##' @title geom_range

-##' @param range range, e.g. "height_0.95_HPD"

+##' @param range range(interval) to be displayed, e.g. "height_0.95_HPD"

 ##' @param center center of the range, mean, median or auto (default, the center of the range)

 ##' @param ... additional parameter, e.g. color, size, alpha

 ##' @return ggplot layer

 ##' @importFrom ggplot2 aes_string

 ##' @export

 ##' @author Guangchuang Yu

+##' @references  

+##' For demonstration of this function, please refer to chapter 5.2.4 of 

+##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+##' <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 geom_range <- function(range, center = "auto", ...) {

     structure(list(range = range, center = center, ...), class = "geom_range")

 }

@@ -1,17 +1,17 @@

-#' display root edge

+#' display root edge layer for a tree

 #'

-#' `geom_rootedge` is used to create a rootedge. 

+#' `geom_rootedge` is used to create a rootedge as ggtree doesn’t plot the root edge by default. 

 #' 

 #' @title geom_rootedge

-#' @param rootedge length of rootedge; use phylo$root.edge if rootedge = NULL (by default).

+#' @param rootedge length of rootedge; use phylo$root.edge if rootedge = NULL (default).

 #' @param ... additional parameters

 #' 

 #' Additional parameters can be referred to the following parameters:

 #'     \itemize{

-#'         \item \code{size} control the width of rootedge, default is 0.5.

-#'         \item \code{colour} color of rootedge, default is black.

-#'         \item \code{linetype} the type of line, default is 1.

-#'         \item \code{alpha} modify colour transparency, default is 1.

+#'         \item \code{size} control the width of rootedge, defaults to 0.5.

+#'         \item \code{colour} color of rootedge, defaults to black.

+#'         \item \code{linetype} the type of line, defaults to 1.

+#'         \item \code{alpha} modify colour transparency, defaults to 1.

 #'     }

 #

 #' @return ggtree rootedge layer

@@ -22,6 +22,7 @@

 #' visualization and annotation of phylogenetic trees with their covariates and

 #' other associated data. Methods in Ecology and Evolution, 8(1):28-36.

 #' <https://doi.org/10.1111/2041-210X.12628>

+#' 

 #' @export 

 #' @examples 

 #'

@@ -43,8 +44,10 @@

 #' ## this will ignore tree$root.edge

 #' ggtree(tree2) + geom_tiplab() + geom_rootedge(rootedge = 3)

 #' 

-#' ## For more information about tree visualization, please refer to the online book

-#' ## https://yulab-smu.top/treedata-book/chapter4.html

+#' 

+#' ## For more detailed demonstration of this function, please refer to chapter A.4.5 of 

+#' ## *Data Integration, Manipulation and Visualization of Phylogenetic Trees*

+#' ## <http://yulab-smu.top/treedata-book/index.html> by Guangchuang Yu.

 #' 

 geom_rootedge <- function(rootedge = NULL, ...) {

     # add isTip for checking whether the x of tree is reversed.

@@ -1,10 +1,13 @@

-##' add horizontal align lines

+##' add horizontal align lines layer to a tree

+##'

+##' 'geom_aline'align all tips to the longest one by adding 

+##' padding characters to the right side of the tip.

 ##'

 ##'

 ##' @title geom_aline

 ##' @param mapping aes mapping

-##' @param linetype line type

-##' @param size line size

+##' @param linetype set line type of the line, defaults to "dotted"

+##' @param size set line size of the line, defaults to 1

 ##' @param ... additional parameter

 ##' @return aline layer

 ##' @export

@@ -25,17 +28,19 @@ geom_aline <- function(mapping=NULL, linetype="dotted", size=1, ...) {