man/ltt.plot.Rd

   1 \name{ltt.plot}
   2 \alias{ltt.plot}
   3 \alias{ltt.lines}
   4 \alias{mltt.plot}
   5 \alias{ltt.coplot}
   6 \alias{ltt.plot.coords}
   7 \title{Lineages Through Time Plot}
   8 \description{
   9   These functions provide tools for plotting the numbers of lineages
  10   through time from phylogenetic trees.
  11 }
  12 \usage{
  13 ltt.plot(phy, xlab = "Time", ylab = "N",
  14          backward = TRUE, tol = 1e-6, ...)
  15 ltt.lines(phy, backward = TRUE, tol = 1e-6, ...)
  16 mltt.plot(phy, ..., dcol = TRUE, dlty = FALSE, legend = TRUE,
  17           xlab = "Time", ylab = "N", log = "", backward = TRUE,
  18           tol = 1e-6)
  19 ltt.coplot(phy, backward = TRUE, ...)
  20 ltt.plot.coords(phy, backward = TRUE, tol = 1e-6)
  21 }
  22 \arguments{
  23   \item{phy}{an object of class \code{"phylo"}; this could be an object
  24     of class \code{"multiPhylo"} in the case of \code{mltt.plot}.}
  25   \item{xlab}{a character string (or a variable of mode character)
  26     giving the label for the \eqn{x}-axis (default is "Time").}
  27   \item{ylab}{idem for the \eqn{y}-axis (default is "N").}
  28   \item{backward}{a logical value: should the time axis be traced from
  29     the present (the default), or from the root of the tree?}
  30   \item{tol}{a numeric value (see details).}
  31   \item{\dots}{in the cases of \code{ltt.plot()}, \code{ltt.lines()},
  32     or \code{ltt.coplot()} these are further (graphical) arguments to be
  33     passed to \code{plot()}, \code{lines()}, or \code{plot.phylo()},
  34     respectively (see details on how to transform the axes); in
  35     the case \code{mltt.plot()} these are additional trees to be plotted
  36     (see details).}
  37   \item{dcol}{a logical specifying whether the different curves should
  38     be differentiated with colors (default is \code{TRUE}).}
  39   \item{dlty}{a logical specifying whether the different curves should
  40     be differentiated with patterns of dots and dashes (default is
  41     \code{FALSE}).}
  42   \item{legend}{a logical specifying whether a legend should be
  43     plotted.}
  44   \item{log}{a character string specifying which axis(es) to be
  45     log-transformed; must be one of the followings: \code{""},
  46     \code{"x"}, \code{"y"}, or \code{"xy"}.}
  47 }
  48 \details{
  49   \code{ltt.plot} does a simple lineages through time (LTT)
  50   plot. Additional arguments (\code{\dots}) may be used to change, for
  51   instance, the limits on the axes (with \code{xlim} and/or
  52   \code{ylim}) or other graphical settings (\code{col} for the color,
  53   \code{lwd} for the line thickness, \code{lty} for the line type may be
  54   useful; see \code{\link[graphics]{par}} for an exhaustive listing of
  55   graphical parameters). The \eqn{y}-axis can be log-transformed by
  56   adding the following option: \code{log = "y"}.
  57
  58   The option \code{tol} is used as follows: first the most distant tip
  59   from the root is found, then all tips whose distance to the root is
  60   not different from the previous one than \code{tol} are considered to
  61   be contemporaneous with it.
  62
  63   If the tree is not ultrametric, the plot is done assuming the tips,
  64   except the most distant from the root, represent extinction events. If
  65   a root edge is present, it is taken into account.
  66
  67   \code{ltt.lines} adds a LTT curve to an existing plot. Additional
  68   arguments (\code{\dots}) may be used to change the settings of the added
  69   line.
  70
  71   \code{mltt.plot} does a multiple LTT plot taking as arguments one or
  72   several trees. These trees may be given as objects of class
  73   \code{"phylo"} (single trees) and/or \code{"multiPhylo"} (multiple
  74   trees). Any number of objects may be given. This function is mainly
  75   for exploratory analyses with the advantages that the axes are set
  76   properly to view all lines, and the legend is plotted by default. The
  77   plot will certainly make sense if all trees have their
  78   most-distant-from-the-root tips contemporaneous (i.e., trees with only
  79   extinct lineages will not be represented properly). For more flexible
  80   settings of line drawings, it may be better to combine
  81   \code{ltt.plot()} with successive calls of \code{ltt.lines()} (see
  82   examples).
  83
  84   \code{ltt.coplot} is meant to show how to set a tree and a LTT plots
  85   on the same scales. All extra arguments modify only the appearance of
  86   the tree. The code can be easily edited and tailored.
  87 }
  88 \value{
  89   \code{ltt.plot.coords} returns a two-column matrix with the time
  90   points and the number of lineages, respectively. The \eqn{i}th value
  91   of the second column is the number of lineages for the interval
  92   defined by the \eqn{(i - 1)}th and the \eqn{i}th values of the first
  93   column. These are then plotted with the option \code{type = "S"} by
  94   the other functions.
  95 }
  96 \references{
  97   Harvey, P. H., May, R. M. and Nee, S. (1994) Phylogenies without
  98   fossils. \emph{Evolution}, \bold{48}, 523--529.
  99
 100   Nee, S., Holmes, E. C., Rambaut, A. and Harvey, P. H. (1995) Inferring
 101   population history from molecular phylogenies. \emph{Philosophical
 102     Transactions of the Royal Society of London. Series B. Biological
 103     Sciences}, \bold{349}, 25--31.
 104 }
 105 \author{Emmanuel Paradis}
 106 \seealso{
 107   \code{\link{kronoviz}}, \code{\link{skyline}},
 108   \code{\link{branching.times}}, \code{\link{birthdeath}},
 109   \code{\link{bd.ext}}, \code{\link{yule.cov}}, \code{\link{bd.time}};
 110   \code{\link[graphics]{plot}} for the basic plotting function in R
 111 }
 112 \examples{
 113 data(bird.families)
 114 opar <- par(mfrow = c(2, 1))
 115 ltt.plot(bird.families)
 116 title("Lineages Through Time Plot of the Bird Families")
 117 ltt.plot(bird.families, log = "y")
 118 title(main = "Lineages Through Time Plot of the Bird Families",
 119       sub = "(with logarithmic transformation of the y-axis)")
 120 par(opar)
 121
 122 ### to plot the tree and the LTT plot together
 123 data(bird.orders)
 124 layout(matrix(1:4, 2, 2))
 125 plot(bird.families, show.tip.label = FALSE)
 126 ltt.plot(bird.families, main = "Bird families")
 127 plot(bird.orders, show.tip.label = FALSE)
 128 ltt.plot(bird.orders, main = "Bird orders")
 129 layout(1)
 130
 131 ### better with ltt.coplot():
 132 ltt.coplot(bird.families, show.tip.label = FALSE, x.lim = 27.5)
 133 data(chiroptera)
 134 chiroptera <- compute.brlen(chiroptera)
 135 ltt.coplot(chiroptera, show.tip.label = FALSE, type = "c")
 136
 137 ### with extinct lineages and a root edge:
 138 omar <- par("mar")
 139 set.seed(31)
 140 tr <- rlineage(0.2, 0.15)
 141 tr$root.edge <- 5
 142 ltt.coplot(tr, show.tip.label = FALSE, x.lim = 55)
 143 ## compare with:
 144 ## ltt.coplot(drop.fossil(tr), show.tip.label = FALSE)
 145 layout(1)
 146 par(mar = omar)
 147
 148 mltt.plot(bird.families, bird.orders)
 149 ### Generates 10 random trees with 23 tips:
 150 TR <- replicate(10, rcoal(23), FALSE)
 151 ### Give names to each tree:
 152 names(TR) <- paste("random tree", 1:10)
 153 ### And specify the class of the list so that mltt.plot()
 154 ### does not trash it!
 155 class(TR) <- "multiPhylo"
 156 mltt.plot(TR, bird.orders)
 157 ### And now for something (not so) completely different:
 158 ltt.plot(bird.orders, lwd = 2)
 159 for (i in 1:10) ltt.lines(TR[[i]], lty = 2)
 160 legend(-20, 10, lwd = c(2, 1), lty = c(1, 2), bty = "n",
 161        legend = c("Bird orders", "Random (coalescent) trees"))
 162 }
 163 \keyword{hplot}
 164 \keyword{aplot}