[Phylobase-commits] r621 - in pkg: . R inst/unitTests man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Fri Sep 4 23:54:26 CEST 2009
Author: regetz
Date: 2009-09-04 23:54:25 +0200 (Fri, 04 Sep 2009)
New Revision: 621
Removed:
pkg/man/prune-methods.Rd
Modified:
pkg/NAMESPACE
pkg/R/prune.R
pkg/R/subset.R
pkg/inst/unitTests/runit.prune.R
pkg/inst/unitTests/runit.subset.R
pkg/man/subset-methods.Rd
Log:
* removed ape::phylo subset/prune methods
* integrated prune documentation into subset-methods.Rd
* overhauled documentation and updated examples
* updated NAMESPACE and unit tests
Modified: pkg/NAMESPACE
===================================================================
--- pkg/NAMESPACE 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/NAMESPACE 2009-09-04 21:54:25 UTC (rev 621)
@@ -16,8 +16,7 @@
#----------------------------------------------------------------------
# utility methods
-exportMethods("[", "[<-", "[[", "[[<-", print, head, tail,
- reorder, subset, plot, summary)
+exportMethods(print, head, tail, reorder, plot, summary)
# tree constructor methods
exportMethods(phylo4, phylo4d)
@@ -39,9 +38,12 @@
# tree data methods
exportMethods(tdata, "tdata<-", addData, hasTipData, hasNodeData)
-# prune methods
-exportMethods(prune)
+# subset methods
+exportMethods(subset, prune, "[")
+# pdata methods
+exportMethods("[<-", "[[", "[[<-")
+
# label methods
exportMethods(labels, "labels<-", nodeLabels, "nodeLabels<-",
tipLabels, "tipLabels<-", edgeLabels, "edgeLabels<-",
@@ -62,9 +64,6 @@
# pdata functions
export(pdata, check_pdata)
-# prune functions --> maybe don't export?
-export(DropTip)
-
# plotting functions
export(treePlot, plotOneTree, tip.data.plot)
export(phyloXXYY, phylobubbles)
Modified: pkg/R/prune.R
===================================================================
--- pkg/R/prune.R 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/R/prune.R 2009-09-04 21:54:25 UTC (rev 621)
@@ -1,29 +1,9 @@
-## drop.tip4.R
-## modified from drop.tip.R (2006-10-12)
-## Remove Tips in a Phylogenetic Tree
-## Copyright 2003-2006 Emmanuel Paradis
-## This file is part of the R-package `ape'.
-
-## See the file ../COPYING for licensing issues.
-
setGeneric("prune",function(phy, ...) {
standardGeneric("prune")
})
-## setGeneric("drop.tip") ## if ape has already been loaded
-
-DropTip <- function(phy,tip,...) {
- if (length(tip)==0) {
- phy
- } else if (is(phy,"phylo4d")) {
- ## use extract.tree instead of as() to avoid warning
- as(ape::drop.tip(as(extractTree(phy),"phylo"),tip,...),"phylo4d")
- } else as(ape::drop.tip(as(phy,"phylo"),tip,...),class(phy))
-}
-
-
## return characters, sorted in NUMERIC order
.chnumsort <- function(x) {
as.character(sort(as.numeric(x)))
@@ -33,10 +13,7 @@
function(phy, tip, trim.internal = TRUE, subtree = FALSE, ...) {
if (subtree) {
- #stop("subtree option is not currently supported for phylo4")
- # do this for now (at least to allow examples to pass check)
warning("subtree option is not currently supported for phylo4")
- return(DropTip(phy,tip,trim.internal, subtree))
}
makeEdgeNames <- function(edge) {
@@ -182,12 +159,6 @@
phytr
})
-setMethod("prune", "phylo",
- function(phy, tip, trim.internal = TRUE, subtree = FALSE,
- ...) {
- DropTip(phy, tip, trim.internal, subtree)
- })
-
## setMethod("prune","ANY",
## function(phy, tip, trim.internal = TRUE, subtree = FALSE,
## ,...) {
Modified: pkg/R/subset.R
===================================================================
--- pkg/R/subset.R 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/R/subset.R 2009-09-04 21:54:25 UTC (rev 621)
@@ -13,11 +13,11 @@
mrca,node.subtree),is.null))>1) {
stop("must specify at most one criterion for subsetting")
}
- arglist <- list(...)
- if (length(arglist)>0) {
- warning("unused arguments: ",
- paste(names(arglist),collapse=","))
- }
+ #arglist <- list(...)
+ #if (length(arglist)>0) {
+ # warning("unused arguments: ",
+ # paste(names(arglist),collapse=","))
+ #}
kept <- x at tip.label
dropped <- character(0)
if (!is.null(tips.include)) {
@@ -59,19 +59,9 @@
stop("0 or 1 tips would remain after subsetting")
}
if (length(dropped)==0) return(x)
- return(prune(x,dropped))
+ return(prune(x, dropped, ...))
})
-
-setMethod("subset", "phylo", function(x,...) {
- x <- as(x,"phylo4")
- res <- subset(x,...)
- return(as(res,"phylo"))
-})
-
-
-
-
###############
# '[' operator
###############
Modified: pkg/inst/unitTests/runit.prune.R
===================================================================
--- pkg/inst/unitTests/runit.prune.R 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/inst/unitTests/runit.prune.R 2009-09-04 21:54:25 UTC (rev 621)
@@ -5,11 +5,6 @@
data(geospiza)
gtree <- extractTree(geospiza)
-
-test.DropTip <- function() {
- # function(phy, tip, ...)
-}
-
test.prune.phylo4 <- function() {
# function(phy, tip, trim.internal = TRUE, subtree = FALSE, ...)
checkIdentical(gtree, prune(gtree, character(0)))
@@ -19,7 +14,3 @@
# function(phy, tip, trim.internal = TRUE, subtree = FALSE, ...)
checkIdentical(geospiza, prune(geospiza, character(0)))
}
-
-test.prune.phylo <- function() {
- # function(phy, tip, trim.internal = TRUE, subtree = FALSE, ...)
-}
Modified: pkg/inst/unitTests/runit.subset.R
===================================================================
--- pkg/inst/unitTests/runit.subset.R 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/inst/unitTests/runit.subset.R 2009-09-04 21:54:25 UTC (rev 621)
@@ -9,32 +9,7 @@
tr <- read.tree(text="(((t1:0.2,(t2:0.1,t3:0.1):0.15):0.5,t4:0.7):0.2,t5:1):0.4;")
tr.sub2 <- read.tree(text="(t2:0.95,t5:1);")
tr.sub4 <- read.tree(text="(((t1:0.2,t2:0.25):0.5,t4:0.7):0.2,t5:1);")
-# Explicitly set order as 'cladewise', to match behavior of
-# ape::drop.tip in test comparisons below
-tr <- reorder(tr, "cladewise")
-tr.sub2 <- reorder(tr.sub2, "cladewise")
-tr.sub4 <- reorder(tr.sub4, "cladewise")
-test.subset.phylo <- function() {
- # subset 2 tips
- checkEquals(tr.sub2, subset(tr, tips.include=c(2, 5)))
- checkEquals(tr.sub2, subset(tr, tips.exclude=c(1, 3, 4)))
- checkEquals(tr.sub2, subset(tr, tips.include=c("t2", "t5")))
- checkEquals(tr.sub2, subset(tr, tips.exclude=c("t1", "t3", "t4")))
- # subset 4 tips
- checkEquals(tr.sub4, subset(tr, tips.include=c(1, 2, 4, 5)))
- checkEquals(tr.sub4, subset(tr, tips.exclude=3))
- checkEquals(tr.sub4, subset(tr, tips.include=c("t1", "t2", "t4", "t5")))
- checkEquals(tr.sub4, subset(tr, tips.exclude="t3"))
- # check variants that should all return the original object
- checkEquals(tr, subset(tr))
- # error if only one valid tip requested
- checkException(subset(tr, tips.include="t1"))
- checkException(subset(tr, tips.include=c("t1", "t999")))
- # error if zero valid tips requested
- checkException(subset(tr, tips.include="t999"))
-}
-
test.subset.phylo4 <- function() {
# subset 2 tips
checkEquals(phy.sub2, subset(phy, tips.include=c(2, 5)))
Deleted: pkg/man/prune-methods.Rd
===================================================================
--- pkg/man/prune-methods.Rd 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/man/prune-methods.Rd 2009-09-04 21:54:25 UTC (rev 621)
@@ -1,105 +0,0 @@
-\name{prune-methods}
-\docType{methods}
-\alias{prune}
-\alias{prune-methods}
-\alias{prune,phylo-method}
-\alias{prune,phylo4-method}
-\alias{prune,phylo4d-method}
-\alias{na.omit,phylo4d-method}
-\alias{DropTip}
-\title{Methods for dropping tips}
-\description{
- Methods for pruning phylogenies: remove terminal branches of
- a phylogenetic tree,
- possibly removing the corresponding internal branches.
- Preserve match to edge and node data.
-}
-\section{Methods}{
- \describe{
- \item{phy = "phylo4d"}{drop tips and corresponding node and tip data}
- \item{phy = "phylo4"}{drop tips}
- \item{phy = "phylo"}{drop tips}
- }
-}
-\note{The phylo method simply wraps \code{ape::drop.tip}.}
- \usage{
-\S4method{prune}{phylo4}(phy, tip, trim.internal = TRUE, subtree = FALSE, \dots)
-\S4method{prune}{phylo4d}(phy, tip, trim.internal = TRUE, subtree = FALSE, \dots)
-\S4method{prune}{phylo}(phy, tip, trim.internal = TRUE, subtree = FALSE, \dots)
-DropTip(phy, tip, \dots)
-}
-\arguments{
- \item{phy}{an object of class \code{"phylo4"}}
- \item{tip}{a vector of mode numeric or character specifying the tips
- to delete}
- \item{trim.internal}{a logical specifying whether to delete the
- corresponding internal branches}
- \item{subtree}{a logical specifying whether to output in the tree how
- many tips have been deleted and where}
- \item{\dots}{additional arguments}
-}
-\details{
- The argument \code{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
- \code{tipLabels(phy)} are given
-
- If \code{trim.internal = FALSE}, the new tips are given \code{NA} as
- labels, unless there are node labels in the tree in which case they
- are used
-
- If \code{subtree = TRUE}, the returned tree has one or several
- terminal branches indicating how many tips have been removed (with a
- label \code{"[x_tips]"}). This is done for as many monophyletic groups
- that have been deleted. This option is only implemented for the
- phylo method, and thus if used on phylo4 or phylo4d objects, they will
- be coerced to phylo
-
- Note that \code{subtree = TRUE} implies \code{trim.internal = TRUE}
-
- Handling of root edge lengths differs between \code{phylobase} and
- \code{ape}. For phylo4/phylo4d objects, the new root edge length
- will be the total distance back through the original root edge (or NA
- if the original edge had length NA)
-
- A \code{root.edge} argument can be passed to the phylo method. To
- understand how this option works, see the examples below
-}
-\value{
- an object of class \code{"phylo4"}
-}
-\author{
- Jim Regetz \email{regetz at nceas.ucsb.edu} (phylo4 method),
- Emmanuel Paradis \email{Emmanuel.Paradis at mpl.ird.fr
- (original ape version used in phylo method)}
-}
-\examples{
-data(geospiza)
-
-## Pruning phylo4 objects
-geotree <- extractTree(geospiza)
-tip <- c("difficilis", "fortis", "fuliginosa", "fusca", "olivacea",
- "pallida", "parvulus", "scandens")
-plot(prune(geotree, tip))
-plot(prune(geotree, tip, trim.internal = FALSE))
-plot(prune(geotree, 1:11, subtree = TRUE))
-
-## Pruning phylo4d objects
-r1 <- as(rcoal(5), "phylo4")
-td <- data.frame(a=1:5, row.names=paste("t", 1:5, sep=""))
-nd <- data.frame(a=6:9, row.names=nodeId(r1, "internal"))
-r2 <- phylo4d(r1, tip.data=td, node.data=nd)
-r3 <- prune(r2, "t1")
-
-## Pruning phylo objects, including the use of `root.edge'
-require(ape)
-tr <- as(ape::read.tree(text = "(A:1,(B:1,(C:1,(D:1,E:1):1):1):1):1;"),"phylo4")
-prune(tr, c("A", "B"), root.edge = 0) # = (C:1,(D:1,E:1):1);
-prune(tr, c("A", "B"), root.edge = 1) # = (C:1,(D:1,E:1):1):1;
-prune(tr, c("A", "B"), root.edge = 2) # = (C:1,(D:1,E:1):1):2;
-prune(tr, c("A", "B"), root.edge = 3) # = (C:1,(D:1,E:1):1):3;
-
-}
-\keyword{manip}
-\keyword{methods}
-
Modified: pkg/man/subset-methods.Rd
===================================================================
--- pkg/man/subset-methods.Rd 2009-09-03 21:59:20 UTC (rev 620)
+++ pkg/man/subset-methods.Rd 2009-09-04 21:54:25 UTC (rev 621)
@@ -1,87 +1,141 @@
\name{subset-methods}
\docType{methods}
-\alias{subset}
\alias{subset-methods}
-\alias{subset,phylo-method}
\alias{subset,phylo4-method}
\alias{subset,phylo4d-method}
+\alias{prune}
+\alias{prune-methods}
+\alias{prune,phylo4-method}
+\alias{prune,phylo4d-method}
+\alias{[-methods}
\alias{[,phylo4-method}
\alias{[,phylo4d-method}
+\alias{na.omit,phylo4d-method}
\title{Methods for creating subsets of phylogenies}
\description{
Methods for creating subsets of phylogenies, based on pruning a tree
to include or exclude a set of terminal taxa, to include all
- descendants of the MRCA of two taxa, or eventually to a subtree rooted
- at a given node.\cr
-
- The "[" operator can be used with \linkS4class{phylo4} and
- \linkS4class{phylo4d} objects. With a \linkS4class{phylo4} object
- 'foo', \code{foo[i]} creates a subset of \code{foo} taking \code{i}
- for a tip index. With a \linkS4class{phylo4d} object
- 'foo', \code{foo[i,j]} creates a subset of \code{foo} taking \code{i}
- for a tip index and \code{j} for the index of tips variables (see
- details).\cr
+ descendants of the MRCA of multiple taxa, or to return a subtree
+ rooted at a given node.
}
\section{Methods}{
\describe{
- \item{phy = "phylo4d"}{drop tips and corresponding node and tip data}
- \item{phy = "phylo4"}{drop tips}
- \item{phy = "phylo"}{drop tips}
+ \item{x = "phylo4"}{subset tree}
+ \item{x = "phylo4d"}{subset tree and corresponding node and tip data}
}
}
-\note{At the moment, this simply wraps \code{ape::drop.tip}.
- Renamed from \code{drop.tip} to \code{prune} in order to
- avoid conflicts with ape.}
\usage{
-\S4method{subset}{phylo4}(x, tips.include=NULL, tips.exclude=NULL, mrca=NULL, node.subtree=NULL, \dots)
+\S4method{subset}{phylo4}(x, tips.include=NULL, tips.exclude=NULL,
+ mrca=NULL, node.subtree=NULL, \dots)
+\S4method{subset}{phylo4d}(x, tips.include=NULL, tips.exclude=NULL,
+ mrca=NULL, node.subtree=NULL, \dots)
-\S4method{subset}{phylo4d}(x, tips.include=NULL, tips.exclude=NULL, mrca=NULL, node.subtree=NULL, \dots)
-\S4method{subset}{phylo}(x, \dots)
+\S4method{prune}{phylo4}(x, tips.exclude, trim.internal = TRUE, \dots)
+\S4method{prune}{phylo4d}(x, tips.exclude, trim.internal = TRUE, \dots)
+
+\S4method{[}{phylo4}(x, i)
+\S4method{[}{phylo4d}(x, i, j)
}
\arguments{
- \item{x}{an object of class \code{"phylo4"}, \code{"phylo"} or \code{"phylo4d"}}
- \item{tips.include}{A vector containing tips to include in the pruned tree}
- \item{tips.exclude}{A vector containing tips to exclude from the pruned tree}
- \item{mrca}{Prune tree to include all descendants of the most recent common ancestor of the specified taxa}
- \item{node.subtree}{Prune to all descendants of a specified node}
- \item{\dots}{further arguments to be passed to other methods}
+ \item{x}{an object of class \code{"phylo4"} or \code{"phylo4d"}}
+ \item{tips.include}{A vector of tips to include in the subset tree}
+ \item{tips.exclude}{A vector of tips to exclude from the subset tree}
+ \item{mrca}{A vector of tips for determining the most recent common
+ ancestor, which is then used as the root of the subset tree}
+ \item{node.subtree}{A single internal node specifying the root of the
+ subset tree}
+ \item{trim.internal}{A logical specifying whether to remove internal
+ nodes that no longer have tip descendants in the subset tree}
+ \item{i}{(\code{[} method) An index vector indicating tips to include}
+ \item{j}{(\code{[} method, phylo4d only) An index vector indicating
+ columns of node/tip data to include}
+ \item{\dots}{additional arguments to be passed to other methods}
}
\details{
- The arguments \code{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
- \code{phy\$tip.label} are given.\cr
+ The \code{subset} methods must be called using no more than one of the
+ four main subsetting criteria arguments (\code{tips.include},
+ \code{tips.exclude}, \code{mrca}, or \code{node.subtree}). Each of
+ these arguments can be either character or numeric. In the first case,
+ they are treated as node labels; in the second case, they are treated
+ as node numbers. For the first three arguments, any supplied tips not
+ found in the tree (\code{tipLabels(x)}) will be ignored, with a
+ warning. For the \code{node.subtree} argument, failure to provide a
+ single, valid internal node will result in an error.
- The indices used with the \code{[} operator can be characters, integers
- or logical, just like with a vector or a matrix.\cr
- If \code{foo} is a \linkS4class{phylo4d} object, the index of
- variables ("j") is optional: \code{foo[i,j]} is the same as
- \code{foo[i]}.\cr
+ Although \code{prune} is mainly intended as the workhorse function
+ called by \code{subset}, it may also be called directly. In general
+ it should be equivalent to the \code{tips.exclude} form of
+ \code{subset} (although perhaps with less up-front error checking).
+ The "[" operator, when used as \code{x[i]}, is similar to the
+ \code{tips.include} form of \code{subset}. However, the indices used
+ with this operator can also be logical, just like with a vector or a
+ matrix. With a \linkS4class{phylo4d} object 'x', \code{x[i,j]}
+ creates a subset of \code{x} taking \code{i} for a tip index and
+ \code{j} for the index of data variables in \code{tdata(geospiza,
+ "all")}. Note that the second index is optional: \code{x[i, TRUE]},
+ \code{x[i,]}, and \code{x[i]} are all equivalent.
+
+ Regardless of which approach to subsetting is used, the argument
+ values must be such that at least two tips are retained.
+
+ If the most recent common ancestor of the retained tips is not the
+ original root node, then the root node of the subset tree will be a
+ descendant of the original root. For rooted trees with non-NA root
+ edge length, this has implications for the new root edge length. In
+ particular, the new length will be the summed edge length from the new
+ root node back to the original root (including the original root
+ edge). As an alternative, see the examples for a way to determine the
+ length of the edge that was immediately ancestral to the new root node
+ in the original tree.
+
+ Note that the correspondance between nodes and labels (and data in the
+ case of \linkS4class{phylo4d}) will be retained after all forms of
+ subsetting. Beware, however, that the node numbers (IDs) will likely
+ be altered to reflect the new tree topology, and therefore cannot be
+ compared directly between the original tree and the subset tree.
}
\value{
- an object of class \code{"phylo4"}
+ an object of class \code{"phylo4"} or \code{"phylo4d"}
}
-\author{Steven Kembel \email{skembel at berkeley.edu}\cr
+\author{
+ Jim Regetz \email{regetz at nceas.ucsb.edu}\cr
+ Steven Kembel \email{skembel at berkeley.edu}\cr
Damien de Vienne \email{damien.de-vienne at u-psud.fr}\cr
Thibaut Jombart \email{jombart at biomserv.univ-lyon1.fr}
}
\examples{
data(geospiza)
+nodeLabels(geospiza) <- paste("N", nodeId(geospiza), sep="")
+geotree <- extractTree(geospiza)
## "subset" examples
-g1 <- as(geospiza,"phylo4")
-nodeLabels(g1) <- paste("N", nodeId(g1), sep="")
-plot(subset(g1,tips.exclude="scandens"))
-plot(subset(g1,mrca=c("scandens","fortis","pauper")))
-plot(subset(g1,node.subtree=18))
+tips <- c("difficilis", "fortis", "fuliginosa", "fusca", "olivacea",
+ "pallida", "parvulus", "scandens")
+plot(subset(geotree, tips.include=tips))
+plot(subset(geotree, tips.include=tips, trim.internal=FALSE))
+plot(subset(geotree, tips.exclude="scandens"))
+plot(subset(geotree, mrca=c("scandens","fortis","pauper")))
+plot(subset(geotree, node.subtree=18))
-## "[" examples
-plot(g1,show.node.label=TRUE)
-plot(g1[c(1:6,14)],show.node.label=TRUE)
-nodeLabels(geospiza) <- paste("N", nodeId(geospiza), sep="")
-plot(geospiza[c(1:6,14)],show.node.label=TRUE)
-plot(geospiza[c(1:6,14),3:5],show.node.label=TRUE)
+## "prune" examples (equivalent to subset using tips.exclude)
+plot(prune(geotree, tips))
+
+## "[" examples (equivalent to subset using tips.include)
+plot(geotree[c(1:6,14)])
+plot(geospiza[c(1:6,14)])
+
+## for phylo4d, subset both tips and data columns
+geospiza[c(1:6,14), c("wingL", "beakD")]
+
+## note handling of root edge length:
+edgeLength(geotree)['NA-15'] <- 0.1
+geotree2 <- geotree[1:2]
+## in subset tree, edge of new root extends back to the original root
+edgeLength(geotree2)['NA-3']
+## edge length immediately ancestral to this node in the original tree
+edgeLength(geotree, MRCA(geotree, tipLabels(geotree2)))
+
}
\keyword{manip}
\keyword{methods}
More information about the Phylobase-commits
mailing list