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