[Phylobase-commits] r924 - pkg/man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Apr 9 21:57:41 CEST 2014
Author: francois
Date: 2014-04-09 21:57:40 +0200 (Wed, 09 Apr 2014)
New Revision: 924
Added:
pkg/man/MRCA.Rd
pkg/man/addData-methods.Rd
pkg/man/ancestors.Rd
pkg/man/checkPhylo4.Rd
pkg/man/edgeLength-methods.Rd
pkg/man/edges-accessors.Rd
pkg/man/extractTree.Rd
pkg/man/getNode-methods.Rd
pkg/man/labels-methods.Rd
pkg/man/nTips-methods.Rd
pkg/man/nodeId-methods.Rd
pkg/man/phylo4-methods.Rd
pkg/man/phylo4d-accessors.Rd
pkg/man/phylo4d-methods.Rd
pkg/man/print-methods.Rd
pkg/man/readNexus.Rd
pkg/man/root-methods.Rd
pkg/man/setAs-methods.Rd
pkg/man/shortestPath-methods.Rd
pkg/man/summary-methods.Rd
pkg/man/tdata-methods.Rd
pkg/man/treeStructure-methods.Rd
Removed:
pkg/man/addData.Rd
pkg/man/as-methods.Rd
pkg/man/check.phylo4.Rd
pkg/man/extract.tree.Rd
pkg/man/getNode.Rd
pkg/man/hasSingles.Rd
pkg/man/phylo4-accessors.Rd
pkg/man/phylo4-display.Rd
pkg/man/phylo4-labels.Rd
pkg/man/phylo4.Rd
pkg/man/phylo4d-display.Rd
pkg/man/phylo4d-hasData.Rd
pkg/man/phylo4d-nData.Rd
pkg/man/phylo4d.Rd
pkg/man/phylog.Rd
pkg/man/printphylo4.Rd
pkg/man/readNCL.Rd
pkg/man/tdata.Rd
pkg/man/treewalk.Rd
Modified:
pkg/man/formatData.Rd
pkg/man/geospiza.Rd
pkg/man/multiPhylo-class.Rd
pkg/man/owls4.Rd
pkg/man/pdata-class.Rd
pkg/man/pdata.Rd
pkg/man/phylo4-class.Rd
pkg/man/phylo4d-class.Rd
pkg/man/phyloXXYY.Rd
pkg/man/phylobase-package.Rd
pkg/man/phylobase.options.Rd
pkg/man/phylobubbles.Rd
pkg/man/phylomat-class.Rd
pkg/man/plotOneTree.Rd
pkg/man/reorder-methods.Rd
pkg/man/subset-methods.Rd
pkg/man/tip.data.plot.Rd
pkg/man/treePlot-methods.Rd
Log:
major re-organization of the docs with transition to roxygen
Added: pkg/man/MRCA.Rd
===================================================================
--- pkg/man/MRCA.Rd (rev 0)
+++ pkg/man/MRCA.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,48 @@
+\docType{methods}
+\name{MRCA}
+\alias{MRCA}
+\alias{MRCA,phylo-method}
+\alias{MRCA,phylo4-method}
+\title{MRCA}
+\usage{
+MRCA(phy, ...)
+
+\S4method{MRCA}{phylo4}(phy, ...)
+
+\S4method{MRCA}{phylo}(phy, ...)
+}
+\arguments{
+ \item{phy}{a phylogenetic tree in phylo4, phylo4d or
+ phylo format.}
+
+ \item{...}{a vector of nodes}
+}
+\value{
+the node corresponding to the most recent common ancestor
+}
+\description{
+Most Recent Common Ancestor (MRCA) of 2 or more nodes.
+}
+\details{
+Given some nodes (i.e., tips and/or internal), this
+function returns the node corresponding to the most recent
+common ancestor.
+
+If \code{phy} is a \code{phylo4} or \code{phylo4d} object,
+the nodes can contain both numeric or character values that
+will be used by \code{getNode} to retrieve the correct
+node. However, if \code{phy} is a \code{phylo} object, the
+nodes must be a numeric vector.
+
+With \code{phylo4} and \code{phylo4d} objects, if a single
+node is provided, it will be returned.
+}
+\examples{
+data(geospiza)
+ MRCA(geospiza, 1, 5)
+ MRCA(geospiza, "fortis", 11)
+ MRCA(geospiza, 2, 4, "fusca", 3)
+ geo <- as(geospiza, "phylo")
+ MRCA(geo, c(1,5))
+}
+
Added: pkg/man/addData-methods.Rd
===================================================================
--- pkg/man/addData-methods.Rd (rev 0)
+++ pkg/man/addData-methods.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,78 @@
+\docType{methods}
+\name{addData}
+\alias{addData}
+\alias{addData,phylo4-method}
+\alias{addData,phylo4d-method}
+\alias{addData-methods}
+\title{Adding data to a phylo4 or a phylo4d object}
+\usage{
+addData(x, ...)
+
+\S4method{addData}{phylo4d}(x, tip.data = NULL, node.data = NULL,
+ all.data = NULL, merge.data = TRUE, pos = c("after", "before"), ...)
+
+\S4method{addData}{phylo4}(x, tip.data = NULL, node.data = NULL,
+ all.data = NULL, merge.data = TRUE, pos = c("after", "before"), ...)
+}
+\arguments{
+ \item{x}{a phylo4 or a phylo4d object}
+
+ \item{tip.data}{a data frame (or object to be coerced to
+ one) containing only tip data}
+
+ \item{node.data}{a data frame (or object to be coerced to
+ one) containing only node data}
+
+ \item{all.data}{a data frame (or object to be coerced to
+ one) containing both tip and node data}
+
+ \item{merge.data}{if both \code{tip.data} and
+ \code{node.data} are provided, it determines whether
+ columns with common names will be merged together
+ (default TRUE). If FALSE, columns with common names will
+ be preserved separately, with ".tip" and ".node" appended
+ to the names. This argument has no effect if
+ \code{tip.data} and \code{node.data} have no column names
+ in common.}
+
+ \item{pos}{should the new data provided be bound
+ \code{before} or \code{after} the pre-existing data?}
+
+ \item{\dots}{additional arguments to be passed to
+ \link{formatData}}
+}
+\value{
+\code{addData} returns a \code{phylo4d} object.
+}
+\description{
+\code{addData} adds data to a \code{phylo4} (converting it
+in a \code{phylo4d} object) or to a \code{phylo4d} object
+}
+\details{
+Rules for matching data to tree nodes are identical to
+those used by the \code{\link{phylo4d}} constructor.
+
+If any column names in the original data are the same as
+columns in the new data, ".old" is appended to the former
+column names and ".new" is appended to the new column
+names.
+
+The option \code{pos} is ignored (silently) if \code{x} is
+a \code{phylo4} object. It is provided for compatibility
+reasons.
+}
+\examples{
+data(geospiza)
+ nDt <- data.frame(a=rnorm(nNodes(geospiza)), b=1:nNodes(geospiza),
+ row.names=nodeId(geospiza, "internal"))
+ t1 <- addData(geospiza, node.data=nDt)
+}
+\author{
+Francois Michonneau
+}
+\seealso{
+\code{\link{tdata}} for extracting or updating data and
+\code{\link{phylo4d}} constructor.
+}
+\keyword{methods}
+
Deleted: pkg/man/addData.Rd
===================================================================
--- pkg/man/addData.Rd 2014-04-09 19:54:17 UTC (rev 923)
+++ pkg/man/addData.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -1,61 +0,0 @@
-\name{addData}
-\alias{addData}
-\alias{addData-methods}
-\alias{addData,phylo4-method}
-\alias{addData,phylo4d-method}
-
-\title{Adding data to a phylo4 or a phylo4d object}
-\description{
- \code{addData} adds data to a \code{phylo4} (converting it in a
- \code{phylo4d} object) or to a \code{phylo4d} object
-}
-\usage{
-\S4method{addData}{phylo4}(x, tip.data, node.data, all.data,
- merge.data=TRUE, pos=c("after", "before"), \dots)
-\S4method{addData}{phylo4d}(x, tip.data, node.data, all.data,
- merge.data=TRUE, pos=c("after", "before"), \dots)
-}
-\arguments{
- \item{x}{a phylo4 or a phylo4d object}
- \item{tip.data}{a data frame (or object to be coerced to one)
- containing only tip data}
- \item{node.data}{a data frame (or object to be coerced to one)
- containing only node data}
- \item{all.data}{a data frame (or object to be coerced to one)
- containing both tip and node data}
- \item{merge.data}{if both \code{tip.data} and \code{node.data} are
- provided, it determines whether columns with common names will be
- merged together (default TRUE). If FALSE, columns with common names
- will be preserved separately, with ".tip" and ".node" appended to
- the names. This argument has no effect if \code{tip.data} and
- \code{node.data} have no column names in common.}
- \item{pos}{should the new data provided be bound \code{before} or
- \code{after} the pre-existing data?}
- \item{\dots}{additional arguments to be passed to \link{formatData}}
-}
-\value{
- \code{addData} returns a \code{phylo4d} object.
-}
-\details{
- Rules for matching data to tree nodes are identical to those used by
- the \code{\link{phylo4d}} constructor.
-
- If any column names in the original data are the same as columns in
- the new data, ".old" is appended to the former column names and ".new"
- is appended to the new column names.
-
- The option \code{pos} is ignored (silently) if \code{x} is a
- \code{phylo4} object. It is provided for compatibility reasons.
-}
-\seealso{
- \code{\link{tdata}} for extracting or updating data and
- \code{\link{phylo4d}} constructor.
-}
-\examples{
- data(geospiza)
- nDt <- data.frame(a=rnorm(nNodes(geospiza)), b=1:nNodes(geospiza),
- row.names=nodeId(geospiza, "internal"))
- t1 <- addData(geospiza, node.data=nDt)
-}
-\author{Francois Michonneau}
-\keyword{methods}
Added: pkg/man/ancestors.Rd
===================================================================
--- pkg/man/ancestors.Rd (rev 0)
+++ pkg/man/ancestors.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,109 @@
+\name{ancestor}
+\alias{ancestor}
+\alias{ancestors}
+\alias{children}
+\alias{descendants}
+\alias{siblings}
+\title{Tree traversal and utility functions}
+\usage{
+ancestor(phy, node)
+
+children(phy, node)
+
+descendants(phy, node, type = c("tips", "children", "all"))
+
+siblings(phy, node, include.self = FALSE)
+
+ancestors(phy, node, type = c("all", "parent", "ALL"))
+}
+\arguments{
+ \item{phy}{a \linkS4class{phylo4} object (or one
+ inheriting from \linkS4class{phylo4}, e.g. a
+ \linkS4class{phylo4d} object)}
+
+ \item{node}{either an integer corresponding to a node ID
+ number, or a character corresponding to a node label; for
+ \code{ancestors} and \code{descendants}, this may be a
+ vector of multiple node numbers or names}
+
+ \item{type}{(\code{ancestors}) specify whether to return
+ just direct ancestor ("parent"), all ancestor nodes
+ ("all"), or all ancestor nodes including self ("ALL");
+ (\code{descendants}) specify whether to return just
+ direct descendants ("children"), all extant descendants
+ ("tips"), or all descendant nodes ("all")}
+
+ \item{include.self}{whether to include self in list of
+ siblings}
+
+ \item{\dots}{a list of node numbers or names, or a vector
+ of node numbers or names}
+}
+\value{
+\describe{ \item{\code{ancestors}}{ return a named vector
+(or a list of such vectors in the case of multiple input
+nodes) of the ancestors and descendants of a node}
+
+\item{\code{descendants}}{ return a named vector (or a list
+of such vectors in the case of multiple input nodes) of the
+ancestors and descendants of a node}
+
+\item{\code{ancestor}}{ \code{ancestor} is analogous to
+\code{ancestors(\dots{}, type="parent")} (i.e. direct
+ancestor only), but returns a single concatenated vector in
+the case of multiple input nodes}
+
+\item{\code{children}}{is analogous to
+\code{descendants(\dots{}, type="children")} (i.e. direct
+descendants only), but is not currently intended to be used
+with multiple input nodes }
+
+\item{\code{siblings}}{ returns sibling nodes (children of
+the same parent)} }
+}
+\description{
+Functions for describing relationships among phylogenetic
+nodes (i.e. internal nodes or tips).
+}
+\details{
+\code{ancestors} and \code{descendants} can take
+\code{node} vectors of arbitrary length, returning a list
+of output vectors if the number of valid input nodes is
+greater than one. List element names are taken directly
+from the input node vector.
+
+If any supplied nodes are not found in the tree, the
+behavior currently varies across functions. \itemize{ \item
+Invalid nodes are automatically omitted by \code{ancestors}
+and \code{descendants}, with a warning.
+
+\item \code{ancestor} will return \code{NA} for any invalid
+nodes, with a warning.
+
+\item Both \code{children} and \code{siblings} will return
+an empty vector, again with a warning. }
+}
+\examples{
+data(geospiza)
+ nodeLabels(geospiza) <- LETTERS[1:nNodes(geospiza)]
+ plot(as(geospiza, "phylo4"), show.node.label=TRUE)
+ ancestor(geospiza, "E")
+ children(geospiza, "C")
+ descendants(geospiza, "D", type="tips")
+ descendants(geospiza, "D", type="all")
+ ancestors(geospiza, "D")
+ MRCA(geospiza, "conirostris", "difficilis", "fuliginosa")
+ MRCA(geospiza, "olivacea", "conirostris")
+
+ ## shortest path between 2 nodes
+ shortestPath(geospiza, "fortis", "fuliginosa")
+ shortestPath(geospiza, "F", "L")
+
+ ## branch length from a tip to the root
+ sumEdgeLength(geospiza, ancestors(geospiza, "fortis", type="ALL"))
+}
+\seealso{
+\code{\link[ape]{mrca}}, in the ape package, gives a list
+of all subtrees
+}
+
Deleted: pkg/man/as-methods.Rd
===================================================================
--- pkg/man/as-methods.Rd 2014-04-09 19:54:17 UTC (rev 923)
+++ pkg/man/as-methods.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -1,138 +0,0 @@
-\name{as}
-\docType{methods}
-\alias{as}
-\alias{as-method}
-\alias{as,phylo,phylo4-method}
-\alias{as,phylo,phylo4d-method}
-\alias{as,multiPhylo4,multiPhylo-method}
-\alias{as,multiPhylo,multiPhylo4-method}
-\alias{as,multiPhylo4d,multiPhylo-method}
-\alias{as,phylo4,phylo-method}
-\alias{as,phylo4d,phylo-method}
-\alias{as,phylo4,data.frame-method}
-\alias{as,phylo4d,data.frame-method}
-\alias{as,phylo4vcov,phylo4-method}
-\alias{as,phylo4,phylo4vcov-method}
-\alias{coerce-methods}
-\alias{coerce,phylo,phylo4-method}
-\alias{coerce,phylo,phylo4d-method}
-\alias{coerce,multiPhylo4,multiPhylo-method}
-\alias{coerce,multiPhylo,multiPhylo4-method}
-\alias{coerce,multiPhylo4d,multiPhylo-method}
-\alias{coerce,phylo4,phylo-method}
-\alias{coerce,phylo4d,phylo-method}
-\alias{coerce,phylo4,data.frame-method}
-\alias{coerce,phylo4d,data.frame-method}
-\alias{coerce,phylo4vcov,phylo4-method}
-\alias{coerce,phylo4,phylo4vcov-method}
-
-\title{Converting between phylo4/phylo4d and other phylogenetic tree formats}
-
-\section{Usage}{
-\code{as(object, class)}
-}
-
-\section{Arguments}{
-\describe{
- \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 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}, \emph{now deprecated}), and to
- \code{data.frame} representation.
-}
-
-\section{Methods}{
-
- 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}. 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.}
- }} %end phylobase to phylobase
-
- \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}. 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}.}
- }} % end phylobase to ape
-
- \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}. }
- }} % end ape to phylobase
-
- \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}.}
- }
- Note that this format is now deprecated; the \code{ade4} developers recommend that you use \code{adephylo} instead,
- which uses \code{phylo} and \code{phylo4} formats natively.
-} % end phylobase to ade4
-
- \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}.}
- }} % end phylobase to dataframe
- } % end main description
-} % end methods
-
-\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{
-trString <- "(((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3):6.3,Tyto_alba:13.5);"
-tree.owls <- ape::read.tree(text=trString)
-## round trip conversion
-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 phylo4 converted to phylo are identical
-## (no, because of dimnames)
-
-## 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}
-\concept{convert tree formats}
-\concept{conversion between tree formats}
Deleted: pkg/man/check.phylo4.Rd
===================================================================
--- pkg/man/check.phylo4.Rd 2014-04-09 19:54:17 UTC (rev 923)
+++ pkg/man/check.phylo4.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -1,67 +0,0 @@
-\name{checkPhylo4}
-\alias{checkPhylo4}
-\alias{checkTree}
-\alias{checkPhylo4Data}
-\title{Validity checking for phylo4 objects}
-\description{
- Basic checks on the validity of S4 phylogenetic objects
-}
-\usage{
-checkPhylo4(object)
-checkTree(object)
-checkPhylo4Data(object)
-}
-\arguments{
- \item{object}{A prospective phylo4 or phylo4d object}
-}
-\value{
- As required by \code{\link[methods]{validObject}}, returns an
- error string (describing problems) or TRUE if everything is OK.
-}
-\note{
-
- These functions are only intended to be called by other phylobase
- functions.
-
- \code{checkPhylo4} is an (inflexible) wrapper for
- \code{checkTree}.
- The rules for \code{phylo4} objects essentially follow
- those for \code{phylo} objects from the \code{ape} package,
- which are in turn defined in
- \url{http://ape.mpl.ird.fr/misc/FormatTreeR_28July2008.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 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 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
- \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
- }
-
- You can alter some of the default options by using the function
- \code{phylobase.options}.
-
- 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 and
- \code{\link{phylobase.options} to change some of the default options
- of the validator.}
-}
-\author{Ben Bolker, Steven Kembel, Francois Michonneau}
-\keyword{misc}
Added: pkg/man/checkPhylo4.Rd
===================================================================
--- pkg/man/checkPhylo4.Rd (rev 0)
+++ pkg/man/checkPhylo4.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,65 @@
+\name{checkPhylo4}
+\alias{checkPhylo4}
+\alias{checkPhylo4Data}
+\alias{checkTree}
+\title{Validity checking for phylo4 objects}
+\usage{
+checkPhylo4(object)
+}
+\arguments{
+ \item{object}{A prospective phylo4 or phylo4d object}
+}
+\value{
+As required by \code{\link[methods]{validObject}}, returns
+an error string (describing problems) or TRUE if everything
+is OK.
+}
+\description{
+Basic checks on the validity of S4 phylogenetic objects
+}
+\note{
+These functions are only intended to be called by other
+phylobase functions.
+
+\code{checkPhylo4} is an (inflexible) wrapper for
+\code{checkTree}. The rules for \code{phylo4} objects
+essentially follow those for \code{phylo} objects from the
+\code{ape} package, which are in turn defined in
+\url{http://ape.mpl.ird.fr/misc/FormatTreeR_28July2008.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 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 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 \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 }
+
+You can alter some of the default options by using the
+function \code{phylobase.options}.
+
+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.
+}
+\author{
+Ben Bolker, Steven Kembel, Francois Michonneau
+}
+\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 and
+\code{\link{phylobase.options} to change some of the
+default options of the validator.}
+}
+\keyword{misc}
+
Added: pkg/man/edgeLength-methods.Rd
===================================================================
--- pkg/man/edgeLength-methods.Rd (rev 0)
+++ pkg/man/edgeLength-methods.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,115 @@
+\docType{methods}
+\name{hasEdgeLength}
+\alias{depthTips}
+\alias{depthTips,phylo4-method}
+\alias{depthTips,phylo4-methods}
+\alias{edgeLength}
+\alias{edgeLength,phylo4-method}
+\alias{edgeLength<-}
+\alias{edgeLength<-,phylo4,ANY-method}
+\alias{edgeLength<-,phylo4-method}
+\alias{hasEdgeLength}
+\alias{hasEdgeLength,phylo4-method}
+\alias{isUltrametric}
+\alias{isUltrametric,phylo4-method}
+\alias{nodeDepth}
+\alias{nodeDepth,phylo4-method}
+\alias{sumEdgeLength}
+\alias{sumEdgeLength,phylo4-method}
+\title{edgeLength methods}
+\usage{
+hasEdgeLength(x)
+
+\S4method{hasEdgeLength}{phylo4}(x)
+
+edgeLength(x, ...)
+
+\S4method{edgeLength}{phylo4}(x, node)
+
+edgeLength(x, use.names = TRUE, ...) <- value
+
+depthTips(x)
+
+\S4method{depthTips}{phylo4}(x)
+
+nodeDepth(x, node)
+
+\S4method{nodeDepth}{phylo4}(x, node)
+
+sumEdgeLength(x, node)
+
+\S4method{sumEdgeLength}{phylo4}(x, node)
+
+isUltrametric(x, tol = .Machine$double.eps^0.5)
+
+\S4method{isUltrametric}{phylo4}(x, tol = .Machine$double.eps^0.5)
+}
+\arguments{
+ \item{x}{a \code{phylo4} or \code{phylo4d} object.}
+
+ \item{value}{a numeric vector indicating the new values
+ for the edge lengths}
+
+ \item{node}{optional numeric or character vector
+ indicating the nodes for which edge}
+
+ \item{use.names}{should the the name attributes of
+ \code{value} be used to match the length to a given
+ edge.}
+
+ \item{tol}{the tolerance to decide whether all the tips
+ have the same depth to test if the tree is ultrametric.
+ Default is \code{.Machine$double.eps^0.5}.}
+
+ \item{\dots}{optional arguments (none used at present).}
+}
+\value{
+\describe{
+
+\item{hasEdgeLength}{whether or not the object has edge
+lengths (logical)}
+
+\item{edgeLength}{a named vector of the edge length for the
+object}
+
+\item{nodeDepth}{a named vector indicating the
+\dQuote{depth} (the distance between the root and the tip)
+of each tip.}
+
+\item{isUltrametric}{whether or not the tree is ultrametric
+(all the tips are have the same depth (distance from the
+root) (logical)}
+
+\item{sumEdgeLength}{the sum of the edge lengths for a set
+of nodes (intended to be used with \code{ancestors} or
+\code{descendants})} }
+}
+\description{
+These functions give information about and allow
+replacement of edge lengths.
+}
+\details{
+The \code{edgeLength} function returns the edge length in
+the same order as the edges in the matrix.
+}
+\examples{
+data(geospiza)
+ hasEdgeLength(geospiza) # TRUE
+ topoGeo <- geospiza
+ edgeLength(topoGeo) <- NULL
+ hasEdgeLength(topoGeo) # FALSE
+
+ edgeLength(geospiza)[2] # use the position in vector
+ edgeLength(geospiza)["16-17"] # or the name of the edge
+ edgeLength(geospiza, 17) # or the descendant node of the edge
+
+ ## The same methods can be used to update an edge length
+ edgeLength(geospiza)[2] <- 0.33
+ edgeLength(geospiza)["16-17"] <- 0.34
+ edgeLength(geospiza, 17) <- 0.35
+}
+\seealso{
+\code{ancestors}, \code{descendants}, \code{.Machine} for
+more information about tolerance.
+}
+
Added: pkg/man/edges-accessors.Rd
===================================================================
--- pkg/man/edges-accessors.Rd (rev 0)
+++ pkg/man/edges-accessors.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,74 @@
+\docType{methods}
+\name{edges}
+\alias{edgeOrder}
+\alias{edgeOrder,phylo4-method}
+\alias{edges}
+\alias{edges,phylo4-method}
+\alias{internalEdges}
+\alias{internalEdges,phylo4-method}
+\alias{terminalEdges}
+\alias{terminalEdges,phylo4-method}
+\title{Edges accessors}
+\usage{
+edges(x, ...)
+
+\S4method{edges}{phylo4}(x, drop.root = FALSE)
+
+edgeOrder(x, ...)
+
+\S4method{edgeOrder}{phylo4}(x)
+
+internalEdges(x)
+
+\S4method{internalEdges}{phylo4}(x)
+
+terminalEdges(x)
+
+\S4method{terminalEdges}{phylo4}(x)
+}
+\arguments{
+ \item{x}{a \code{phylo4} or \code{phylo4d} object.}
+
+ \item{drop.root}{logical (default FALSE), should the edge
+ connecting the root be included in the edge matrix?}
+
+ \item{\dots}{Optional arguments used by specific methods.
+ (None used at present).}
+}
+\value{
+\describe{ \item{\code{edges}}{returns the edge matrix that
+represent the ancestor-descendant relationships among the
+nodes of the tree.}
+
+\item{\code{edgeOrder}}{returns the order in which the edge
+matrix is in.}
+
+\item{\code{internalEdges}}{returns a logical vector
+indicating internal edges (edges that connect an internal
+node to another). This vector is named with the
+\code{edgeId}}.
+
+\item{\code{terminalEdges}}{returns a logical vector
+indicating terminal edges (edges that connect an internal
+node to a tip). This vector is named with the \code{edgeId}
+}}
+}
+\description{
+Access or modify information about the edges.
+}
+\examples{
+data(geospiza)
+ edges(geospiza)
+ edgeOrder(geospiza)
+ geoPost <- reorder(geospiza, "postorder")
+ edgeOrder(geoPost)
+ ## with a binary tree this should always be true
+ identical(!terminalEdges(geospiza), internalEdges(geospiza))
+}
+\author{
+Ben Bolker, Francois Michonneau, Thibaut Jombart
+}
+\seealso{
+reorder, edgeId
+}
+
Deleted: pkg/man/extract.tree.Rd
===================================================================
--- pkg/man/extract.tree.Rd 2014-04-09 19:54:17 UTC (rev 923)
+++ pkg/man/extract.tree.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -1,28 +0,0 @@
-\name{extractTree}
-\alias{extractTree}
-\title{Get tree from tree+data object}
-\description{
- Extracts a \code{phylo4} tree object from a \code{phylo4d} tree+data object.
-}
-\usage{
-extractTree(from)
-}
-\arguments{
- \item{from}{ a \code{phylo4d} object, containing a phylogenetic tree plus associated phenotypic data. Created by the \code{phylo4d()} function. }
-}
-\details{
- \code{extractTree} extracts just the phylogeny from a tree+data object. The phylogeny contains the topology (how the nodes are linked together), the branch lengths (if any), and any tip and/or node labels. This may be useful for extracting a tree from a \code{phylo4d} object, and associating with another phenotypic dataset, or to convert the tree to another format.
-}
-\author{ Ben Bolker }
-\seealso{\code{\link{phylo4}}, \code{\link{phylo4d}}, \code{\link{coerce-methods}} for translation functions. }
-\examples{
-tree.phylo <- ape::read.tree(text = "((a,b),c);")
-tree <- as(tree.phylo, "phylo4")
-plot(tree)
-tip.data <- data.frame(size = c(1, 2, 3), row.names = c("a", "b", "c"))
-(treedata <- phylo4d(tree, tip.data))
-plot(treedata)
-(tree1 <- extractTree(treedata))
-plot(tree1)
-}
-\keyword{methods}
Added: pkg/man/extractTree.Rd
===================================================================
--- pkg/man/extractTree.Rd (rev 0)
+++ pkg/man/extractTree.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -0,0 +1,43 @@
+\name{extractTree}
+\alias{extractTree}
+\title{Get tree from tree+data object}
+\usage{
+extractTree(from)
+}
+\arguments{
+ \item{from}{a \code{phylo4d} object, containing a
+ phylogenetic tree plus associated phenotypic data.
+ Created by the \code{phylo4d()} function.}
+}
+\description{
+Extracts a \code{phylo4} tree object from a \code{phylo4d}
+tree+data object.
+}
+\details{
+\code{extractTree} extracts just the phylogeny from a
+tree+data object. The phylogeny contains the topology (how
+the nodes are linked together), the branch lengths (if
+any), and any tip and/or node labels. This may be useful
+for extracting a tree from a \code{phylo4d} object, and
+associating with another phenotypic dataset, or to convert
+the tree to another format.
+}
+\examples{
+tree.phylo <- ape::read.tree(text = "((a,b),c);")
+tree <- as(tree.phylo, "phylo4")
+plot(tree)
+tip.data <- data.frame(size = c(1, 2, 3), row.names = c("a", "b", "c"))
+(treedata <- phylo4d(tree, tip.data))
+plot(treedata)
+(tree1 <- extractTree(treedata))
+plot(tree1)
+}
+\author{
+Ben Bolker
+}
+\seealso{
+\code{\link{phylo4}}, \code{\link{phylo4d}},
+\code{\link{coerce-methods}} for translation functions.
+}
+\keyword{methods}
+
Modified: pkg/man/formatData.Rd
===================================================================
--- pkg/man/formatData.Rd 2014-04-09 19:54:17 UTC (rev 923)
+++ pkg/man/formatData.Rd 2014-04-09 19:57:40 UTC (rev 924)
@@ -1,84 +1,92 @@
\name{formatData}
\alias{formatData}
-
\title{Format data for use in phylo4d objects}
-
-\description{
- Associates data with tree nodes and applies consistent formatting
- rules.
-}
-
\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"), keep.all=TRUE)
+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"), keep.all = TRUE)
}
-
\arguments{
\item{phy}{a valid \code{phylo4} object}
+
\item{dt}{a data frame, matrix, vector, or factor}
+
\item{type}{type of data to attach}
- \item{match.data}{(logical) should the rownames of the data frame
- be used to be matched against tip and internal node identifiers? See
- details.}
- \item{rownamesAsLabels}{(logical), should the row names of the data
- provided be matched only to labels (TRUE), or should any number-like
- row names be matched to node numbers (FALSE and default)}
- \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 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{keep.all}{(logical), should the returned data have rows for all
- nodes (with NA values for internal rows when type='tip', and vice
- versa) (TRUE and default) or only rows corresponding to the type
- argument}
+
+ \item{match.data}{(logical) should the rownames of the
+ data frame be used to be matched against tip and internal
+ node identifiers? See details.}
+
+ \item{rownamesAsLabels}{(logical), should the row names
+ of the data provided be matched only to labels (TRUE), or
+ should any number-like row names be matched to node
+ numbers (FALSE and default)}
+
+ \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 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{keep.all}{(logical), should the returned data have
+ rows for all nodes (with NA values for internal rows when
+ type='tip', and vice versa) (TRUE and default) or only
+ rows corresponding to the type argument}
}
-
\value{
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/phylobase -r 924
More information about the Phylobase-commits
mailing list