3 \alias{plot.multiPhylo}
4 \title{Plot Phylogenies}
6 \method{plot}{phylo}(x, type = "phylogram", use.edge.length = TRUE,
7 node.pos = NULL, show.tip.label = TRUE, show.node.label = FALSE,
8 edge.color = "black", edge.width = 1, edge.lty = 1, font = 3,
9 cex = par("cex"), adj = NULL, srt = 0, no.margin = FALSE,
10 root.edge = FALSE, label.offset = 0, underscore = FALSE,
11 x.lim = NULL, y.lim = NULL, direction = "rightwards",
12 lab4ut = "horizontal", tip.color = "black", plot = TRUE,
14 \method{plot}{multiPhylo}(x, layout = 1, ...)
17 \item{x}{an object of class \code{"phylo"} or of class
19 \item{type}{a character string specifying the type of phylogeny to be
20 drawn; it must be one of "phylogram" (the default), "cladogram",
21 "fan", "unrooted", "radial" or any unambiguous abbreviation of
23 \item{use.edge.length}{a logical indicating whether to use the edge
24 lengths of the phylogeny to draw the branches (the default) or not
25 (if \code{FALSE}). This option has no effect if the object of class
26 \code{"phylo"} has no `edge.length' element.}
27 \item{node.pos}{a numeric taking the value 1 or 2 which specifies the
28 vertical position of the nodes with respect to their descendants. If
29 \code{NULL} (the default), then the value is determined in relation
30 to `type' and `use.edge.length' (see details).}
31 \item{show.tip.label}{a logical indicating whether to show the tip
32 labels on the phylogeny (defaults to \code{TRUE}, i.e. the labels
34 \item{show.node.label}{a logical indicating whether to show the node
35 labels on the phylogeny (defaults to \code{FALSE}, i.e. the labels
37 \item{edge.color}{a vector of mode character giving the colours used
38 to draw the branches of the plotted phylogeny. These are taken to be
39 in the same order than the component \code{edge} of \code{phy}. If
40 fewer colours are given than the length of \code{edge}, then the
41 colours are recycled.}
42 \item{edge.width}{a numeric vector giving the width of the branches of
43 the plotted phylogeny. These are taken to be in the same order than
44 the component \code{edge} of \code{phy}. If fewer widths are given
45 than the length of \code{edge}, then these are recycled.}
46 \item{edge.lty}{same than the previous argument but for line types;
47 1: plain, 2: dashed, 3: dotted, 4: dotdash, 5: longdash, 6: twodash.}
48 \item{font}{an integer specifying the type of font for the labels: 1
49 (plain text), 2 (bold), 3 (italic, the default), or 4 (bold
51 \item{cex}{a numeric value giving the factor scaling of the tip and
52 node labels (Character EXpansion). The default is to take the
53 current value from the graphical parameters.}
54 \item{adj}{a numeric specifying the justification of the text strings
55 of the labels: 0 (left-justification), 0.5 (centering), or 1
56 (right-justification). This option has no effect if \code{type =
57 "unrooted"}. If \code{NULL} (the default) the value is set with
58 respect of \code{direction} (see details).}
59 \item{srt}{a numeric giving how much the labels are rotated in degrees
60 (negative values are allowed resulting in clock-like rotation); the
61 value has an effect respectively to the value of
62 \code{direction} (see Examples). This option has no effect if
63 \code{type = "unrooted"}.}
64 \item{no.margin}{a logical. If \code{TRUE}, the margins are set to
65 zero and the plot uses all the space of the device (note that this
66 was the behaviour of \code{plot.phylo} up to version 0.2-1 of `ape'
67 with no way to modify it by the user, at least easily).}
68 \item{root.edge}{a logical indicating whether to draw the root edge
69 (defaults to FALSE); this has no effect if `use.edge.length = FALSE'
70 or if `type = "unrooted"'.}
71 \item{label.offset}{a numeric giving the space between the nodes and
72 the tips of the phylogeny and their corresponding labels. This
73 option has no effect if \code{type = "unrooted"}.}
74 \item{underscore}{a logical specifying whether the underscores in tip
75 labels should be written as spaces (the default) or left as are (if
77 \item{x.lim}{a numeric vector of length one or two giving the limit(s)
78 of the x-axis. If \code{NULL}, this is computed with respect to
79 various parameters such as the string lengths of the labels and the
80 branch lengths. If a single value is given, this is taken as the
82 \item{y.lim}{same than above for the y-axis.}
83 \item{direction}{a character string specifying the direction of the
84 tree. Four values are possible: "rightwards" (the default),
85 "leftwards", "upwards", and "downwards".}
86 \item{lab4ut}{(= labels for unrooted trees) a character string
87 specifying the display of tip labels for unrooted trees: either
88 \code{"horizontal"} where all labels are horizontal (the default),
89 or \code{"axial"} where the labels are displayed in the axis of the
90 corresponding terminal branches. This option has an effect only if
91 \code{type = "unrooted"}.}
92 \item{tip.color}{the colours used for the tip labels, eventually
93 recycled (see examples).}
94 \item{plot}{a logical controlling whether to draw the tree. If
95 \code{FALSE}, the graphical device is set as if the tree was
96 plotted, and the coordinates are saved as well.}
97 \item{rotate.tree}{for "fan", "unrooted", or "radial" trees: the
98 rotation of the whole tree in degrees (negative values are
100 \item{layout}{the number of trees to be plotted simultaneously.}
101 \item{\dots}{further arguments to be passed to \code{plot} or to
105 These functions plot phylogenetic trees on the current graphical
109 If \code{x} is a list of trees (i.e., an object of class
110 \code{"multiPhylo"}), then any further argument may be passed with
111 \code{...} and could be any one of those listed above for a single
114 The font format of the labels of the nodes and the tips is the same.
116 If \code{no.margin = TRUE}, the margins are set to zero and are not
117 restored after plotting the tree, so that the user can access the
118 coordinates system of the plot.
120 The option `node.pos' allows the user to alter the vertical position
121 (i.e. ordinates) of the nodes. If \code{node.pos = 1}, then the
122 ordinate of a node is the mean of the ordinates of its direct
123 descendants (nodes and/or tips). If \code{node.pos = 2}, then the
124 ordinate of a node is the mean of the ordinates of all the tips of
125 which it is the ancestor. If \code{node.pos = NULL} (the default),
126 then its value is determined with respect to other options: if
127 \code{type = "phylogram"} then `node.pos = 1'; if \code{type =
128 "cladogram"} and \code{use.edge.length = FALSE} then `node.pos = 2';
129 if \code{type = "cladogram"} and \code{use.edge.length = TRUE} then
130 `node.pos = 1'. Remember that in this last situation, the branch
131 lengths make sense when projected on the x-axis.
133 If \code{adj} is not specified, then the value is determined with
134 respect to \code{direction}: if \code{direction = "leftwards"} then
135 \code{adj = 1} (0 otherwise).
137 If the arguments \code{x.lim} and \code{y.lim} are not specified by the
138 user, they are determined roughly by the function. This may not always
139 give a nice result: the user may check these values with the
140 (invisibly) returned list (see ``Value:'').
142 If you resize manually the graphical device (windows or X11) you may
143 need to replot the tree.
146 The argument \code{asp} cannot be passed with \code{\dots}.
149 \code{plot.phylo} returns invisibly a list with the following
150 components which values are those used for the current plot:
153 \item{use.edge.length}{}
155 \item{show.tip.label}{}
156 \item{show.node.label}{}
162 \item{label.offset}{}
170 \author{Emmanuel Paradis}
172 \code{\link{read.tree}}, \code{\link{trex}}, \code{\link{kronoviz}},
173 \code{\link{add.scale.bar}}, \code{\link{axisPhylo}},
174 \code{\link{nodelabels}}, \code{\link{edges}},
175 \code{\link[graphics]{plot}} for the basic plotting function in R
178 ### An extract from Sibley and Ahlquist (1990)
179 cat("(((Strix_aluco:4.2,Asio_otus:4.2):3.1,",
180 "Athene_noctua:7.3):6.3,Tyto_alba:13.5);",
181 file = "ex.tre", sep = "\n")
182 tree.owls <- read.tree("ex.tre")
184 unlink("ex.tre") # delete the file "ex.tre"
186 ### Show the types of trees.
187 layout(matrix(1:6, 3, 2))
188 plot(tree.owls, main = "With branch lengths")
189 plot(tree.owls, type = "c")
190 plot(tree.owls, type = "u")
191 plot(tree.owls, use.edge.length = FALSE, main = "Without branch lengths")
192 plot(tree.owls, type = "c", use.edge.length = FALSE)
193 plot(tree.owls, type = "u", use.edge.length = FALSE)
197 ### using random colours and thickness
199 edge.color = sample(colors(), length(bird.orders$edge)/2),
200 edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
201 title("Random colours and branch thickness")
202 ### rainbow colouring...
203 X <- c("red", "orange", "yellow", "green", "blue", "purple")
205 edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
206 edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
207 title("Rainbow colouring")
208 plot(bird.orders, type = "c", use.edge.length = FALSE,
209 edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
210 edge.width = rep(5, length(bird.orders$edge)/2))
211 segments(rep(0, 6), 6.5:1.5, rep(2, 6), 6.5:1.5, lwd = 5, col = X)
212 text(rep(2.5, 6), 6.5:1.5, paste(X, "..."), adj = 0)
213 title("Character mapping...")
214 plot(bird.orders, "u", font = 1, cex = 0.75)
216 plot(bird.families, "u", lab4ut = "axial", font = 1, cex = 0.5)
217 plot(bird.families, "r", font = 1, cex = 0.5)
218 ### cladogram with oblique tip labels
219 plot(bird.orders, "c", FALSE, direction = "u", srt = -40, x.lim = 25.5)
220 ### facing trees with different informations...
222 tr$tip.label <- rep("", 23)
223 layout(matrix(1:2, 1, 2), c(5, 4))
224 plot(bird.orders, "c", FALSE, adj = 0.5, no.margin = TRUE, label.offset = 0.8,
225 edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
226 edge.width = rep(5, length(bird.orders$edge)/2))
227 text(7.5, 23, "Facing trees with\ndifferent informations", font = 2)
228 plot(tr, "p", direction = "l", no.margin = TRUE,
229 edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
230 ### Recycling of arguments gives a lot of possibilities
232 plot(bird.orders, tip.col = c(rep("red", 5), rep("blue", 18)),
233 font = c(rep(3, 5), rep(2, 17), 1))
234 plot(bird.orders, tip.col = c("blue", "green"),
235 cex = 23:1/23 + .3, font = 1:3)
236 co <- c(rep("blue", 9), rep("green", 35))
237 plot(bird.orders, "f", edge.col = co)
238 plot(bird.orders, edge.col = co)