man/root.Rd

   1 \name{root}
   2 \alias{root}
   3 \alias{unroot}
   4 \alias{is.rooted}
   5 \title{Roots Phylogenetic Trees}
   6 \usage{
   7 root(phy, outgroup, node = NULL, resolve.root = FALSE, interactive = FALSE)
   8 unroot(phy)
   9 is.rooted(phy)
  10 }
  11 \arguments{
  12   \item{phy}{an object of class \code{"phylo"}.}
  13   \item{outgroup}{a vector of mode numeric or character specifying the
  14     new outgroup.}
  15   \item{node}{alternatively, a node number where to root the tree (this
  16     should give the MRCA of the ingroup).}
  17   \item{resolve.root}{a logical specifying whether to resolve the new
  18     root as a bifurcating node.}
  19   \item{interactive}{if \code{TRUE} the user is asked to select the node
  20     by clicking on the tree which must be plotted.}
  21 }
  22 \description{
  23   \code{root} reroots a phylogenetic tree with respect to the specified
  24   outgroup or at the node specified in \code{node}.
  25
  26   \code{unroot} unroots a phylogenetic tree, or returns it unchanged if
  27   it is already unrooted.
  28
  29   \code{is.rooted} tests whether a tree is rooted.
  30 }
  31 \details{
  32   The argument \code{outgroup} can be either character or numeric. In
  33   the first case, it gives the labels of the tips of the new outgroup;
  34   in the second case the numbers of these labels in the vector
  35   \code{phy$tip.label} are given.
  36
  37   If \code{outgroup} is of length one (i.e., a single value), then the
  38   tree is rerooted using the node below this tip as the new root.
  39
  40   If \code{outgroup} is of length two or more, the most recent common
  41   ancestor (MRCA) \emph{of the ingroup} is used as the new root. Note
  42   that the tree is unrooted before being rerooted, so that if
  43   \code{outgroup} is already the outgroup, then the returned tree is not
  44   the same than the original one (see examples). If \code{outgroup} is
  45   not monophyletic, the operation fails and an error message is issued.
  46
  47   If \code{resolve.root = TRUE}, \code{root} adds a zero-length branch
  48   below the MRCA of the ingroup.
  49
  50   A tree is considered rooted if either only two branches connect to the
  51   root, or if there is a \code{root.edge} element. In all other cases,
  52   \code{is.rooted} returns \code{FALSE}.
  53 }
  54 \value{
  55   an object of class \code{"phylo"} for \code{root} and \code{unroot}; a
  56   single logical value for \code{is.rooted}.
  57 }
  58 \author{Emmanuel Paradis}
  59 \seealso{
  60   \code{\link{bind.tree}}, \code{\link{drop.tip}},
  61   \code{\link{nodelabels}}, \code{\link{identify.phylo}}
  62 }
  63 \examples{
  64 data(bird.orders)
  65 plot(root(bird.orders, 1))
  66 plot(root(bird.orders, 1:5))
  67
  68 tr <- root(bird.orders, 1)
  69 is.rooted(bird.orders) # yes!
  70 is.rooted(tr)          # no!
  71 ### This is because the tree has been unrooted first before rerooting.
  72 ### You can delete the outgroup...
  73 is.rooted(drop.tip(tr, "Struthioniformes"))
  74 ### ... or resolve the basal trichotomy in two ways:
  75 is.rooted(multi2di(tr))
  76 is.rooted(root(bird.orders, 1, r = TRUE))
  77 ### To keep the basal trichotomy but forcing the tree as rooted:
  78 tr$root.edge <- 0
  79 is.rooted(tr)
  80 }
  81 \keyword{manip}