man/plot.phylo.Rd

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