man/boot.phylo.Rd

   1 \name{boot.phylo}
   2 \alias{boot.phylo}
   3 \alias{prop.part}
   4 \alias{prop.clades}
   5 \alias{print.prop.part}
   6 \alias{summary.prop.part}
   7 \alias{plot.prop.part}
   8 \title{Tree Bipartition and Bootstrapping Phylogenies}
   9 \usage{
  10 boot.phylo(phy, x, FUN, B = 100, block = 1, trees = FALSE)
  11 prop.part(..., check.labels = TRUE)
  12 prop.clades(phy, ..., part = NULL)
  13 \method{print}{prop.part}(x, ...)
  14 \method{summary}{prop.part}(object, ...)
  15 \method{plot}{prop.part}(x, barcol = "blue", leftmar = 4, ...)
  16 }
  17 \arguments{
  18   \item{phy}{an object of class \code{"phylo"}.}
  19   \item{x}{in the case of \code{boot.phylo}: a taxa (rows) by characters
  20     (columns) matrix; this may be presented as a list; in the case of
  21     \code{print} and \code{plot}: an object of class \code{"prop.part"}.}
  22   \item{FUN}{the function used to estimate \code{phy} (see details).}
  23   \item{B}{the number of bootstrap replicates.}
  24   \item{block}{the number of columns in \code{x} that will be resampled
  25     together (see details).}
  26   \item{trees}{a logical specifying whether to return the bootstraped
  27     trees (\code{FALSE} by default).}
  28   \item{\dots}{either (i) a single object of class \code{"phylo"}, (ii) a
  29     series of such objects separated by commas, or (iii) a list
  30     containing such objects. In the case of \code{plot} further
  31     arguments for the plot (see details).}
  32   \item{check.labels}{a logical specifying whether to check the labels
  33     of each tree. If \code{FALSE}, it is assumed that all trees have the
  34     same tip labels, and that they are in the same order (see details).}
  35   \item{part}{a list of partitions as returned by \code{prop.part}; if
  36     this is used then \code{\dots} is ignored.}
  37   \item{object}{an object of class \code{"prop.part"}.}
  38   \item{barcol}{the colour used for the bars displaying the number of
  39     partitions in the upper panel.}
  40   \item{leftmar}{the size of the margin on the left to display the tip
  41     labels.}
  42 }
  43 \description{
  44   These functions analyse bipartitions found in a series of trees.
  45
  46   \code{prop.part} counts the number of bipartitions found in a series
  47   of trees given as \code{\dots}.
  48
  49   \code{prop.clades} counts the number of times the bipartitions present
  50   in \code{phy} are present in a series of trees given as \code{\dots} or
  51   in the list previously computed and given with \code{part}.
  52
  53   \code{boot.phylo} performs a bootstrap analysis.
  54 }
  55 \details{
  56   The argument \code{FUN} in \code{boot.phylo} must be the function used
  57   to estimate the tree from the original data matrix. Thus, if the tree
  58   was estimated with neighbor-joining (see \code{nj}), one maybe wants
  59   something like \code{FUN = function(xx) nj(dist.dna(xx))}.
  60
  61   \code{block} in \code{boot.phylo} specifies the number of columns to
  62   be resampled altogether. For instance, if one wants to resample at the
  63   codon-level, then \code{block = 3} must be used.
  64
  65   Using \code{check.labels = FALSE} in \code{prop.part} decreases
  66   computing times. This requires that (i) all trees have the same tip
  67   labels, \emph{and} (ii) these labels are ordered similarly in all
  68   trees (in other words, the element \code{tip.label} are identical in
  69   all trees).
  70
  71   The plot function represents a contingency table of the different
  72   partitions (on the \emph{x}-axis) in the lower panel, and their observed
  73   numbers in the upper panel. Any further arguments (\dots) are used to
  74   change the aspects of the points in the lower panel: these may be
  75   \code{pch}, \code{col}, \code{bg}, \code{cex}, etc. This function
  76   works only if there is an attribute \code{labels} in the object.
  77
  78   The print method displays the partitions and their numbers. The
  79   summary method extracts the numbers only.
  80 }
  81 \note{
  82   \code{prop.clades} calls internally \code{prop.part} with the option
  83   \code{check.labels = TRUE}, which may be very slow. If the trees
  84   passed as \code{\dots} fulfills conditions (i) and (ii) above, then it
  85   might be faster to first call, e.g., \code{pp <- prop.part(...)}, then
  86   use the option \code{part}: \code{prop.clades(phy, part = pp)}.
  87 }
  88 \value{
  89   \code{prop.part} returns an object of class \code{"prop.part"} which
  90   is a list with an attribute \code{"number"}. The elements of this list
  91   are the observed clades, and the attribute their respective
  92   numbers. If the default \code{check.labels = FALSE} is used, an
  93   attribute \code{"labels"} is added, and the vectors of the returned
  94   object contains the indices of these labels instead of the labels
  95   themselves.
  96
  97   \code{prop.clades} and \code{boot.phylo} return a numeric vector
  98   which \emph{i}th element is the number associated to the \emph{i}th
  99   node of \code{phy}. If \code{trees = TRUE}, \code{boot.phylo} returns
 100   a list whose first element (named \code{"BP"}) is like before, and the
 101   second element (\code{"trees"}) is a list with the bootstraped
 102   trees.
 103
 104   \code{summary} returns a numeric vector.
 105 }
 106 \references{
 107   Efron, B., Halloran, E. and Holmes, S. (1996) Bootstrap confidence
 108   levels for phylogenetic trees. \emph{Proceedings of the National
 109     Academy of Sciences USA}, \bold{93}, 13429--13434.
 110
 111   Felsenstein, J. (1985) Confidence limits on phylogenies: an approach
 112   using the bootstrap. \emph{Evolution}, \bold{39}, 783--791.
 113 }
 114 \author{Emmanuel Paradis}
 115 \seealso{
 116   \code{\link{dist.topo}}, \code{\link{consensus}}, \code{\link{nodelabels}}
 117 }
 118 \examples{
 119 data(woodmouse)
 120 tr <- nj(dist.dna(woodmouse))
 121 ### Are bootstrap values stable?
 122 for (i in 1:5)
 123   print(boot.phylo(tr, woodmouse, function(xx) nj(dist.dna(xx))))
 124 ### How many partitions in 100 random trees of 10 labels?...
 125 TR <- replicate(100, rtree(10), FALSE)
 126 pp10 <- prop.part(TR)
 127 length(pp10)
 128 ### ... and in 100 random trees of 20 labels?
 129 TR <- replicate(100, rtree(20), FALSE)
 130 pp20 <- prop.part(TR)
 131 length(pp20)
 132 plot(pp10, pch = "x", col = 2)
 133 plot(pp20, pch = "x", col = 2)
 134 }
 135 \keyword{manip}
 136 \keyword{htest}