#### Document update

Document update

William Lee authored on 22/03/2022 14:46:29
Showing30 changed files

 ... ... @@ -2,7 +2,7 @@ 2 2 ##' 3 3 ##' 4 4 ##' @title as.polytomy 5 -##' @param tree tree object 5 +##' @param tree tree object, 'phylo' object only 6 6 ##' @param feature selected feature 7 7 ##' @param fun function to select nodes to collapse 8 8 ##' @return polytomy tree
 ... ... @@ -12,15 +12,20 @@ vexpand <- function(ratio, direction = 1) { 12 12 ggexpand(ratio, direction, side = 'v') 13 13 } 14 14 15 -##' expand xlim (ylim) by ratio of x (y) range 15 +##' expand xlim (ylim) by ratio of x (y) axis range 16 16 ##' 17 17 ##' 18 18 ##' @rdname ggexpand 19 -##' @param ratio expand x (y) limits by amount of xrange (yrange) * ratio 20 -##' @param direction expand x limit at right hand side if direction is 1, or left hand side if direction is -1 21 -##' @param side one of 'h' for horizontal and 'v' for vertical or 'hv' for both. 19 +##' @param ratio expand x (y) axis limits by amount of xrange (yrange) * ratio 20 +##' @param direction expand x axis limit at right hand side if direction is 1 (default), or left hand side if direction is -1 21 +##' @param side one of 'h' for horizontal and 'v' for vertical or 'hv' for both (default). 22 22 ##' @return ggexpand object 23 23 ##' @export 24 +##' @examples 25 +##' x <- rtree(20) 26 +##' x$tip.label <- paste0('RRRRREEEEEAAAAALLLLLYYYYY_Long_Lable_', x$tip.label) 27 +##' p1 <- ggtree(x) + geom_tiplab() 28 +##' p1 + ggexpand(1.5, side = "h") 24 29 ##' @author Guangchuang Yu 25 30 ggexpand <- function(ratio, direction = 1, side = 'hv') { 26 31 side <- match.arg(side, c('h', 'v', 'hv')) ... ... @@ -30,13 +35,21 @@ ggexpand <- function(ratio, direction = 1, side = 'hv') { 30 35 } 31 36 32 37 33 -##' set x axis limits for Tree panel 38 +##' set x axis limits specially for Tree panel 34 39 ##' 35 40 ##' 36 41 ##' @title xlim_tree 37 -##' @param xlim xlim 42 +##' @param xlim x axis limits 38 43 ##' @return updated tree view 39 44 ##' @export 45 +##' @examples 46 +##' x <- rtree(30) 47 +##' p <- ggtree(x) + geom_tiplab() 48 +##' d <- data.frame(label = x$tip.label, 49 +##' value = rnorm(30)) 50 +##' p2 <- p + geom_facet(panel = "Dot", data = d, 51 +##' geom = geom_point, mapping = aes(x = value)) 52 +##' p2 + xlim_tree(6) 40 53 ##' @author Guangchuang Yu 41 54 xlim_tree <- function(xlim) { 42 55 xlim_expand(xlim, panel='Tree') ... ... @@ -47,11 +60,19 @@ xlim_tree <- function(xlim) { 47 60 ##' 48 61 ##' 49 62 ##' @title xlim_expand 50 -##' @param xlim xlim 51 -##' @param panel panel 63 +##' @param xlim x axis limits 64 +##' @param panel name of the panel to expand 52 65 ##' @return updated tree view 53 66 ##' @importFrom ggplot2 geom_blank 54 67 ##' @export 68 +##' @examples 69 +##' x <- rtree(30) 70 +##' p <- ggtree(x) + geom_tiplab() 71 +##' d <- data.frame(label = x$tip.label, 72 +##' value = rnorm(30)) 73 +##' p2 <- p + geom_facet(panel = "Dot", data = d, 74 +##' geom = geom_point, mapping = aes(x = value)) 75 +##' p2 + xlim_expand(c(-10, 10), 'Dot') 55 76 ##' @author Guangchuang Yu 56 77 xlim_expand <- function(xlim, panel) { 57 78 structure(list(x = xlim, panel = panel), class = "facet_xlim") ... ... @@ -61,23 +82,36 @@ xlim_expand <- function(xlim, panel) { 61 82 62 83 ##' add second x-axis for geom_range 63 84 ##' 85 +##' notice that the first axis is disabled in the default theme thus users need to enable it first before using scale_x_range 64 86 ##' 65 87 ##' @title scale_x_range 66 88 ##' @return ggtree object 67 89 ##' @export 90 +##' @references 91 +##' For demonstration of this function ,please refer to chapter 5.2.4 of 92 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 93 +##' by Guangchuang Yu. 68 94 ##' @author Guangchuang Yu 69 95 scale_x_range <- function() { 70 96 structure(list(), class = "range_xaxis") 71 97 } 72 98 73 99 74 -##' reverse timescle x-axis 100 +##' reverse timescle x-axis by setting the most recent tip to 0 101 +##' 102 +##' 'scale_x_continuous(labels=abs)' is required if users want to set the x-axis lable to absolute value 75 103 ##' 76 104 ##' 77 105 ##' @title revts 78 -##' @param treeview treeview 79 -##' @return updated treeview 106 +##' @param treeview original tree view 107 +##' @return updated tree view 80 108 ##' @export 109 +##' @examples 110 +##' tr <- rtree(10) 111 +##' p <- ggtree(tr) + theme_tree2() 112 +##' p2 <- revts(p) 113 +##' p3 <- p2 + scale_x_continuous(labels=abs) 114 +##' plot_list(p, p2, p3, ncol=3, tag_levels="A") 81 115 ##' @author Guangchuang Yu 82 116 revts <- function(treeview) { 83 117 x <- treeview$data$x
 ... ... @@ -1,9 +1,9 @@ 1 -##' label facet_plot output 1 +##' function to relable selected panels created by 'geom_facet' or 'facet-plot' 2 2 ##' 3 3 ##' 4 4 ##' @title facet_labeller 5 5 ##' @param p facet_plot output 6 -##' @param label labels of facet panels 6 +##' @param label new labels of facet panels 7 7 ##' @return ggplot object 8 8 ##' @importFrom ggplot2 as_labeller 9 9 ##' @export
 ... ... @@ -2,11 +2,13 @@ 2 2 3 3 ##' zoom selected clade of a tree 4 4 ##' 5 +##' 'geom_zoom_clade' zooms in on a selected clade of a tree, 6 +##' while showing its on the full view of tree as a seperated panel for reference 5 7 ##' 6 8 ##' @title geom_zoom_clade 7 -##' @param node internal node number 8 -##' @param xexpand numeric, extend x, meaning the ratio of range of original x, 9 -##' default is NULL. 9 +##' @param node internal node number to zoom in its corresponding clade 10 +##' @param xexpand numeric, extend x, meaning the ratio of range of the xlim of the original tree, 11 +##' defaults to NULL. 10 12 ##' @return updated tree view 11 13 ##' @author Guangchuang Yu 12 14 ##' @export
 ... ... @@ -4,20 +4,32 @@ 4 4 #' correspond to multichotomies will not be displayed. 5 5 #' 6 6 #' @title geom_balance 7 -#' @param node selected node (balance) to highlight 8 -#' @param fill color fill 9 -#' @param color color to outline highlights and divide balance 10 -#' @param alpha alpha (transparency) 11 -#' @param extend extend xmax of the rectangle 12 -#' @param extendto extend xmax to extendto 7 +#' @param node selected node (balance) to highlight its two direct descendant 8 +#' @param fill color to fill in the highlight rectangle, default to "steelblue" 9 +#' @param color color to outline highlight rectangle and divide balance, defaults to "white" 10 +#' @param alpha alpha (transparency) for the highlight rectangle, defaults to 0.5 11 +#' @param extend extend xmax of the highlight rectangle by the value of extend 12 +#' @param extendto extend xmax of the highlight rectangle to the value of extendto 13 13 #' @return ggplot2 14 14 #' @export 15 15 #' @importFrom ggplot2 aes_ 16 16 #' @importFrom ggplot2 GeomRect 17 17 #' @importFrom utils packageVersion 18 18 #' @author Justin Silverman and modified by Guangchuang Yu 19 -#' @references J. Silverman, et al. *A phylogenetic transform enhances 20 -#' analysis of compositional microbiota data*. (in preparation) 19 +#' @examples 20 +#' library(ggtree) 21 +#' set.seed(123) 22 +#' tr<- rtree(15) 23 +#' x <- ggtree(tr) 24 +#' x + geom_balance(17) 25 +#' 26 +#' @references 27 +#' J. Silverman, et al. *A phylogenetic transform enhances 28 +#' analysis of compositional microbiota data*. (in preparation) 29 +#' 30 +#' For more detailed demonstration, please refer to chapter 5.2.2 of 31 +#' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 32 +#' by Guangchuang Yu. 21 33 geom_balance <- function(node, fill="steelblue", color='white', alpha=.5, extend=0, extendto=NULL) { 22 34 23 35 data = NULL
 ... ... @@ -3,30 +3,30 @@ 3 3 ##' @title geom_cladelab 4 4 ##' @param node selected node to annotate, when data and mapping is NULL, it is required. 5 5 ##' @param label character, character to be showed, when data and mapping is NULL, it is required. 6 -##' @param data data.frame, the data to be displayed in the annotation, default is NULL. 7 -##' @param mapping Set of aesthetic mappings, default is NULL. The detail see the following explanation. 6 +##' @param data data.frame, the data to be displayed in the annotation, defaults to NULL. 7 +##' @param mapping Set of aesthetic mappings, defaults to NULL. The detail see the following explanation. 8 8 ##' @param geom character, one of 'text', 'label', 'shadowtext', 'image' and 'phylopic', 9 -##' default is 'text', and the parameter see the Aesthetics For Specified Geom. 10 -##' @param parse logical, whether parse label to emoji font, default is FALSE. 9 +##' defaults to 'text', and the parameter see the Aesthetics For Specified Geom. 10 +##' @param parse logical, whether parse label to emoji font, defaults to FALSE. 11 11 ##' @param ... additional parameters, see also following section. 12 12 ##' 13 13 ##' additional parameters can refer the following parameters. 14 14 ##' \itemize{ 15 15 ##' \item \code{offset} distance bar and tree, offset of bar and text from 16 -##' the clade, default is 0. 16 +##' the clade, defaults to 0. 17 17 ##' \item \code{offset.text} distance bar and text, offset of text from bar, 18 -##' default is 0. 19 -##' \item \code{align} logical, whether align clade lab, default is FALSE. 20 -##' \item \code{extend} numeric, extend the length of bar, default is 0. 18 +##' defaults to 0. 19 +##' \item \code{align} logical, whether align clade lab, defaults to FALSE. 20 +##' \item \code{extend} numeric, extend the length of bar, defaults to 0. 21 21 ##' \item \code{angle} numeric or 'auto', if angle is auto, the angle of text will 22 -##' be calculated automatically, which is useful for the circular etc layout, default is 0. 23 -##' \item \code{horizontal} logical, whether set label to horizontal, default is TRUE. 24 -##' \item \code{barsize} the width of line, default is 0.5. 25 -##' \item \code{barcolour} the colour of line, default is 'black'. 26 -##' \item \code{fontsize} the size of text, default is 3.88. 27 -##' \item \code{textcolour} the colour of text, default is 'black'. 28 -##' \item \code{imagesize} the size of image, default is 0.05. 29 -##' \item \code{imagecolor} the colour of image, default is NULL, when 22 +##' be calculated automatically, which is useful for the circular etc layout, defaults to 0. 23 +##' \item \code{horizontal} logical, whether set label to horizontal, defaults to TRUE. 24 +##' \item \code{barsize} the width of line, defaults to 0.5. 25 +##' \item \code{barcolour} the colour of line, defaults to 'black'. 26 +##' \item \code{fontsize} the size of text, defaults to 3.88. 27 +##' \item \code{textcolour} the colour of text, defaults to 'black'. 28 +##' \item \code{imagesize} the size of image, defaults to 0.05. 29 +##' \item \code{imagecolor} the colour of image, defaults to NULL, when 30 30 ##' geom="phylopic", it should be required. 31 31 ##' } 32 32 ##' The parameters also can be set in mapping, when data is provided. Note: the barsize, barcolour, ... ... @@ -40,16 +40,16 @@ 40 40 ##' \itemize{ 41 41 ##' \item \strong{\code{node}} selected node to hight light, it is required. 42 42 ##' \item \strong{\code{label}} labels showed, it is required. 43 -##' \item \code{colour} the colour of text, default is "black". 44 -##' \item \code{size} the size of text, default is 3.88. 45 -##' \item \code{angle} the angle of text, default is 0. 46 -##' \item \code{hjust} A numeric vector specifying horizontal justification, default is 0. 47 -##' \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5. 48 -##' \item \code{alpha} the transparency of text, default is NA. 49 -##' \item \code{family} the family of text, default is 'sans'. 50 -##' \item \code{fontface} the font face of text, default is 1 (plain), others are 43 +##' \item \code{colour} the colour of text, defaults to "black". 44 +##' \item \code{size} the size of text, defaults to 3.88. 45 +##' \item \code{angle} the angle of text, defaults to 0. 46 +##' \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0. 47 +##' \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5. 48 +##' \item \code{alpha} the transparency of text, defaults to NA. 49 +##' \item \code{family} the family of text, defaults to 'sans'. 50 +##' \item \code{fontface} the font face of text, defaults to 1 (plain), others are 51 51 ##' 2 (bold), 3 (italic), 4 (bold.italic). 52 -##' \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 . 52 +##' \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 . 53 53 ##' } 54 54 ##' when the colour, size are not be set in mapping, and user want to modify the colour of text, 55 55 ##' they should use textcolour, fontsize to avoid the confusion with bar layer annotation. ... ... @@ -59,17 +59,17 @@ 59 59 ##' \itemize{ 60 60 ##' \item \strong{\code{node}} selected node to hight light, it is required. 61 61 ##' \item \strong{\code{label}} labels to be showed, it is required. 62 -##' \item \code{colour} the colour of text, default is "black". 63 -##' \item \code{fill} the background colour of the label, default is "white". 64 -##' \item \code{size} the size of text, default is 3.88. 65 -##' \item \code{angle} the angle of text, default is 0. 66 -##' \item \code{hjust} A numeric vector specifying horizontal justification, default is 0. 67 -##' \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5. 68 -##' \item \code{alpha} the transparency of text, default is NA. 69 -##' \item \code{family} the family of text, default is 'sans'. 70 -##' \item \code{fontface} the font face of text, default is 1 (plain), others are 62 +##' \item \code{colour} the colour of text, defaults to "black". 63 +##' \item \code{fill} the background colour of the label, defaults to "white". 64 +##' \item \code{size} the size of text, defaults to 3.88. 65 +##' \item \code{angle} the angle of text, defaults to 0. 66 +##' \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0. 67 +##' \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5. 68 +##' \item \code{alpha} the transparency of text, defaults to NA. 69 +##' \item \code{family} the family of text, defaults to 'sans'. 70 +##' \item \code{fontface} the font face of text, defaults to 1 (plain), others are 71 71 ##' 2 (bold), 3 (italic), 4 (bold.italic). 72 -##' \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 . 72 +##' \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 . 73 73 ##' } 74 74 ##' when the colour, size are not be set in mapping, and user want to modify the colour of text, 75 75 ##' they should use textcolour, fontsize to avoid the confusion with bar layer annotation. ... ... @@ -79,18 +79,18 @@ 79 79 ##' \itemize{ 80 80 ##' \item \strong{\code{node}} selected node to hight light, it is required. 81 81 ##' \item \strong{\code{label}} labels to be showed, it is required. 82 -##' \item \code{colour} the colour of text, default is "black". 83 -##' \item \code{bg.colour} the background colour of text, default is 'black'. 84 -##' \item \code{bg.r} the width of background text, default is 0.1. 85 -##' \item \code{size} the size of text, default is 3.88. 86 -##' \item \code{angle} the angle of text, default is 0. 87 -##' \item \code{hjust} A numeric vector specifying horizontal justification, default is 0. 88 -##' \item \code{vjust} A numeric vector specifying vertical justification, default is 0.5. 89 -##' \item \code{alpha} the transparency of text, default is NA. 90 -##' \item \code{family} the family of text, default is 'sans'. 91 -##' \item \code{fontface} the font face of text, default is 1 (plain), others are 82 +##' \item \code{colour} the colour of text, defaults to "black". 83 +##' \item \code{bg.colour} the background colour of text, defaults to 'black'. 84 +##' \item \code{bg.r} the width of background text, defaults to 0.1. 85 +##' \item \code{size} the size of text, defaults to 3.88. 86 +##' \item \code{angle} the angle of text, defaults to 0. 87 +##' \item \code{hjust} A numeric vector specifying horizontal justification, defaults to 0. 88 +##' \item \code{vjust} A numeric vector specifying vertical justification, defaults to 0.5. 89 +##' \item \code{alpha} the transparency of text, defaults to NA. 90 +##' \item \code{family} the family of text, defaults to 'sans'. 91 +##' \item \code{fontface} the font face of text, defaults to 1 (plain), others are 92 92 ##' 2 (bold), 3 (italic), 4 (bold.italic). 93 -##' \item \code{lineheight} The height of a line as a multiple of the size of text, default is 1.2 . 93 +##' \item \code{lineheight} The height of a line as a multiple of the size of text, defaults to 1.2 . 94 94 ##' } 95 95 ##' when the colour, size are not be set in mapping, and user want to modify the colour of text, 96 96 ##' they should use textcolour, fontsize to avoid the confusion with bar layer annotation. ... ... @@ -102,9 +102,9 @@ 102 102 ##' \item \strong{\code{label}} labels to be showed, it is required. 103 103 ##' \item \strong{\code{image}} the image to be annotated, when geom="phylopic", 104 104 ##' the uid of phylopic databases, it is required. 105 -##' \item \code{colour} the color of image, default is NULL. 106 -##' \item \code{size} the size of image, default is 0.05. 107 -##' \item \code{alpha} the alpha of image, default is 0.8. 105 +##' \item \code{colour} the color of image, defaults to NULL. 106 +##' \item \code{size} the size of image, defaults to 0.05. 107 +##' \item \code{alpha} the alpha of image, defaults to 0.8. 108 108 ##' } 109 109 ##' when the colour, size are not be set in mapping, and user want to modify the colour of image, 110 110 ##' they should use imagecolour, imagesize to avoid the confusion with bar layer annotation.
 ... ... @@ -18,7 +18,7 @@ 18 18 ##' @param family sans by default, can be any supported font 19 19 ##' @param parse logical, whether parse label 20 20 ##' @param horizontal logical, whether set label to horizontal, 21 -##' default is TRUE. 21 +##' defaults to TRUE. 22 22 ##' @param ... additional parameter 23 23 ##' @return ggplot layers 24 24 ##' @export
 ... ... @@ -5,10 +5,10 @@ 5 5 #' 6 6 #' @title geom_hilight 7 7 #' @rdname geom-hilight 8 -#' @param data data.frame, The data to be displayed in this layer, default is NULL. 9 -#' @param mapping Set of aesthetic mappings, default is NULL. 8 +#' @param data data.frame, The data to be displayed in this layer, defaults to NULL. 9 +#' @param mapping Set of aesthetic mappings, defaults to NULL. 10 10 #' @param node selected node to hilight, when data and mapping is NULL, it is required. 11 -#' @param type the type of layer, default is auto, meaning rectangular, circular, 11 +#' @param type the type of layer, defaults to auto, meaning rectangular, circular, 12 12 #' slanted, fan, inward_circular, radial, equal_angle, ape layout tree will use rectangular layer, 13 13 #' unrooted and daylight layout tree use will use encircle layer. You can specify this parameter to 14 14 #' rect (rectangular layer) or encircle (encircle layer), 'gradient' (gradient color), ... ... @@ -18,39 +18,39 @@ 18 18 #' \item \code{align} control the align direction of the edge of high light rectangular. 19 19 #' Options is 'none' (default), 'left', 'right', 'both'. This argument only work when the 20 20 #' 'geom_hilight' is plotting using geom_hilight(mapping=aes(...)). 21 -#' \item \code{gradient.direction} character, the direction of gradient color, default is 'rt' 21 +#' \item \code{gradient.direction} character, the direction of gradient color, defaults to 'rt' 22 22 #' meaning the locations of gradient color is from root to tip, options are 'rt' and 'tr'. 23 23 #' \item \code{gradient.length.out} integer, desired length of the sequence of gradient color, 24 -#' default is 2. 24 +#' defaults to 2. 25 25 #' \item \code{roundrect.r} numeric, the radius of the rounded corners, when \code{roundrect=TRUE}, 26 -#' default is 0.05. 26 +#' defaults to 0.05. 27 27 #' } 28 28 #' @section Aesthetics: 29 29 #' \code{geom_hilight()} understands the following aesthetics for rectangular layer (required 30 30 #' aesthetics are in bold): 31 31 #' \itemize{ 32 32 #' \item \strong{\code{node}} selected node to hight light, it is required. 33 -#' \item \code{colour} the colour of margin, default is NA. 34 -#' \item \code{fill} the colour of fill, default is 'steelblue'. 35 -#' \item \code{alpha} the transparency of fill, default is 0.5. 36 -#' \item \code{extend} extend xmax of the rectangle, default is 0. 37 -#' \item \code{extendto} specify a value, meaning the rectangle extend to, default is NULL. 38 -#' \item \code{linetype} the line type of margin, default is 1. 39 -#' \item \code{size} the width of line of margin, default is 0.5. 33 +#' \item \code{colour} the colour of margin, defaults to NA. 34 +#' \item \code{fill} the colour of fill, defaults to 'steelblue'. 35 +#' \item \code{alpha} the transparency of fill, defaults to 0.5. 36 +#' \item \code{extend} extend xmax of the rectangle, defaults to 0. 37 +#' \item \code{extendto} specify a value, meaning the rectangle extend to, defaults to NULL. 38 +#' \item \code{linetype} the line type of margin, defaults to 1. 39 +#' \item \code{size} the width of line of margin, defaults to 0.5. 40 40 #' } 41 41 #' \code{geom_hilight()} understands the following aesthethics for encircle layer (required 42 42 #' aesthetics are in bold): 43 43 #' \itemize{ 44 44 #' \item \strong{\code{node}} selected node to hight light, it is required. 45 -#' \item \code{colour} the colour of margin, default is 'black'. 46 -#' \item \code{fill} the colour of fill, default is 'steelblue'. 47 -#' \item \code{alpha} the transparency of fill, default is 0.5. 48 -#' \item \code{expand} expands the xspline clade region, default is 0. 45 +#' \item \code{colour} the colour of margin, defaults to 'black'. 46 +#' \item \code{fill} the colour of fill, defaults to 'steelblue'. 47 +#' \item \code{alpha} the transparency of fill, defaults to 0.5. 48 +#' \item \code{expand} expands the xspline clade region, defaults to 0. 49 49 #' \item \code{spread} control the size, when only one point. 50 -#' \item \code{size} the width of line of margin, default is 0.5. 51 -#' \item \code{linetype} the line type of margin, default is 1. 52 -#' \item \code{s_shape} the shape of the spline relative to the control points, default is 0.5. 53 -#' \item \code{s_open} whether the spline is a line or a closed shape, default is FALSE. 50 +#' \item \code{size} the width of line of margin, defaults to 0.5. 51 +#' \item \code{linetype} the line type of margin, defaults to 1. 52 +#' \item \code{s_shape} the shape of the spline relative to the control points, defaults to 0.5. 53 +#' \item \code{s_open} whether the spline is a line or a closed shape, defaults to FALSE. 54 54 #' } 55 55 #' @return a list object. 56 56 #' @author Guangchuang Yu and Shuangbin Xu ... ... @@ -74,6 +74,10 @@ 74 74 #' # display the high light layer with round rectangular. 75 75 #' p8 <- p + geom_hilight(data=dat, mapping=aes(node=id, fill=type), type = "roundrect", alpha=0.68) 76 76 #' p2/ p3/ p4/ p5 / p6/ p7/ p8 77 +#' @references 78 +#' For more detailed demonstration, please refer to chapter 5.2.2 of 79 +#' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 80 +#' by Guangchuang Yu. 77 81 geom_hilight <- function(data=NULL, 78 82 mapping=NULL, 79 83 node=NULL,
 ... ... @@ -1,12 +1,12 @@ 1 -##' add node label layer 1 +##' add node label layer for a tree 2 2 ##' 3 3 ##' 4 4 ##' @title geom_nodelab 5 -##' @param mapping aes mapping 6 -##' @param nudge_x horizontal adjustment to nudge label 7 -##' @param nudge_y vertical adjustment to nudge label 5 +##' @param mapping aesthetic mappings, defaults to NULL 6 +##' @param nudge_x horizontal adjustment to nudge labels, defaults to 0 7 +##' @param nudge_y vertical adjustment to nudge labels, defaults to 0 8 8 ##' @param geom one of 'text', "shadowtext", 'label', 'image' and 'phylopic' 9 -##' @param hjust horizontal alignment, one of 0, 0.5 or 1 9 +##' @param hjust horizontal alignment, defaults to 0.5 10 10 ##' @param node a character indicating which node labels will be displayed, 11 11 ##' it should be one of 'internal', 'external' and 'all'. If it is set to 'internal' 12 12 ##' will display internal node labels, 'external' will display the tip labels, ... ... @@ -17,6 +17,10 @@ 17 17 ##' @return geom layer 18 18 ##' @export 19 19 ##' @author Guangchuang Yu 20 +##' @references 21 +##' For demonstration of this function, please refer to chapter A.4.5 of 22 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 23 +##' by Guangchuang Yu. 20 24 geom_nodelab <- function(mapping = NULL, nudge_x = 0, nudge_y = 0, geom = "text", hjust = 0.5, node="internal",...) { 21 25 22 26 p <- geom_tiplab(mapping, offset = nudge_x, nudge_y = nudge_y, geom = geom, hjust = hjust, ...)
 ... ... @@ -1,5 +1,5 @@ 1 1 2 -##' add tip point 2 +##' add tip point layer for a tree 3 3 ##' 4 4 ##' 5 5 ##' @title geom_tippoint ... ... @@ -7,6 +7,15 @@ 7 7 ##' @return tip point layer 8 8 ##' @export 9 9 ##' @author Guangchuang Yu 10 +##' @examples 11 +##' library(ggtree) 12 +##' tr<- rtree(15) 13 +##' x <- ggtree(tr) 14 +##' x + geom_tippoint() 15 +##' @references 16 +##' For more detailed demonstration, please refer to chapter 4.3.2 of 17 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 18 +##' by Guangchuang Yu. 10 19 geom_tippoint <- function(mapping = NULL, data = NULL, 11 20 position = "identity", na.rm = FALSE, 12 21 show.legend = NA, inherit.aes = TRUE, ...) { ... ... @@ -49,7 +58,7 @@ geom_tippoint <- function(mapping = NULL, data = NULL, 49 58 ## } 50 59 51 60 52 -##' add node point 61 +##' add node point layer to a tree 53 62 ##' 54 63 ##' 55 64 ##' @title geom_nodepoint ... ... @@ -58,6 +67,14 @@ geom_tippoint <- function(mapping = NULL, data = NULL, 58 67 ##' @importFrom ggplot2 aes_string 59 68 ##' @export 60 69 ##' @author Guangchuang Yu 70 +##' library(ggtree) 71 +##' tr<- rtree(15) 72 +##' x <- ggtree(tr) 73 +##' x + geom_nodepoint() 74 +##' @references 75 +##' For more detailed demonstration, please refer to chapter 4.3.2 of 76 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 77 +##' by Guangchuang Yu. 61 78 geom_nodepoint <- function(mapping = NULL, data = NULL, 62 79 position = "identity", na.rm = FALSE, 63 80 show.legend = NA, inherit.aes = TRUE, ...) { ... ... @@ -80,9 +97,9 @@ geom_nodepoint <- function(mapping = NULL, data = NULL, 80 97 } 81 98 82 99 83 -##' geom_rootpoint is used to add root point 100 +##' geom_rootpoint is used to add root point layer to a tree 84 101 ##' 85 -##' geom_rootpoint inherit from geom_point2, it is used to display and customize the points on the root 102 +##' geom_rootpoint inherit from geom_point2, and it is used to display and customize the points on the root 86 103 ##' 87 104 ##' @title geom_rootpoint 88 105 ##' @inheritParams geom_point2 ... ... @@ -136,13 +153,13 @@ geom_rootpoint <- function(mapping = NULL, data = NULL, 136 153 #' If inherit.aes = TRUE, the mapping can be inherited from the plot mapping as 137 154 #' specified in the call to ggplot(). 138 155 #' @param data The data to be displayed in this layer. If 'NULL' (the default), 139 -#' the data is inherited from the plot data as specified in the call to 'ggplot()', 156 +#' the data is inherited from the plot data as specified in the call to ggplot(). 140 157 #' @param stat Name of the statistical transformation to be used on the data for this layer. 141 158 #' @param position Position adjustment. 142 -#' @param na.rm logical. If 'FALSE' (the default), missing values are removed with a warning. If 'TRUE', missing values are silently removed. 159 +#' @param na.rm logical. If 'FALSE' (default), missing values are removed with a warning. If 'TRUE', missing values are silently removed. 143 160 #' @param show.legend logical. Should this layer be included in the legends? 144 161 #' 'NA', the default, includes if any aesthetics are mapped. 'FALSE' never includes, and 'TRUE' always includes. 145 -#' @param inherit.aes logical (default is 'TRUE'). If 'FALSE', overrides the default aesthetics, 162 +#' @param inherit.aes logical (defaults to 'TRUE'). If 'FALSE', overrides the default aesthetics, 146 163 #' rather then combining with them. 147 164 #' @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. 148 165 #' @importFrom ggplot2 layer ... ... @@ -150,12 +167,12 @@ geom_rootpoint <- function(mapping = NULL, data = NULL, 150 167 #' \code{geom_point2()} understands the following aesthetics 151 168 #' \itemize{ 152 169 #' \item \code{subset} logical expression indicating elements or rows to keep: missing values are taken as false; should be in aes(). 153 -#' \item \code{colour} the colour of point, default is black. 154 -#' \item \code{fill} the colour of fill, default is black. 155 -#' \item \code{alpha} the transparency of fill, default is 1. 156 -#' \item \code{size} the size of point, default is 1.5. 157 -#' \item \code{shape} specify a shape, default is 19. 158 -#' \item \code{stroke} control point border thickness of point, default is 0.5. 170 +#' \item \code{colour} the colour of point, defaults to "black". 171 +#' \item \code{fill} the colour of fill, defaults to "black". 172 +#' \item \code{alpha} the transparency of fill, defaults to 1. 173 +#' \item \code{size} the size of point, defaults to 1.5. 174 +#' \item \code{shape} specify a shape, defaults to 19. 175 +#' \item \code{stroke} control point border thickness of point, defaults to 0.5. 159 176 #' } 160 177 #' @seealso 161 178 #' [geom_point][ggplot2::geom_point];
 ... ... @@ -1,14 +1,18 @@ 1 -##' bar of range (HPD, range etc) to present uncertainty of evolutionary inference 1 +##' horizontal bar of range (HPD, range etc) on nodes to present uncertainty of evolutionary inference 2 2 ##' 3 3 ##' 4 4 ##' @title geom_range 5 -##' @param range range, e.g. "height_0.95_HPD" 5 +##' @param range range(interval) to be displayed, e.g. "height_0.95_HPD" 6 6 ##' @param center center of the range, mean, median or auto (default, the center of the range) 7 7 ##' @param ... additional parameter, e.g. color, size, alpha 8 8 ##' @return ggplot layer 9 9 ##' @importFrom ggplot2 aes_string 10 10 ##' @export 11 11 ##' @author Guangchuang Yu 12 +##' @references 13 +##' For demonstration of this function, please refer to chapter 5.2.4 of 14 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 15 +##' by Guangchuang Yu. 12 16 geom_range <- function(range, center = "auto", ...) { 13 17 structure(list(range = range, center = center, ...), class = "geom_range") 14 18 }
 ... ... @@ -1,17 +1,17 @@ 1 -#' display root edge 1 +#' display root edge layer for a tree 2 2 #' 3 -#' geom_rootedge is used to create a rootedge. 3 +#' geom_rootedge is used to create a rootedge as ggtree doesn’t plot the root edge by default. 4 4 #' 5 5 #' @title geom_rootedge 6 -#' @param rootedge length of rootedge; use phylo$root.edge if rootedge = NULL (by default). 6 +#' @param rootedge length of rootedge; use phylo$root.edge if rootedge = NULL (default). 7 7 #' @param ... additional parameters 8 8 #' 9 9 #' Additional parameters can be referred to the following parameters: 10 10 #' \itemize{ 11 -#' \item \code{size} control the width of rootedge, default is 0.5. 12 -#' \item \code{colour} color of rootedge, default is black. 13 -#' \item \code{linetype} the type of line, default is 1. 14 -#' \item \code{alpha} modify colour transparency, default is 1. 11 +#' \item \code{size} control the width of rootedge, defaults to 0.5. 12 +#' \item \code{colour} color of rootedge, defaults to black. 13 +#' \item \code{linetype} the type of line, defaults to 1. 14 +#' \item \code{alpha} modify colour transparency, defaults to 1. 15 15 #' } 16 16 # 17 17 #' @return ggtree rootedge layer ... ... @@ -22,6 +22,7 @@ 22 22 #' visualization and annotation of phylogenetic trees with their covariates and 23 23 #' other associated data. Methods in Ecology and Evolution, 8(1):28-36. 24 24 #' 25 +#' 25 26 #' @export 26 27 #' @examples 27 28 #' ... ... @@ -43,8 +44,10 @@ 43 44 #' ## this will ignore tree\$root.edge 44 45 #' ggtree(tree2) + geom_tiplab() + geom_rootedge(rootedge = 3) 45 46 #' 46 -#' ## For more information about tree visualization, please refer to the online book 47 -#' ## https://yulab-smu.top/treedata-book/chapter4.html 47 +#' 48 +#' ## For more detailed demonstration of this function, please refer to chapter A.4.5 of 49 +#' ## *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 50 +#' ## by Guangchuang Yu. 48 51 #' 49 52 geom_rootedge <- function(rootedge = NULL, ...) { 50 53 # add isTip for checking whether the x of tree is reversed.
 ... ... @@ -1,10 +1,13 @@ 1 -##' add horizontal align lines 1 +##' add horizontal align lines layer to a tree 2 +##' 3 +##' 'geom_aline'align all tips to the longest one by adding 4 +##' padding characters to the right side of the tip. 2 5 ##' 3 6 ##' 4 7 ##' @title geom_aline 5 8 ##' @param mapping aes mapping 6 -##' @param linetype line type 7 -##' @param size line size 9 +##' @param linetype set line type of the line, defaults to "dotted" 10 +##' @param size set line size of the line, defaults to 1 8 11 ##' @param ... additional parameter 9 12 ##' @return aline layer 10 13 ##' @export ... ... @@ -25,17 +28,19 @@ geom_aline <- function(mapping=NULL, linetype="dotted", size=1, ...) { 25 28 26 29 ##' geom_segment2 support aes(subset) via setup_data 27 30 ##' 31 +##' 'geom_segment2' is a modified version of geom_segment, with subset aesthetic supported 28 32 ##' 29 33 ##' @title geom_segment2 30 -##' @param mapping aes mapping 31 -##' @param data data 32 -##' @param stat Name of stat to modify data 33 -##' @param position position 34 -##' @param lineend lineend 35 -##' @param na.rm logical 36 -##' @param show.legend logical 37 -##' @param inherit.aes logical 38 -##' @param nudge_x horizontal adjustment of x 34 +##' @param mapping Set of aesthetic mappings, defaults to NULL 35 +##' @param data A layer specific dataset - 36 +##' only needed if you want to override the plot defaults. 37 +##' @param stat Name of stat to modify data. 38 +##' @param position The position adjustment to use for overlapping points on this layer. 39 +##' @param lineend Line end style, one of butt (default), round and square. 40 +##' @param na.rm If "FALSE" (default), missing values are removed with a warning. If "TRUE", missing values are silently removed, logical. 41 +##' @param show.legend Whether to show legend, logical. 42 +##' @param inherit.aes Whether to inherit aesthetic mappings, logical, defaults to "TRUE". 43 +##' @param nudge_x adjust the horizontal position of the segments. 39 44 ##' @param arrow specification for arrow heads, as created by arrow(). 40 45 ##' @param arrow.fill fill color to usse for the arrow head (if closed). NULL means use colour aesthetic. 41 46 ##' @param ... additional parameter
 ... ... @@ -4,24 +4,34 @@ 4 4 ##' @title geom_strip 5 5 ##' @param taxa1 taxa1 6 6 ##' @param taxa2 taxa2 7 -##' @param label optional label 7 +##' @param label add label alongside the bar (optional) 8 8 ##' @param offset offset of bar and text from the clade 9 9 ##' @param offset.text offset of text from bar 10 -##' @param align logical 11 -##' @param barsize size of bar 12 -##' @param extend extend bar vertically 13 -##' @param fontsize size of text 14 -##' @param angle angle of text 10 +##' @param align logical, whether to align bars to the most distant bar ,defaults to "TRUE" 11 +##' Note that if "FALSE", the bars might cross the tree 12 +##' @param barsize set size of the bar 13 +##' @param extend extend bar length vertically 14 +##' @param fontsize set size of the text 15 +##' @param angle set the angle of text 15 16 ##' @param geom one of 'text' or 'label' 16 -##' @param hjust hjust 17 -##' @param color color for bar and label 18 -##' @param fill fill label background, only work with geom='label' 19 -##' @param family sans by default, can be any supported font 20 -##' @param parse logical, whether parse label 17 +##' @param hjust adjust the horizonal position of the bar 18 +##' @param color set color for bar and label 19 +##' @param fill set color to fill label background, only work with geom='label' 20 +##' @param family "sans" by default, can be any supported font 21 +##' @param parse logical, whether to parse labels, if "TRUE", the labels will be parsed into expressions, defaults to "FALSE" 21 22 ##' @param ... additional parameter 22 23 ##' @return ggplot layers 23 24 ##' @export 24 25 ##' @author Guangchuang Yu 26 +##' @examples 27 +##' library(ggtree) 28 +##' tr<- rtree(15) 29 +##' x <- ggtree(tr) 30 +##' x + geom_strip(13, 1, color = "red") + geom_strip(3, 7, color = "blue") 31 +##' @references 32 +##' For more detailed demonstration of this function, please refer to chapter 5.2.1 of 33 +##' *Data Integration, Manipulation and Visualization of Phylogenetic Trees* 34 +##' by Guangchuang Yu. 25 35 geom_strip <- function(taxa1, taxa2, label, offset=0, offset.text=0, 26 36 align=TRUE, barsize=0.5, extend=0, fontsize=3.88, 27 37 angle=0, geom="text", hjust=0, color = 'black', fill=NA, family="sans",