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