[Phylobase-commits] r575 - pkg/man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Aug 24 05:35:58 CEST 2009
Author: francois
Date: 2009-08-24 05:35:58 +0200 (Mon, 24 Aug 2009)
New Revision: 575
Modified:
pkg/man/as-methods.Rd
pkg/man/check.phylo4.Rd
pkg/man/check.phylo4d.Rd
Log:
updated documentation to reflect changes in code and reorganization: checkPhylo4Data is on the same page as other validators, formatData is on its own page
Modified: pkg/man/as-methods.Rd
===================================================================
--- pkg/man/as-methods.Rd 2009-08-24 03:34:40 UTC (rev 574)
+++ pkg/man/as-methods.Rd 2009-08-24 03:35:58 UTC (rev 575)
@@ -25,80 +25,123 @@
\alias{coerce,phylo4d,data.frame-method}
\alias{coerce,phylo4vcov,phylo4-method}
\alias{coerce,phylo4,phylo4vcov-method}
-%\alias{coerce,phylo4d,phylo4-method}
+\title{Converting between phylo4/phylo4d and other phylogenetic tree formats}
-\title{Converting between phylo4 and other phylogenetic trees}
-
\section{Usage}{
-\code{as(tree, Class)}
+\code{as(object, class)}
}
\section{Arguments}{
\describe{
- \item{\code{tree}}{a tree of class \code{phylo4}, \code{phylo} or \code{phylog}, or tree+data object of class \code{phylo4d}.}
- \item{\code{Class}}{the name of the class to which \code{tree} should be coerced (e.g., \code{"phylo4"} or \code{"data.frame"}).}
+ \item{\code{object}}{a tree of class \code{phylo4}, \code{phylo} or
+ \code{phylog}, or tree and data object of class \code{phylo4d}.}
+ \item{\code{class}}{the name of the class to which \code{tree} should
+ be coerced (e.g., \code{"phylo4"} or \code{"data.frame"}).}
}
}
\description{
- Translation functions to convert between phylobase trees or trees+data objects (\code{phylo4}, \code{phylo4d}), and objects used by other comparative methods packages in R: \code{ape} objects
- (\code{phylo}, \code{multiPhylo}) \code{ade4} objects (\code{phylog}), and to \code{data.frame} respresentation.
+ Translation functions to convert between phylobase objects
+ (\code{phylo4} or \code{phylo4d}), and objects used by other
+ comparative methods packages in R: \code{ape} objects (\code{phylo},
+ \code{multiPhylo}), \code{ade4} objects (\code{phylog}), and to
+ \code{data.frame} respresentation.
}
+
\section{Methods}{
-\describe{
- \item{coerce}{from one object class to another using \code{as(object,"Class")}, where the \code{object} is of the old class and the returned object is of the new class \code{"Class"}. The \code{as} function examines the class of \code{object} and the new \code{"Class"} specified to choose the proper conversion without additional information from the user. Conversions exist for combinations:}
+
+ Coerce from one object class to another using
+ \code{as(object, "class")}, where the \code{object} is of the old class
+ and the returned object is of the new class \code{"class"}. The
+ \code{as} function examines the class of \code{object} and the new
+ \code{"class"} specified to choose the proper conversion without
+ additional information from the user. Conversions exist for
+ combinations:
+
\describe{
-
- \item{\code{phylobase} to \code{phylobase} formats:}{
- \describe{
- \item{\code{as(object, "phylo4d")}}{where object is of class \linkS4class{phylo4} and returns an object of class \linkS4class{phylo4d}, with empty data.}
- \item{\code{as(object, "phylo4")}}{where object is of class \linkS4class{phylo4d} and returns an object of class \linkS4class{phylo4}, dropping data with warning.}
- }
+
+ \item{}{\code{phylobase} to \code{phylobase} formats:}
+ \itemize{
+ \item{\code{as(object, "phylo4d")}}{where object is of class
+ \linkS4class{phylo4} and returns an object of class
+ \linkS4class{phylo4d}, with empty data.}
+ \item{\code{as(object, "phylo4")}}{where object is of class
+ \linkS4class{phylo4d} and returns an object of class
+ \linkS4class{phylo4}. If data are dropped during the conversion, a
+ warning message is produced. A similar conversion can be done by
+ using the function \code{extractTree}, but in this case, no error
+ message is produced.}
}
- \item{\code{phylobase} to \code{ape} formats:}{
- \describe{
- \item{\code{as(object, "phylo")}}{where object is of class \linkS4class{phylo4} or \linkS4class{phylo4d} and returns an object of class \code{phylo}, with data dropped in the case of \code{phylo4d} conversion (with warning).}
- \item{\code{as(object, "multiPhylo")}}{ ~~Not implemented yet. where object is of class \linkS4class{multiPhylo4} and returns an object of class \code{multiPhylo}. }
- }
+
+ \item{}{\code{phylobase} to \code{ape} formats:}
+ \itemize{
+ \item{\code{as(object, "phylo")}}{where object is of class
+ \linkS4class{phylo4} or \linkS4class{phylo4d} and returns an
+ object of class \code{phylo}. If data are dropped during the
+ conversion from a \code{phylo4d} object, a warning message is
+ produced.}
+ \item{\code{as(object, "multiPhylo")}}{ ~~Not implemented
+ yet. where object is of class \linkS4class{multiPhylo4} and returns
+ an object of class \code{multiPhylo}. }
}
- \item{\code{ape} to \code{phylobase} formats:}{
- \describe{
- \item{\code{as(object, "phylo4")}}{where object is of class \code{phylo} and returns an object of class \code{phylo4}.}
- \item{\code{as(object, "phylo4d")}}{where object is of class \code{phylo} and returns an object of class \code{phylo4d}, with empty data.}
- \item{\code{as(object, "multiPhylo4")}}{ ~~Not implemented yet. where object is of class \code{multiPhylo} and returns an object of class \code{multiPhylo4}. }
- }
+
+ \item{}{\code{ape} to \code{phylobase} formats:}
+ \itemize{
+ \item{\code{as(object, "phylo4")}}{where object is of class
+ \code{phylo} and returns an object of class \code{phylo4}.}
+ \item{\code{as(object, "phylo4d")}}{where object is of class
+ \code{phylo} and returns an object of class \code{phylo4d}, with
+ empty data.}
+ \item{\code{as(object, "multiPhylo4")}}{ ~~Not implemented
+ yet. where object is of class \code{multiPhylo} and returns an
+ object of class \code{multiPhylo4}. }
}
- \item{\code{phylobase} to \code{ade4} formats:}{
- \describe{
- \item{\code{as(object, "phylog")}}{where object is of class \code{phylo4} and returns an object of class \linkS4class{phylog}.}
- }
+
+ \item{}{\code{phylobase} to \code{ade4} formats:}
+ \itemize{
+ \item{\code{as(object, "phylog")}}{where object is of class
+ \code{phylo4} and returns an object of class \linkS4class{phylog}.}
}
- \item{\code{phylobase} format to \code{data.frame}:}{
- \describe{
- \item{\code{as(object, "data.frame")}}{where object is of class \code{phylo4} or \code{phylo4d} and returns an object of class \code{data.frame}, with data included in the case of \code{phylo4d}.}
- }
+
+ \item{}{\code{phylobase} format to \code{data.frame}:}
+ \itemize{
+ \item{\code{as(object, "data.frame")}}{where object is of class
+ \code{phylo4} or \code{phylo4d} and returns an object of class
+ \code{data.frame}, with data included in the case of
+ \code{phylo4d}.}
}
- }}
+ }
}
-\author{Ben Bolker, Thibaut Jombart \email{jombart at biomserv.univ-lyon1.fr}, Marguerite Butler, Steve Kembel}
-\seealso{ generic \code{\link[methods]{as}}, \code{\link{phylo4}}, \code{\link{phylo4d}}, \code{\link{extractTree}}, the original \code{\link[ade4]{phylog}} from the
- \code{ade4} package and \code{\link[ape]{as.phylo}} from the \code{ape} package.
+
+\author{Ben Bolker, Thibaut Jombart, Marguerite Butler, Steve Kembel}
+\seealso{ generic \code{\link[methods]{as}}, \code{\link{phylo4}},
+ \code{\link{phylo4d}}, \code{\link{extractTree}}, the original
+ \code{\link[ade4]{phylog}} from the \code{ade4} package and
+ \code{\link[ape]{as.phylo}} from the \code{ape} package.
}
+
+
\examples{
-
tree.owls <- read.tree(text="(((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3):6.3,Tyto_alba:13.5);")
## round trip conversion
-tree_in_phylo <- tree.owls # tree is a phylo object
+tree_in_phylo <- tree.owls # tree is a phylo object
(tree_in_phylo4 <- as(tree.owls,"phylo4")) # phylo converted to phylo4
identical(tree_in_phylo,as(tree_in_phylo4,"phylo"))
## test if phylo, and phlyo4 converted to phylo are identical
## (no, because of dimnames)
-as(tree_in_phylo4, "phylog") # conversion to phylog (ade4)
-as(tree_in_phylo4, "data.frame") # conversion to data.frame
-as(tree_in_phylo4, "phylo") # conversion to phylo (ape)
-as(tree_in_phylo4, "phylo4d") # conversion to phylo4d, but with data slots empty
+## Conversion to phylog (ade4)
+as(tree_in_phylo4, "phylog")
+
+## Conversion to data.frame
+as(tree_in_phylo4, "data.frame")
+
+## Conversion to phylo (ape)
+as(tree_in_phylo4, "phylo")
+
+## Conversion to phylo4d, (data slots empty)
+as(tree_in_phylo4, "phylo4d")
}
\keyword{methods}
\concept{phylo4 tree formats}
Modified: pkg/man/check.phylo4.Rd
===================================================================
--- pkg/man/check.phylo4.Rd 2009-08-24 03:34:40 UTC (rev 574)
+++ pkg/man/check.phylo4.Rd 2009-08-24 03:35:58 UTC (rev 575)
@@ -1,6 +1,7 @@
\name{checkPhylo4}
\alias{checkPhylo4}
\alias{checkTree}
+\alias{checkPhylo4Data}
\title{Validity checking for phylo4 objects}
\description{
Basic checks on the validity of S4 phylogenetic objects
@@ -10,9 +11,10 @@
checkTree(object,
warn=c("retic","singleton","multiroot"),
err=NULL)
+checkPhylo4Data(object)
}
\arguments{
- \item{object}{A prospective S4 object}
+ \item{object}{A prospective phylo4 or phylo4d object}
\item{warn}{a character vector listing phenomena to warn about:
current options are [\code{"poly"} (polytomies),
\code{"retic"} (reticulations),
@@ -24,9 +26,14 @@
}
\value{
As required by \code{\link[methods]{validObject}}, returns an
- error string (describing problems) or TRUE if everything is OK
+ error string (describing problems) or TRUE if everything is OK.
}
-\note{\code{checkPhylo4} is an (inflexible) wrapper for
+\note{
+
+ These functions are only intended to be called by other phylobase
+ functions.
+
+ \code{checkPhylo4} is an (inflexible) wrapper for
\code{checkTree}, which uses the default settings.
The rules for \code{phylo4} objects essentially follow
those for \code{phylo} objects from the \code{ape} package,
@@ -34,18 +41,32 @@
http://ape.mpl.ird.fr/misc/FormatTreeR_4Dec2006.pdf.
These are essentially that:
\itemize{
- \item if the tree has edge lengths defined, the number of edge lengths must match the number of edges;
+ \item if the tree has edge lengths defined, the number of edge
+ lengths must match the number of edges;
\item the number of tip labels must match the number of tips;
- \item in a tree with \code{ntips} tips and \code{nnodes} (total) nodes, nodes 1 to \code{ntips} must be tips
+ \item in a tree with \code{ntips} tips and \code{nnodes} (total)
+ nodes, nodes 1 to \code{ntips} must be tips
\item if the tree is rooted, the root must be node number
- \code{ntips+1} and the root node must be the first row of the edge matrix
+ \code{ntips+1} and the root node must be the first row of the edge
+ matrix
+ \item tip labels, node labels, edge labels, edge lengths must have
+ proper internal names (i.e. internal names that match the node
+ numbers they document)
+ \item tip and node labels must be unique
}
+
+ For \code{phylo4d} objects, \code{checkTree} also calls
+ \code{checkPhylo4Data} to check the validity of the data associated
+ with the tree. It ensures that (1) the data associated with the tree
+ have the correct dimensions, (2) that the row names for the data are
+ correct.
}
+
\seealso{
the \code{\link{phylo4}} constructor and \linkS4class{phylo4} class;
\code{\link{formatData}}, the \code{\link{phylo4d}} constructor and
the \linkS4class{phylo4d} class do checks for the data associated with trees.
See \code{\link{coerce-methods}} for translation functions.
}
-\author{Ben Bolker}
+\author{Ben Bolker, Steven Kembel, Francois Michonneau}
\keyword{misc}
Modified: pkg/man/check.phylo4d.Rd
===================================================================
--- pkg/man/check.phylo4d.Rd 2009-08-24 03:34:40 UTC (rev 574)
+++ pkg/man/check.phylo4d.Rd 2009-08-24 03:35:58 UTC (rev 575)
@@ -1,64 +1,76 @@
-\name{checkPhylo4d}
+\name{formatData}
\alias{formatData}
-\alias{checkPhylo4Data}
-\title{Data addition and validity checking for phylo4d objects}
+\title{Formatting data before attaching them to a phylo4 object}
+
\description{
Basic checks on the validity of S4 phylogenetic plus data objects
(i.e. \linkS4class{phylo4d} objects).
}
-\section{Methods}{
- \describe{
- \item{formatData}{\code{signature(phy="phylo4d")}}
- \item{checkPhylo4Data}{\code{signature(phy="phylo4d")}}
- }
- }
- \usage{
-formatData(phy, dt, type=c("tip", "internal", "all"),
- match.data=TRUE, rownamesAsLabels=FALSE,
- label.type=c("rownames", "column"),
- label.column=1, missing.data=c("fail", "warn", "OK"),
- extra.data=c("warn", "OK", "fail"))
-checkPhylo4Data(phy)
-
+\usage{
+ formatData(phy, dt, type=c("tip", "internal", "all"),
+ match.data=TRUE, rownamesAsLabels=FALSE,
+ label.type=c("rownames", "column"),
+ label.column=1, missing.data=c("fail", "warn", "OK"),
+ extra.data=c("warn", "OK", "fail"))
+}
-}
\arguments{
- \item{phy}{A phylo4 object}
- \item{dt}{a data frame or matrix}
+ \item{phy}{a valid \code{phylo4} object}
+ \item{dt}{a data frame or a vector}
\item{type}{type of data to attach}
- \item{match.data}{(logical) check data labels against tree labels?}
- \item{label.type}{character, "rownames" or "column": should
+ \item{match.data}{(logical) Are data labels matched against tree
+ labels?}
+ \item{label.type}{character, \code{rownames} or \code{column}: should
the labels be taken from the row names of \code{dt} or from
the \code{label.column} column of \code{dt}?}
\item{label.column}{if \code{label.type=="column"}, column specifier
- (number or name) of the column containing tip labels}
- \item{missing.data}{action to take if there are missing data/labels don't match}
- \item{extra.data}{action to take if there are extra data/labels don't match}
- \item{rownamesAsLabels}{(logical), in the case of number-like labels should the row
- names of the data provided be considered as labels (TRUE) or node numbers (FALSE and default)}
+ (number or name) of the column containing tip labels}
+ \item{missing.data}{action to take if there are missing data or if
+ there are data labels that don't match}
+ \item{extra.data}{action to take if there are extra data or if there
+ are labels that don't match}
+ \item{rownamesAsLabels}{(logical), in the case of number-like labels
+ should the row names of the data provided be considered as labels
+ (TRUE) or node numbers (FALSE and default)}
}
+
\value{
-By default, tip data names are used to attach the tip data to the tree, must be present, and must match the set of tree taxa exactly. By default node data names are not used to attach the data to the tree, and thus node data names are not required.
+ \code{formatData} returns a data frame having node numbers as row
+ names. The data frame is also formatted to have the correct dimension
+ given the \code{phylo4} object provided.
+}
+\details{
-}
-\details{
- \code{formatData} is an internal function that should not be called by the user. It
- formats properly the data provided by the
- user before being attached to a tree. The function (1) converts labels provided in the
- data into node numbers, (2) makes sure that the data are appropriately matched against
- tip or nodes, (3) checks for differences between data and tree, (4) creates a data frame
- with the correct dimensions given a tree. \code{formatData} returns a data frame.
+ \code{formatData} is an internal function that should not be called by
+ the user. It formats properly the data provided by the user before
+ being attached to a tree.
- \code{checkPhylo4Data} checks the validity of a \code{phylo4d} object. It ensures that
- (1) the data associated with the tree have the correct dimensions, (2) that the row
- names for the data are correct.
+ By default, data names are used to attach tip data to the
+ tree. In this case data names must be present and must match the set
+ of tip or internal nodes exactly. The matching process can be done
+ either by using \code{phylo4} labels (i.e. tip or node) or by using
+ node numbers. It is possible to provide both at the same time by using
+ the option \code{rownamesAsLabels=FALSE}.
+
+ \code{formatData} (1) converts labels provided in the data into node
+ numbers, (2) makes sure that the data are appropriately matched
+ against tip or nodes, (3) checks for differences between data and
+ tree, (4) creates a data frame with the correct dimensions given a
+ tree.
+
}
-\seealso{the \code{\link{phylo4d}} constructor, the \linkS4class{phylo4d} class. See also the \code{\link{checkPhylo4}}, the \code{\link{phylo4}} constructor and the \linkS4class{phylo4} class. See \code{\link{coerce-methods}} for translation functions.}
-\author{Steven Kembel \email{skembel at berkeley.edu}}
+
+\seealso{the \code{\link{phylo4d}} constructor, the
+ \linkS4class{phylo4d} class. See also the \code{\link{checkPhylo4}},
+ the \code{\link{phylo4}} constructor and the \linkS4class{phylo4}
+ class. See \code{\link{coerce-methods}} for translation functions.}
+
+\author{Francois Michonneau}
+
\examples{
require(ape) ## for rcoal
## generate a tree and some data
More information about the Phylobase-commits
mailing list