man/drop.tip.Rd

   1 \name{drop.tip}
   2 \alias{drop.tip}
   3 \alias{extract.clade}
   4 \title{Remove Tips in a Phylogenetic Tree}
   5 \description{
   6   \code{drop.tip} removes the terminal branches of a phylogenetic tree,
   7   possibly removing the corresponding internal branches.
   8
   9   \code{extract.clade} does the inverse operation: it keeps all the tips
  10   from a given node, and deletes all the other tips.
  11 }
  12 \usage{
  13 drop.tip(phy, tip, trim.internal = TRUE, subtree = FALSE,
  14          root.edge = 0, rooted = is.rooted(phy), interactive = FALSE)
  15 extract.clade(phy, node, root.edge = 0, interactive = FALSE)
  16 }
  17 \arguments{
  18   \item{phy}{an object of class \code{"phylo"}.}
  19   \item{tip}{a vector of mode numeric or character specifying the tips
  20     to delete.}
  21   \item{trim.internal}{a logical specifying whether to delete the
  22     corresponding internal branches.}
  23   \item{subtree}{a logical specifying whether to output in the tree how
  24     many tips have been deleted and where.}
  25   \item{root.edge}{an integer giving the number of internal branches to
  26     be used to build the new root edge. This has no effect if
  27     \code{trim.internal = FALSE}.}
  28   \item{rooted}{a logical indicating whether the tree must be treated as
  29     rooted or not. This allows to force the tree to be considered as
  30     unrooted (see examples).}
  31   \item{node}{a node number or label.}
  32   \item{interactive}{if \code{TRUE} the user is asked to select the tips
  33     or the node by clicking on the tree which must be plotted.}
  34 }
  35 \details{
  36   The argument \code{tip} can be either character or numeric. In the
  37   first case, it gives the labels of the tips to be deleted; in the
  38   second case the numbers of these labels in the vector
  39   \code{phy$tip.label} are given.
  40
  41   This also applies to \code{node}, but if this argument is character
  42   and the tree has no node label, this results in an error. If more than
  43   one value is given with \code{node} (i.e., a vector of length two or
  44   more), only the first one is used with a warning.
  45
  46   If \code{trim.internal = FALSE}, the new tips are given \code{"NA"} as
  47   labels, unless there are node labels in the tree in which case they
  48   are used.
  49
  50   If \code{subtree = TRUE}, the returned tree has one or several
  51   terminal branches indicating how many tips have been removed (with a
  52   label \code{"[x_tips]"}). This is done for as many monophyletic groups
  53   that have been deleted.
  54
  55   Note that \code{subtree = TRUE} implies \code{trim.internal = TRUE}.
  56
  57   To undestand how the option \code{root.edge} works, see the examples
  58   below.
  59 }
  60 \value{
  61   an object of class \code{"phylo"}.
  62 }
  63 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  64 \seealso{
  65   \code{\link{bind.tree}}, \code{\link{root}}
  66 }
  67 \examples{
  68 data(bird.families)
  69 tip <- c(
  70 "Eopsaltriidae", "Acanthisittidae", "Pittidae", "Eurylaimidae",
  71 "Philepittidae", "Tyrannidae", "Thamnophilidae", "Furnariidae",
  72 "Formicariidae", "Conopophagidae", "Rhinocryptidae", "Climacteridae",
  73 "Menuridae", "Ptilonorhynchidae", "Maluridae", "Meliphagidae",
  74 "Pardalotidae", "Petroicidae", "Irenidae", "Orthonychidae",
  75 "Pomatostomidae", "Laniidae", "Vireonidae", "Corvidae",
  76 "Callaeatidae", "Picathartidae", "Bombycillidae", "Cinclidae",
  77 "Muscicapidae", "Sturnidae", "Sittidae", "Certhiidae",
  78 "Paridae", "Aegithalidae", "Hirundinidae", "Regulidae",
  79 "Pycnonotidae", "Hypocoliidae", "Cisticolidae", "Zosteropidae",
  80 "Sylviidae", "Alaudidae", "Nectariniidae", "Melanocharitidae",
  81 "Paramythiidae","Passeridae", "Fringillidae")
  82 plot(drop.tip(bird.families, tip))
  83 plot(drop.tip(bird.families, tip, trim.internal = FALSE))
  84 data(bird.orders)
  85 plot(drop.tip(bird.orders, 6:23, subtree = TRUE))
  86 plot(drop.tip(bird.orders, c(1:5, 20:23), subtree = TRUE))
  87 plot(drop.tip(bird.orders, c(1:20, 23), subtree = TRUE))
  88 plot(drop.tip(bird.orders, c(1:20, 23), subtree = TRUE, rooted = FALSE))
  89 ### Examples of the use of `root.edge'
  90 tr <- read.tree(text = "(A:1,(B:1,(C:1,(D:1,E:1):1):1):1):1;")
  91 drop.tip(tr, c("A", "B"), root.edge = 0) # = (C:1,(D:1,E:1):1);
  92 drop.tip(tr, c("A", "B"), root.edge = 1) # = (C:1,(D:1,E:1):1):1;
  93 drop.tip(tr, c("A", "B"), root.edge = 2) # = (C:1,(D:1,E:1):1):2;
  94 drop.tip(tr, c("A", "B"), root.edge = 3) # = (C:1,(D:1,E:1):1):3;
  95 }
  96 \keyword{manip}