drop.tip {ape}

Remove Tips in a Phylogenetic Tree

Description

drop.tip removes the terminal branches of a phylogenetic tree, possibly removing the corresponding internal branches. keep.tip does the opposite operation (i.e., returns the induced tree).

extract.clade does the inverse operation: it keeps all the tips from a given node, and deletes all the other tips.

Usage

drop.tip(phy, tip, ...)
## S3 method for class 'phylo'
drop.tip(phy, tip, trim.internal = TRUE, subtree = FALSE,
         root.edge = 0, rooted = is.rooted(phy), collapse.singles = TRUE,
         interactive = FALSE, ...)
## S3 method for class 'multiPhylo'
drop.tip(phy, tip, ...)

keep.tip(phy, tip, ...)
## S3 method for class 'phylo'
keep.tip(phy, tip, ...)
## S3 method for class 'multiPhylo'
keep.tip(phy, tip, ...)

extract.clade(phy, node, root.edge = 0, collapse.singles = TRUE,
              interactive = FALSE)

Arguments

phy

an object of class "phylo".

tip

a vector of mode numeric or character specifying the tips to delete.

trim.internal

a logical specifying whether to delete the corresponding internal branches.

subtree

a logical specifying whether to output in the tree how many tips have been deleted and where.

root.edge

an integer giving the number of internal branches to be used to build the new root edge. This has no effect if trim.internal = FALSE.

rooted

a logical indicating whether the tree must be treated as rooted or not. This allows to force the tree to be considered as unrooted (see examples). See details about a possible root.edge element in the tree.

collapse.singles

a logical specifying whether to delete the internal nodes of degree 2.

node

a node number or label.

interactive

if TRUE the user is asked to select the tips or the node by clicking on the tree which must be plotted.

...

arguments passed from and to methods.

Details

The argument tip can be either character or numeric. In the first case, it gives the labels of the tips to be deleted; in the second case the numbers of these labels in the vector phy$tip.label are given.

This also applies to node, but if this argument is character and the tree has no node label, this results in an error. If more than one value is given with node (i.e., a vector of length two or more), only the first one is used with a warning.

If trim.internal = FALSE, the new tips are given "NA" as labels, unless there are node labels in the tree in which case they are used.

If subtree = TRUE, the returned tree has one or several terminal branches named with node labels if available. Otherwise it is indicated how many tips have been removed (with a label "[x_tips]"). This is done for as many monophyletic groups that have been deleted.

Note that subtree = TRUE implies trim.internal = TRUE.

To undestand how the option root.edge works, see the examples below. If rooted = FALSE and the tree has a root edge, the latter is removed in the output.

Value

an object of class "phylo".

Author(s)

Emmanuel Paradis, Klaus Schliep, Joseph Brown

See Also

bind.tree, root

Examples

data(bird.families)
tip <- c(
"Eopsaltriidae", "Acanthisittidae", "Pittidae", "Eurylaimidae",
"Philepittidae", "Tyrannidae", "Thamnophilidae", "Furnariidae",
"Formicariidae", "Conopophagidae", "Rhinocryptidae", "Climacteridae",
"Menuridae", "Ptilonorhynchidae", "Maluridae", "Meliphagidae",
"Pardalotidae", "Petroicidae", "Irenidae", "Orthonychidae",
"Pomatostomidae", "Laniidae", "Vireonidae", "Corvidae",
"Callaeatidae", "Picathartidae", "Bombycillidae", "Cinclidae",
"Muscicapidae", "Sturnidae", "Sittidae", "Certhiidae",
"Paridae", "Aegithalidae", "Hirundinidae", "Regulidae",
"Pycnonotidae", "Hypocoliidae", "Cisticolidae", "Zosteropidae",
"Sylviidae", "Alaudidae", "Nectariniidae", "Melanocharitidae",
"Paramythiidae","Passeridae", "Fringillidae")
plot(drop.tip(bird.families, tip))
plot(drop.tip(bird.families, tip, trim.internal = FALSE))
data(bird.orders)
plot(drop.tip(bird.orders, 6:23, subtree = TRUE))
plot(drop.tip(bird.orders, c(1:5, 20:23), subtree = TRUE))
plot(drop.tip(bird.orders, c(1:20, 23), subtree = TRUE))
plot(drop.tip(bird.orders, c(1:20, 23), subtree = TRUE, rooted = FALSE))
### Examples of the use of `root.edge'
tr <- read.tree(text = "(A:1,(B:1,(C:1,(D:1,E:1):1):1):1):1;")
drop.tip(tr, c("A", "B"), root.edge = 0) # = (C:1,(D:1,E:1):1);
drop.tip(tr, c("A", "B"), root.edge = 1) # = (C:1,(D:1,E:1):1):1;
drop.tip(tr, c("A", "B"), root.edge = 2) # = (C:1,(D:1,E:1):1):2;
drop.tip(tr, c("A", "B"), root.edge = 3) # = (C:1,(D:1,E:1):1):3;