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", plot = TRUE,
  13     rotate.tree = 0, open.angle = 0, ...)
  14 \method{plot}{multiPhylo}(x, layout = 1, ...)
  15 }
  16 \arguments{
  17   \item{x}{an object of class \code{"phylo"} or of class
  18     \code{"multiPhylo"}.}
  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
  22     these.}
  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
  33     are shown).}
  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
  36     are not shown).}
  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
  50     italic).}
  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
  76     \code{TRUE}).}
  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
  81     upper limit.}
  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
  99     accepted).}
 100   \item{open.angle}{if \code{type = "f"}, the angle in degrees left
 101     blank. Use a non-zero value if you want to call
 102     \code{\link{axisPhylo}} after the tree is plotted.}
 103   \item{layout}{the number of trees to be plotted simultaneously.}
 104   \item{\dots}{further arguments to be passed to \code{plot} or to
 105     \code{plot.phylo}.}
 106 }
 107 \description{
 108   These functions plot phylogenetic trees on the current graphical
 109   device.
 110 }
 111 \details{
 112   If \code{x} is a list of trees (i.e., an object of class
 113   \code{"multiPhylo"}), then any further argument may be passed with
 114   \code{...} and could be any one of those listed above for a single
 115   tree.
 116
 117   The font format of the labels of the nodes and the tips is the same.
 118
 119   If \code{no.margin = TRUE}, the margins are set to zero and are not
 120   restored after plotting the tree, so that the user can access the
 121   coordinates system of the plot.
 122
 123   The option `node.pos' allows the user to alter the vertical position
 124   (i.e. ordinates) of the nodes. If \code{node.pos = 1}, then the
 125   ordinate of a node is the mean of the ordinates of its direct
 126   descendants (nodes and/or tips). If \code{node.pos = 2}, then the
 127   ordinate of a node is the mean of the ordinates of all the tips of
 128   which it is the ancestor. If \code{node.pos = NULL} (the default),
 129   then its value is determined with respect to other options: if
 130   \code{type = "phylogram"} then `node.pos = 1'; if \code{type =
 131     "cladogram"} and \code{use.edge.length = FALSE} then `node.pos = 2';
 132   if \code{type = "cladogram"} and \code{use.edge.length = TRUE} then
 133   `node.pos = 1'. Remember that in this last situation, the branch
 134   lengths make sense when projected on the x-axis.
 135
 136   If \code{adj} is not specified, then the value is determined with
 137   respect to \code{direction}: if \code{direction = "leftwards"} then
 138   \code{adj = 1} (0 otherwise).
 139
 140   If the arguments \code{x.lim} and \code{y.lim} are not specified by the
 141   user, they are determined roughly by the function. This may not always
 142   give a nice result: the user may check these values with the
 143   (invisibly) returned list (see ``Value:'').
 144
 145   If you resize manually the graphical device (windows or X11) you may
 146   need to replot the tree.
 147 }
 148 \note{
 149   The argument \code{asp} cannot be passed with \code{\dots}.
 150 }
 151 \value{
 152   \code{plot.phylo} returns invisibly a list with the following
 153   components which values are those used for the current plot:
 154
 155   \item{type}{}
 156   \item{use.edge.length}{}
 157   \item{node.pos}{}
 158   \item{show.tip.label}{}
 159   \item{show.node.label}{}
 160   \item{font}{}
 161   \item{cex}{}
 162   \item{adj}{}
 163   \item{srt}{}
 164   \item{no.margin}{}
 165   \item{label.offset}{}
 166   \item{x.lim}{}
 167   \item{y.lim}{}
 168   \item{direction}{}
 169   \item{tip.color}{}
 170   \item{Ntip}{}
 171   \item{Nnode}{}
 172 }
 173 \author{Emmanuel Paradis}
 174 \seealso{
 175   \code{\link{read.tree}}, \code{\link{trex}}, \code{\link{kronoviz}},
 176   \code{\link{add.scale.bar}}, \code{\link{axisPhylo}},
 177   \code{\link{nodelabels}}, \code{\link{edges}},
 178   \code{\link[graphics]{plot}} for the basic plotting function in R
 179 }
 180 \examples{
 181 ### An extract from Sibley and Ahlquist (1990)
 182 cat("(((Strix_aluco:4.2,Asio_otus:4.2):3.1,",
 183    "Athene_noctua:7.3):6.3,Tyto_alba:13.5);",
 184    file = "ex.tre", sep = "\n")
 185 tree.owls <- read.tree("ex.tre")
 186 plot(tree.owls)
 187 unlink("ex.tre") # delete the file "ex.tre"
 188
 189 ### Show the types of trees.
 190 layout(matrix(1:6, 3, 2))
 191 plot(tree.owls, main = "With branch lengths")
 192 plot(tree.owls, type = "c")
 193 plot(tree.owls, type = "u")
 194 plot(tree.owls, use.edge.length = FALSE, main = "Without branch lengths")
 195 plot(tree.owls, type = "c", use.edge.length = FALSE)
 196 plot(tree.owls, type = "u", use.edge.length = FALSE)
 197 layout(matrix(1))
 198
 199 data(bird.orders)
 200 ### using random colours and thickness
 201 plot(bird.orders,
 202      edge.color = sample(colors(), length(bird.orders$edge)/2),
 203      edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
 204 title("Random colours and branch thickness")
 205 ### rainbow colouring...
 206 X <- c("red", "orange", "yellow", "green", "blue", "purple")
 207 plot(bird.orders,
 208      edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
 209      edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
 210 title("Rainbow colouring")
 211 plot(bird.orders, type = "c", use.edge.length = FALSE,
 212      edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
 213      edge.width = rep(5, length(bird.orders$edge)/2))
 214 segments(rep(0, 6), 6.5:1.5, rep(2, 6), 6.5:1.5, lwd = 5, col = X)
 215 text(rep(2.5, 6), 6.5:1.5, paste(X, "..."), adj = 0)
 216 title("Character mapping...")
 217 plot(bird.orders, "u", font = 1, cex = 0.75)
 218 data(bird.families)
 219 plot(bird.families, "u", lab4ut = "axial", font = 1, cex = 0.5)
 220 plot(bird.families, "r", font = 1, cex = 0.5)
 221 ### cladogram with oblique tip labels
 222 plot(bird.orders, "c", FALSE, direction = "u", srt = -40, x.lim = 25.5)
 223 ### facing trees with different informations...
 224 tr <- bird.orders
 225 tr$tip.label <- rep("", 23)
 226 layout(matrix(1:2, 1, 2), c(5, 4))
 227 plot(bird.orders, "c", FALSE, adj = 0.5, no.margin = TRUE, label.offset = 0.8,
 228      edge.color = sample(X, length(bird.orders$edge)/2, replace = TRUE),
 229      edge.width = rep(5, length(bird.orders$edge)/2))
 230 text(7.5, 23, "Facing trees with\ndifferent informations", font = 2)
 231 plot(tr, "p", direction = "l", no.margin = TRUE,
 232      edge.width = sample(1:10, length(bird.orders$edge)/2, replace = TRUE))
 233 ### Recycling of arguments gives a lot of possibilities
 234 ### for tip labels:
 235 plot(bird.orders, tip.col = c(rep("red", 5), rep("blue", 18)),
 236      font = c(rep(3, 5), rep(2, 17), 1))
 237 plot(bird.orders, tip.col = c("blue", "green"),
 238      cex = 23:1/23 + .3, font = 1:3)
 239 co <- c(rep("blue", 9), rep("green", 35))
 240 plot(bird.orders, "f", edge.col = co)
 241 plot(bird.orders, edge.col = co)
 242 layout(1)
 243 }
 244 \keyword{hplot}