man/nodelabels.Rd

   1 \name{nodelabels}
   2 \alias{nodelabels}
   3 \alias{tiplabels}
   4 \alias{edgelabels}
   5 \title{Labelling the Nodes, Tips, and Edges of a Tree}
   6 \description{
   7   These functions add labels to or near the nodes, the tips, or the
   8   edges of a tree using text or plotting symbols. The text can be
   9   framed.
  10 }
  11 \usage{
  12 nodelabels(text, node, adj = c(0.5, 0.5), frame = "rect",
  13            pch = NULL, thermo = NULL, pie = NULL, piecol = NULL,
  14            col = "black", bg = "lightblue", ...)
  15 tiplabels(text, tip, adj = c(0.5, 0.5), frame = "rect",
  16           pch = NULL, thermo = NULL, pie = NULL, piecol = NULL,
  17           col = "black", bg = "yellow", ...)
  18 edgelabels(text, edge, adj = c(0.5, 0.5), frame = "rect",
  19            pch = NULL, thermo = NULL, pie = NULL, piecol = NULL,
  20            col = "black", bg = "lightgreen", ...)
  21
  22 }
  23 \arguments{
  24   \item{text}{a vector of mode character giving the text to be
  25     printed. Can be left empty.}
  26   \item{node}{a vector of mode numeric giving the numbers of the nodes
  27     where the text or the symbols are to be printed. Can be left empty.}
  28   \item{tip}{a vector of mode numeric giving the numbers of the tips
  29     where the text or the symbols are to be printed. Can be left empty.}
  30   \item{edge}{a vector of mode numeric giving the numbers of the edges
  31     where the text or the symbols are to be printed. Can be left empty.}
  32   \item{adj}{one or two numeric values specifying the horizontal and
  33     vertical, respectively, justification of the text or symbols. By
  34     default, the text is centered horizontally and vertically. If a
  35     single value is given, this alters only the horizontal position of
  36     the text.}
  37   \item{frame}{a character string specifying the kind of frame to be
  38     printed around the text. This must be one of "rect" (the default),
  39     "circle", "none", or any unambiguous abbreviation of these.}
  40   \item{pch}{a numeric giving the type of plotting symbol to be used;
  41     this is eventually recycled. See \code{\link[graphics]{par}} for R's
  42     plotting symbols. If \code{pch} is used, then \code{text} is
  43     ignored.}
  44   \item{thermo}{a numeric vector giving some proportions (values between
  45     0 and 1) for each node, or a numeric matrix giving some proportions
  46     (the rows must sum to one).}
  47   \item{pie}{same than \code{thermo}.}
  48   \item{piecol}{a list of colours (given as a character vector) to be
  49     used by \code{thermo} or \code{pie}; if left \code{NULL}, a series
  50     of colours given by the function \code{rainbow} is used.}
  51   \item{col}{a character string giving the color to be used for the
  52     text or the plotting symbols; this is eventually recycled.}
  53   \item{bg}{a character string giving the color to be used for the
  54     background of the text frames or of the plotting symbols if it
  55     applies; this is eventually recycled.}
  56   \item{\dots}{further arguments passed to the \code{text} or
  57     \code{points} functions (e.g. \code{cex} to alter the size of the
  58     text or the symbols, or \code{font} for the text; see the examples
  59     below).}
  60 }
  61 \details{
  62   These three functions have the same optional arguments and the same
  63   functioning.
  64
  65   If the arguments \code{text} is missing and \code{pch} and
  66   \code{thermo} are left as \code{NULL}, then the numbers of the nodes
  67   (or of the tips) are printed.
  68
  69   If \code{node}, \code{tip}, or \code{edge} is missing, then the text
  70   or the symbols are printed on all nodes, tips, or edges.
  71
  72   The option \code{cex} can be used to change the size of all types of
  73   labels.
  74
  75   A simple call of these functions with no arguments (e.g.,
  76   \code{nodelabels()}) prints the numbers of all nodes (or tips).
  77
  78   In the case of \code{tiplabels}, it would be useful to play with the
  79   options \code{x.lim} and \code{label.offset} (and possibly
  80   \code{show.tip.label}) of \code{plot.phylo} in most cases (see the
  81   examples).
  82 }
  83 \author{Emmanuel Paradis, Ben Bolker \email{bolker@zoo.ufl.edu}, and Jim
  84   Lemon}
  85 \seealso{
  86   \code{\link{plot.phylo}}, \code{\link{edges}},
  87   \code{\link{mixedFontLabel}}
  88 }
  89 \examples{
  90 tr <- read.tree(text = "((Homo,Pan),Gorilla);")
  91 plot(tr)
  92 nodelabels("7.3 Ma", 4, frame = "r", bg = "yellow", adj = 0)
  93 nodelabels("5.4 Ma", 5, frame = "c", bg = "tomato", font = 3)
  94
  95 data(bird.orders)
  96 plot(bird.orders, use.edge.length = FALSE, font = 1)
  97 bs <- round(runif(22, 90, 100), 0) # some imaginary bootstrap values
  98 bs2 <- round(runif(22, 90, 100), 0)
  99 bs3 <- round(runif(22, 90, 100), 0)
 100 nodelabels(bs, adj = 1.2)
 101 nodelabels(bs2, adj = -0.2, bg = "yellow")
 102
 103 ### something more classical
 104 plot(bird.orders, use.edge.length = FALSE, font = 1)
 105 nodelabels(bs, adj = -0.2, frame = "n", cex = 0.8)
 106 nodelabels(bs2, adj = c(1.2, 1), frame = "n", cex = 0.8)
 107 nodelabels(bs3, adj = c(1.2, -0.2), frame = "n", cex = 0.8)
 108
 109 ### the same but we play with the font
 110 plot(bird.orders, use.edge.length = FALSE, font = 1)
 111 nodelabels(bs, adj = -0.2, frame = "n", cex = 0.8, font = 2)
 112 nodelabels(bs2, adj = c(1.2, 1), frame = "n", cex = 0.8, font = 3)
 113 nodelabels(bs3, adj = c(1.2, -0.2), frame = "n", cex = 0.8)
 114
 115 plot(bird.orders, "c", use.edge.length = FALSE, font = 1)
 116 nodelabels(thermo = runif(22), cex = .8)
 117
 118 plot(bird.orders, "u", FALSE, font = 1, lab4ut = "a")
 119 nodelabels(cex = .75, bg = "yellow")
 120
 121 ### representing two characters at the tips (you could have as many
 122 ### as you want)
 123 plot(bird.orders, "c", FALSE, font = 1, label.offset = 3,
 124      x.lim = 31, no.margin = TRUE)
 125 tiplabels(pch = 21, bg = gray(1:23/23), cex = 2, adj = 1.4)
 126 tiplabels(pch = 19, col = c("yellow", "red", "blue"), adj = 2.5, cex = 2)
 127 ### This can be used to highlight tip labels:
 128 plot(bird.orders, font = 1)
 129 i <- c(1, 7, 18)
 130 tiplabels(bird.orders$tip.label[i], i, adj = 0)
 131 ### Some random data to compare piecharts and thermometres:
 132 tr <- rtree(15)
 133 x <- runif(14, 0, 0.33)
 134 y <- runif(14, 0, 0.33)
 135 z <- runif(14, 0, 0.33)
 136 x <- cbind(x, y, z, 1 - x - y - z)
 137 layout(matrix(1:2, 1, 2))
 138 plot(tr, "c", FALSE, no.margin = TRUE)
 139 nodelabels(pie = x, cex = 1.3)
 140 text(4.5, 15, "Are you \"pie\"...", font = 4, cex = 1.5)
 141 plot(tr, "c", FALSE, no.margin = TRUE)
 142 nodelabels(thermo = x, col = rainbow(4), cex = 1.3)
 143 text(4.5, 15, "... or \"thermo\"?", font = 4, cex = 1.5)
 144 layout(matrix(1))
 145 plot(tr, main = "Showing Edge Lengths")
 146 edgelabels(round(tr$edge.length, 3), srt = 90)
 147 plot(tr, "p", FALSE)
 148 edgelabels("above", adj = c(0.5, -0.25), bg = "yellow")
 149 edgelabels("below", adj = c(0.5, 1.25), bg = "lightblue")
 150 }
 151 \keyword{aplot}