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