man/bind.tree.Rd

   1 \name{bind.tree}
   2 \alias{bind.tree}
   3 \alias{+.phylo}
   4 \title{Binds Trees}
   5 \usage{
   6 bind.tree(x, y, where = "root", position = 0, interactive = FALSE)
   7 \special{x + y}
   8 }
   9 \arguments{
  10   \item{x}{an object of class \code{"phylo"}.}
  11   \item{y}{an object of class \code{"phylo"}.}
  12   \item{where}{an integer giving the number of the node or tip of the
  13     tree \code{x} where the tree \code{y} is binded (\code{"root"} is a
  14     short-cut for the root).}
  15   \item{position}{a numeric value giving the position from the tip or
  16     node given by \code{node} where the tree \code{y} is binded;
  17     negative values are ignored.}
  18   \item{interactive}{if \code{TRUE} the user is asked to choose the tip
  19     or node of \code{x} by clicking on the tree which must be plotted.}
  20 }
  21 \description{
  22   This function binds together two phylogenetic trees to give a single
  23   object of class \code{"phylo"}.
  24 }
  25 \details{
  26   The argument \code{x} can be seen as the receptor tree, whereas
  27   \code{y} is the donor tree. The root of \code{y} is then grafted on a
  28   location of \code{x} specified by \code{where} and, possibly,
  29   \code{position}. If \code{y} has a root edge, this is added as in
  30   internal branch in the resulting tree.
  31
  32   \code{x + y} is a shortcut for:
  33
  34   \preformatted{
  35     bind.tree(x, y, position = if (is.null(x$root.edge)) 0 else
  36     x$root.edge)
  37   }
  38
  39   If only one of the trees has no branch length, the branch lengths of
  40   the other one are ignored with a warning.
  41
  42   If one (or both) of the trees has no branch length, it is possible to
  43   specify a value of 'position' to graft 'y' below the node of 'x'
  44   specified by 'where'. In this case, the exact value of 'position' is
  45   not important as long as it is greater than zero. The new node will be
  46   multichotomous if 'y' has no root edge. This can be solved by giving
  47   an arbitrary root edge to 'y' beforehand (e.g., \code{y$root.edge <-
  48   1}): it will be deleted during the binding operation.
  49 }
  50 \value{
  51   an object of class \code{"phylo"}.
  52 }
  53 \author{Emmanuel Paradis}
  54 \seealso{
  55   \code{\link{drop.tip}}, \code{\link{root}}
  56 }
  57 \examples{
  58 ### binds the two clades of bird orders
  59 cat("((Struthioniformes:21.8,Tinamiformes:21.8):4.1,",
  60     "((Craciformes:21.6,Galliformes:21.6):1.3,Anseriformes:22.9):3.0):2.1;",
  61     file = "ex1.tre", sep = "\n")
  62 cat("(Turniciformes:27.0,(Piciformes:26.3,((Galbuliformes:24.4,",
  63     "((Bucerotiformes:20.8,Upupiformes:20.8):2.6,",
  64     "(Trogoniformes:22.1,Coraciiformes:22.1):1.3):1.0):0.6,",
  65     "(Coliiformes:24.5,(Cuculiformes:23.7,(Psittaciformes:23.1,",
  66     "(((Apodiformes:21.3,Trochiliformes:21.3):0.6,",
  67     "(Musophagiformes:20.4,Strigiformes:20.4):1.5):0.6,",
  68     "((Columbiformes:20.8,(Gruiformes:20.1,Ciconiiformes:20.1):0.7):0.8,",
  69     "Passeriformes:21.6):0.9):0.6):0.6):0.8):0.5):1.3):0.7):1.0;",
  70     file = "ex2.tre", sep = "\n")
  71 tree.bird1 <- read.tree("ex1.tre")
  72 tree.bird2 <- read.tree("ex2.tre")
  73 unlink(c("ex1.tre", "ex2.tre")) # clean-up
  74 (birds <- tree.bird1 + tree.bird2)
  75 layout(matrix(c(1, 2, 3, 3), 2, 2))
  76 plot(tree.bird1)
  77 plot(tree.bird2)
  78 plot(birds)
  79
  80 ### examples with random trees
  81 x <- rtree(4, tip.label = LETTERS[1:4])
  82 y <- rtree(4, tip.label = LETTERS[5:8])
  83 x <- makeNodeLabel(x, prefix = "x_")
  84 y <- makeNodeLabel(y, prefix = "y_")
  85 x$root.edge <- y$root.edge <- .2
  86
  87 z <- bind.tree(x, y, po=.2)
  88 plot(y, show.node.label = TRUE, font = 1, root.edge = TRUE)
  89 title("y")
  90 plot(x, show.node.label = TRUE, font = 1, root.edge = TRUE)
  91 title("x")
  92 plot(z, show.node.label = TRUE, font = 1, root.edge = TRUE)
  93 title("z <- bind.tree(x, y, po=.2)")
  94
  95 z <- bind.tree(x, y, 2, .1)
  96 plot(y, show.node.label = TRUE, font = 1, root.edge = TRUE)
  97 title("y")
  98 plot(x, show.node.label = TRUE, font = 1, root.edge = TRUE)
  99 title("x")
 100 plot(z, show.node.label = TRUE, font = 1, root.edge = TRUE)
 101 title("z <- bind.tree(x, y, 2, .1)")
 102
 103 x <- rtree(50)
 104 y <- rtree(50)
 105 x$root.edge <- y$root.edge <- .2
 106 z <- x + y
 107 plot(y, show.tip.label = FALSE, root.edge = TRUE); axisPhylo()
 108 title("y")
 109 plot(x, show.tip.label = FALSE, root.edge = TRUE); axisPhylo()
 110 title("x")
 111 plot(z, show.tip.label = FALSE, root.edge = TRUE); axisPhylo()
 112 title("z <- x + y")
 113 layout(1)
 114 }
 115 \keyword{manip}