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