5 \title{Labelling the Nodes, Tips, and Edges of a Tree}
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
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", ...)
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
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
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
62 These three functions have the same optional arguments and the same
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.
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.
72 The option \code{cex} can be used to change the size of all types of
75 A simple call of these functions with no arguments (e.g.,
76 \code{nodelabels()}) prints the numbers of all nodes (or tips).
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
83 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}, Ben Bolker
84 \email{bolker@zoo.ufl.edu}, and Jim Lemon}
86 \code{\link{plot.phylo}}
89 tr <- read.tree(text = "((Homo,Pan),Gorilla);")
91 nodelabels("7.3 Ma", 4, frame = "r", bg = "yellow", adj = 0)
92 nodelabels("5.4 Ma", 5, frame = "c", bg = "tomato", font = 3)
95 plot(bird.orders, use.edge.length = FALSE, font = 1)
96 bs <- round(runif(22, 90, 100), 0) # some imaginary bootstrap values
97 bs2 <- round(runif(22, 90, 100), 0)
98 bs3 <- round(runif(22, 90, 100), 0)
99 nodelabels(bs, adj = 1.2)
100 nodelabels(bs2, adj = -0.2, bg = "yellow")
102 ### something more classical
103 plot(bird.orders, use.edge.length = FALSE, font = 1)
104 nodelabels(bs, adj = -0.2, frame = "n", cex = 0.8)
105 nodelabels(bs2, adj = c(1.2, 1), frame = "n", cex = 0.8)
106 nodelabels(bs3, adj = c(1.2, -0.2), frame = "n", cex = 0.8)
108 ### the same but we play with the font
109 plot(bird.orders, use.edge.length = FALSE, font = 1)
110 nodelabels(bs, adj = -0.2, frame = "n", cex = 0.8, font = 2)
111 nodelabels(bs2, adj = c(1.2, 1), frame = "n", cex = 0.8, font = 3)
112 nodelabels(bs3, adj = c(1.2, -0.2), frame = "n", cex = 0.8)
114 plot(bird.orders, "c", use.edge.length = FALSE, font = 1)
115 nodelabels(thermo = runif(22), cex = .8)
117 plot(bird.orders, "u", FALSE, font = 1, lab4ut = "a")
118 nodelabels(cex = .75, bg = "yellow")
120 ### representing two characters at the tips (you could have as many
122 plot(bird.orders, "c", FALSE, font = 1, label.offset = 3,
123 x.lim = 31, no.margin = TRUE)
124 tiplabels(pch = 21, bg = gray(1:23/23), cex = 2, adj = 1.4)
125 tiplabels(pch = 19, col = c("yellow", "red", "blue"), adj = 2.5, cex = 2)
126 ### This can be used to highlight tip labels:
127 plot(bird.orders, font = 1)
129 tiplabels(bird.orders$tip.label[i], i, adj = 0)
130 ### Some random data to compare piecharts and thermometres:
132 x <- runif(14, 0, 0.33)
133 y <- runif(14, 0, 0.33)
134 z <- runif(14, 0, 0.33)
135 x <- cbind(x, y, z, 1 - x - y - z)
136 layout(matrix(1:2, 1, 2))
137 plot(tr, "c", FALSE, no.margin = TRUE)
138 nodelabels(pie = x, cex = 1.3)
139 text(4.5, 15, "Are you \"pie\"...", font = 4, cex = 1.5)
140 plot(tr, "c", FALSE, no.margin = TRUE)
141 nodelabels(thermo = x, col = rainbow(4), cex = 1.3)
142 text(4.5, 15, "... or \"thermo\"?", font = 4, cex = 1.5)
144 plot(tr, main = "Showing Edge Lengths")
145 edgelabels(round(tr$edge.length, 3), srt = 90)
147 edgelabels("above", adj = c(0.5, -0.25), bg = "yellow")
148 edgelabels("below", adj = c(0.5, 1.25), bg = "lightblue")