[Phylobase-commits] r921 - pkg/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Apr 8 23:23:25 CEST 2014
Author: francois
Date: 2014-04-08 23:23:25 +0200 (Tue, 08 Apr 2014)
New Revision: 921
Modified:
pkg/R/pdata.R
pkg/R/phylo4d-class.R
pkg/R/phylobase-package.R
pkg/R/phylomats-class.R
pkg/R/readNCL.R
pkg/R/summary-methods.R
Log:
more cosmetic changes to roxygen doc
Modified: pkg/R/pdata.R
===================================================================
--- pkg/R/pdata.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/pdata.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -2,20 +2,20 @@
ptypes <- c("multitype","binary","continuous","DNA","RNA","aacid",
"other","unknown")
-#' Class "pdata"
-#'
-#' Data class for phylo4d objects
-#'
-#'
-#' @name pdata-class
-#' @aliases ptypes pdata-class [<-,pdata-method [,pdata-method
-#' [,pdata,ANY,ANY,ANY-method [[,pdata-method [[<-,pdata-method
-#' [[,pdata,ANY,ANY-method [[,pdata,ANY,missing-method
-#' @docType class
-#' @section Objects from the Class: Objects can be created by calls of the form
-#' \code{new("pdata", ...)}.
-#' @author Ben Bolker
-#' @keywords classes
+##' Class "pdata"
+##'
+##' Data class for phylo4d objects
+##'
+##'
+##' @name pdata-class
+##' @aliases ptypes pdata-class [<-,pdata-method [,pdata-method
+##' [,pdata,ANY,ANY,ANY-method [[,pdata-method [[<-,pdata-method
+##' [[,pdata,ANY,ANY-method [[,pdata,ANY,missing-method
+##' @docType class
+##' @section Objects from the Class: Objects can be created by calls of the form
+##' \code{new("pdata", ...)}.
+##' @author Ben Bolker
+##' @keywords classes
setClass("pdata", representation(data="data.frame",
type="factor",
comment="character",
@@ -26,23 +26,23 @@
## pdata constructor
-#' Constructor for pdata (phylogenetic data) class
-#'
-#' Combine data, type, comments, and metadata information to create a new pdata
-#' object, or check such an object for consistency
-#'
-#'
-#' @aliases pdata check_pdata
-#' @param data a data frame
-#' @param type a factor with levels as specified by \linkS4class{pdata}, the
-#' same length as \code{ncol(data)}
-#' @param comment a character vector, the same length as \code{ncol(data)}
-#' @param metadata an arbitrary list
-#' @param object an object of class \code{pdata}
-#' @return An object of class \code{pdata}
-#' @author Ben Bolker
-#' @seealso \linkS4class{pdata}
-#' @keywords misc
+##' Constructor for pdata (phylogenetic data) class
+##'
+##' Combine data, type, comments, and metadata information to create a new pdata
+##' object, or check such an object for consistency
+##'
+##'
+##' @aliases pdata check_pdata
+##' @param data a data frame
+##' @param type a factor with levels as specified by \linkS4class{pdata}, the
+##' same length as \code{ncol(data)}
+##' @param comment a character vector, the same length as \code{ncol(data)}
+##' @param metadata an arbitrary list
+##' @param object an object of class \code{pdata}
+##' @return An object of class \code{pdata}
+##' @author Ben Bolker
+##' @seealso \linkS4class{pdata}
+##' @keywords misc
pdata <- function(data,type,comment,metadata) {
nvar <- ncol(data)
if (missing(type)) {
Modified: pkg/R/phylo4d-class.R
===================================================================
--- pkg/R/phylo4d-class.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/phylo4d-class.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -1,32 +1,32 @@
###################################
## phylo4d class
## extend: phylo with data
-#' phylo4d class
-#'
-#' S4 class for phylogenetic tree and data.
-#'
-#'
-#' @name phylo4d-class
-#' @docType class
-#' @section Objects from the Class: Objects can be created from various trees
-#' and a data.frame using the constructor \code{phylo4d}, or using
-#' \code{new("phylo4d", \dots{})} for empty objects.
-#' @author Ben Bolker, Thibaut Jombart
-#' @seealso \code{\link{coerce-methods}} for translation functions. The
-#' \code{\link{phylo4d}} constructor and the \code{\link{formatData}} function
-#' to check the validity of trees and data. See also the \code{\link{phylo4}}
-#' constructor, the \linkS4class{phylo4} class, and the
-#' \code{\link{checkPhylo4}} function to check the validity of \code{phylo4}
-#' trees.
-#' @keywords classes
-#' @export
-#' @include phylo4-methods.R formatData.R
-#' @examples
-#' example(read.tree, "ape")
-#' obj <- phylo4d(as(tree.owls.bis,"phylo4"), data.frame(wing=1:3))
-#' obj
-#' names(obj)
-#' summary(obj)
+##' phylo4d class
+##'
+##' S4 class for phylogenetic tree and data.
+##'
+##'
+##' @name phylo4d-class
+##' @docType class
+##' @section Objects from the Class: Objects can be created from various trees
+##' and a data.frame using the constructor \code{phylo4d}, or using
+##' \code{new("phylo4d", \dots{})} for empty objects.
+##' @author Ben Bolker, Thibaut Jombart
+##' @seealso \code{\link{coerce-methods}} for translation functions. The
+##' \code{\link{phylo4d}} constructor and the \code{\link{formatData}} function
+##' to check the validity of trees and data. See also the \code{\link{phylo4}}
+##' constructor, the \linkS4class{phylo4} class, and the
+##' \code{\link{checkPhylo4}} function to check the validity of \code{phylo4}
+##' trees.
+##' @keywords classes
+##' @export
+##' @include phylo4-methods.R formatData.R
+##' @examples
+##' example(read.tree, "ape")
+##' obj <- phylo4d(as(tree.owls.bis,"phylo4"), data.frame(wing=1:3))
+##' obj
+##' names(obj)
+##' summary(obj)
setClass("phylo4d",
representation(data="data.frame",
metadata = "list"),
Modified: pkg/R/phylobase-package.R
===================================================================
--- pkg/R/phylobase-package.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/phylobase-package.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -1,132 +1,132 @@
-#' Utilities and Tools for Phylogenetics
-#'
-#' Base package for phylogenetic structures and comparative data.
-#'
-#' \code{phylobase} provides a set of functions to associate and
-#' manipulate phylogenetic information and data about the
-#' species/individuals that are in the tree.
-#'
-#' \code{phylobase} intends to be robust, fast and efficient. We hope
-#' other people use the data structure it provides to develop new
-#' comparative methods in R.
-#'
-#' With \code{phylobase} it is easy to ensure that all your data are
-#' represented and associated with the tips or the internal nodes of
-#' your tree. \code{phylobase} provides functions to:
-#' \itemize{
-#'
-#' \item prune (subset) your trees, find ancestor(s) a
-#' descendant(s)
-#'
-#' \item find the most common recent ancestor of 2 nodes (MRCA)
-#'
-#' \item calculate the distance of a given node from the tip or
-#' between two nodes in your tree
-#'
-#' \item robust functions to import data from NEXUS and Newick files
-#' using the NEXUS Class Library (\url{http://ncl.sourceforge.net/})
-#' }
-#'
-#' @section History:
-#' \code{phylobase} was started during a Hackathlon at NEScent on December 10-14 2007.
-#'
-#' Peter Cowan was a Google Summer of Code fellow in 2008 and
-#' developed all the code for plotting.
-#'
-#' In December 2008, a mini-virtual Hackathlon was organized to clean
-#' up and make the code more robust.
-#'
-#' In the spring and summer of 2009, Jim Regetz made several
-#' contributions that made the code faster (in particular with the
-#' re-ordering parts), found many bugs, and wrote most of the testing
-#' code.
-#'
-#' \code{phylobase} was first released on CRAN on November 1st, 2009
-#' with version 0.5.
-#'
-#' Since then, several releases have followed adding new
-#' functionalities: better support of NEXUS files, creation of
-#' \code{phylobase.options()} function that controls the \code{phylo4}
-#' validator, rewrite of the validator in C++.
-#'
-#' Starting with 0.6.8, Francois Michonneau succeeds to Ben Bolker as
-#' the maintainer of the package.
-#'
-#' @name phylobase-package
-#' @aliases phylobase-package phylobase
-#' @docType package
-#' @section More Info:
-#' See the help index \code{help(package="phylobase")} and run
-#' \code{vignette("phylobase", "phylobase")} for further details and
-#' examples about how to use \code{phylobase}.
-#' @keywords package
-#'
-#' @useDynLib phylobase
-#' @import methods
-#' @import ape
-#' @importFrom Rcpp evalCpp
-#' @importFrom graphics plot
-#' @importFrom stats reorder
-#' @importFrom utils head tail
-#' @importFrom ade4 newick2phylog
-#'
-#'
-#' @exportMethod print head tail reorder plot summary
-#' @exportMethod phylo4 phylo4d
-#' @exportMethod edges edgeId hasEdgeLength edgeLength edgeLength<- sumEdgeLength edgeOrder
-#' @exportMethod isRooted rootNode rootNode<-
-#' @exportMethod nodeId nodeType nodeDepth
-#' @exportMethod isUltrametric
-#' @exportMethod subset prune [
-#' @exportMethod [<- [[ [[<-
-#' @exportMethod labels labels<- nodeLabels nodeLabels<- tipLabels tipLabels<- edgeLabels edgeLabels<-
-#' @exportMethod hasNodeLabels hasEdgeLabels hasDuplicatedLabels
+##' Utilities and Tools for Phylogenetics
+##'
+##' Base package for phylogenetic structures and comparative data.
+##'
+##' \code{phylobase} provides a set of functions to associate and
+##' manipulate phylogenetic information and data about the
+##' species/individuals that are in the tree.
+##'
+##' \code{phylobase} intends to be robust, fast and efficient. We hope
+##' other people use the data structure it provides to develop new
+##' comparative methods in R.
+##'
+##' With \code{phylobase} it is easy to ensure that all your data are
+##' represented and associated with the tips or the internal nodes of
+##' your tree. \code{phylobase} provides functions to:
+##' \itemize{
+##'
+##' \item prune (subset) your trees, find ancestor(s) a
+##' descendant(s)
+##'
+##' \item find the most common recent ancestor of 2 nodes (MRCA)
+##'
+##' \item calculate the distance of a given node from the tip or
+##' between two nodes in your tree
+##'
+##' \item robust functions to import data from NEXUS and Newick files
+##' using the NEXUS Class Library (\url{http://ncl.sourceforge.net/})
+##' }
+##'
+##' @section History:
+##' \code{phylobase} was started during a Hackathlon at NEScent on December 10-14 2007.
+##'
+##' Peter Cowan was a Google Summer of Code fellow in 2008 and
+##' developed all the code for plotting.
+##'
+##' In December 2008, a mini-virtual Hackathlon was organized to clean
+##' up and make the code more robust.
+##'
+##' In the spring and summer of 2009, Jim Regetz made several
+##' contributions that made the code faster (in particular with the
+##' re-ordering parts), found many bugs, and wrote most of the testing
+##' code.
+##'
+##' \code{phylobase} was first released on CRAN on November 1st, 2009
+##' with version 0.5.
+##'
+##' Since then, several releases have followed adding new
+##' functionalities: better support of NEXUS files, creation of
+##' \code{phylobase.options()} function that controls the \code{phylo4}
+##' validator, rewrite of the validator in C++.
+##'
+##' Starting with 0.6.8, Francois Michonneau succeeds to Ben Bolker as
+##' the maintainer of the package.
+##'
+##' @name phylobase-package
+##' @aliases phylobase-package phylobase
+##' @docType package
+##' @section More Info:
+##' See the help index \code{help(package="phylobase")} and run
+##' \code{vignette("phylobase", "phylobase")} for further details and
+##' examples about how to use \code{phylobase}.
+##' @keywords package
+##'
+##' @useDynLib phylobase
+##' @import methods
+##' @import ape
+##' @importFrom Rcpp evalCpp
+##' @importFrom graphics plot
+##' @importFrom stats reorder
+##' @importFrom utils head tail
+##' @importFrom ade4 newick2phylog
+##'
+##'
+##' @exportMethod print head tail reorder plot summary
+##' @exportMethod phylo4 phylo4d
+##' @exportMethod edges edgeId hasEdgeLength edgeLength edgeLength<- sumEdgeLength edgeOrder
+##' @exportMethod isRooted rootNode rootNode<-
+##' @exportMethod nodeId nodeType nodeDepth
+##' @exportMethod isUltrametric
+##' @exportMethod subset prune [
+##' @exportMethod [<- [[ [[<-
+##' @exportMethod labels labels<- nodeLabels nodeLabels<- tipLabels tipLabels<- edgeLabels edgeLabels<-
+##' @exportMethod hasNodeLabels hasEdgeLabels hasDuplicatedLabels
NULL
-#' Data from Darwin's finches
-#'
-#' Phylogenetic tree and morphological data for Darwin's finches, in different
-#' formats
-#'
-#'
-#' @name geospiza
-#' @aliases geospiza geospiza_raw
-#' @docType data
-#' @format \code{geospiza} is a \code{phylo4d} object; \code{geospiza_raw} is a
-#' list containing \code{tree}, a \code{phylo} object (the tree), \code{data},
-#' and a data frame with the data (for showing examples of how to merge tree
-#' and data)
-#' @note Stolen from Luke Harmon's Geiger package, to avoid unnecessary
-#' dependencies
-#' @source Dolph Schluter via Luke Harmon
-#' @keywords datasets
-#' @examples
-#'
-#' data(geospiza)
-#' plot(geospiza)
-#'
+##' Data from Darwin's finches
+##'
+##' Phylogenetic tree and morphological data for Darwin's finches, in different
+##' formats
+##'
+##'
+##' @name geospiza
+##' @aliases geospiza geospiza_raw
+##' @docType data
+##' @format \code{geospiza} is a \code{phylo4d} object; \code{geospiza_raw} is a
+##' list containing \code{tree}, a \code{phylo} object (the tree), \code{data},
+##' and a data frame with the data (for showing examples of how to merge tree
+##' and data)
+##' @note Stolen from Luke Harmon's Geiger package, to avoid unnecessary
+##' dependencies
+##' @source Dolph Schluter via Luke Harmon
+##' @keywords datasets
+##' @examples
+##'
+##' data(geospiza)
+##' plot(geospiza)
+##'
NULL
-#' 'Owls' data from ape
-#'
-#' A tiny tree, for testing/example purposes, using one of the examples from
-#' the \code{ape} package
-#'
-#'
-#' @name owls4
-#' @docType data
-#' @format This is the standard 'owls' tree from the \code{ape} package, in
-#' \code{phylo4} format.
-#' @source From various examples in the \code{ape} package
-#' @keywords datasets
-#' @examples
-#'
-#' data(owls4)
-#' plot(owls4)
-#'
+##' 'Owls' data from ape
+##'
+##' A tiny tree, for testing/example purposes, using one of the examples from
+##' the \code{ape} package
+##'
+##'
+##' @name owls4
+##' @docType data
+##' @format This is the standard 'owls' tree from the \code{ape} package, in
+##' \code{phylo4} format.
+##' @source From various examples in the \code{ape} package
+##' @keywords datasets
+##' @examples
+##'
+##' data(owls4)
+##' plot(owls4)
+##'
NULL
Modified: pkg/R/phylomats-class.R
===================================================================
--- pkg/R/phylomats-class.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/phylomats-class.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -1,47 +1,48 @@
-#' matrix classes for phylobase
-#'
-#' Classes representing phylogenies as matrices
-#'
-#'
-#' @name phylomat-class
-#' @aliases phylo4vcov-class as_phylo4vcov
-#' @docType class
-#' @param from a \code{phylo4} object
-#' @param \dots optional arguments, to be passed to \code{vcov.phylo} in
-#' \code{ape} (the main useful option is \code{cor}, which can be set to
-#' \code{TRUE} to compute a correlation rather than a variance-covariance
-#' matrix)
-#' @section Objects from the Class: These are square matrices (with rows and
-#' columns corresponding to tips, and internal nodes implicit) with different
-#' meanings depending on the type (variance-covariance matrix, distance matrix,
-#' etc.).
-#' @author Ben Bolker
-#' @keywords classes
-#' @examples
-#'
-#' tree.owls <- ape::read.tree(text="(((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3):6.3,Tyto_alba:13.5);")
-#' o2 <- as(tree.owls,"phylo4")
-#' ov <- as(o2,"phylo4vcov")
-#' o3 <- as(ov,"phylo4")
-#' ## these are not completely identical, but are
-#' ## topologically identical ...
-#'
-#' ## edge matrices are in a different order:
-#' ## cf. edges(o2) and edges(o3)
-#' ## BUT the edge matrices are otherwise identical
-#' o2edges <- edges(o2)
-#' o3edges <- edges(o3)
-#' identical(o2edges[order(o2edges[,2]),],
-#' o3edges[order(o3edges[,2]),])
-#'
-#' ## There is left/right ambiguity here in the tree orders:
-#' ## in o2 the 5->6->7->1 lineage
-#' ## (terminating in Strix aluco)
-#' ## is first, in o3 the 5->6->3 lineage
-#' ## (terminating in Athene noctua) is first.
-#'
-#'
+##' matrix classes for phylobase
+##'
+##' Classes representing phylogenies as matrices
+##'
+##'
+##' @name phylomat-class
+##' @aliases phylo4vcov-class as_phylo4vcov
+##' @docType class
+##' @param from a \code{phylo4} object
+##' @param \dots optional arguments, to be passed to \code{vcov.phylo} in
+##' \code{ape} (the main useful option is \code{cor}, which can be set to
+##' \code{TRUE} to compute a correlation rather than a variance-covariance
+##' matrix)
+##' @section Objects from the Class: These are square matrices (with rows and
+##' columns corresponding to tips, and internal nodes implicit) with different
+##' meanings depending on the type (variance-covariance matrix, distance matrix,
+##' etc.).
+##' @author Ben Bolker
+##' @rdname phylomat-class
+##' @keywords classes
+##' @examples
+##'
+##' tree.owls <- ape::read.tree(text="(((Strix_aluco:4.2,Asio_otus:4.2):3.1,Athene_noctua:7.3):6.3,Tyto_alba:13.5);")
+##' o2 <- as(tree.owls,"phylo4")
+##' ov <- as(o2,"phylo4vcov")
+##' o3 <- as(ov,"phylo4")
+##' ## these are not completely identical, but are
+##' ## topologically identical ...
+##'
+##' ## edge matrices are in a different order:
+##' ## cf. edges(o2) and edges(o3)
+##' ## BUT the edge matrices are otherwise identical
+##' o2edges <- edges(o2)
+##' o3edges <- edges(o3)
+##' identical(o2edges[order(o2edges[,2]),],
+##' o3edges[order(o3edges[,2]),])
+##'
+##' ## There is left/right ambiguity here in the tree orders:
+##' ## in o2 the 5->6->7->1 lineage
+##' ## (terminating in Strix aluco)
+##' ## is first, in o3 the 5->6->3 lineage
+##' ## (terminating in Athene noctua) is first.
+##'
+##'
## define class for phylogenetic var-cov matrices
setClass("phylo4vcov",
representation("matrix",
@@ -57,11 +58,14 @@
edge.label=from at edge.label,
order=from at order)
}
+##' @rdname phylomat-class
+##' @aliases setAs,phylo,phylo4vcov-method
setAs("phylo4","phylo4vcov",
function(from,to) {
as_phylo4vcov(from)})
-## var-cov to phylo4
+##' @rdname phylomat-class
+##' @aliases setAs,phylo4vcov,phylo4-method
setAs("phylo4vcov","phylo4",
function(from,to) {
matrix2tree <- function(v,reorder=TRUE) {
Modified: pkg/R/readNCL.R
===================================================================
--- pkg/R/readNCL.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/readNCL.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -3,97 +3,97 @@
### - readNexus (wrapper for readNCL importing Nexus files)
### - readNewick (wrapper for readNCL importing Newick files)
-#' Create a phylo4, phylo4d or data.frame object from a Nexus or a Newick file
-#'
-#' \code{readNexus} reads a Nexus file and outputs a \code{phylo4} or
-#' \code{phylo4d} or \code{data.frame} object.
-#'
-#' \code{readNewick} reads a Newick file and outputs a \code{phylo4} or
-#' \code{phylo4d} object.
-#'
-#'
-#' \code{readNexus} extracts data held in a Nexus file, specifically from DATA,
-#' CHARACTER or TREES blocks present in the file. The \code{type} argument
-#' specifies which of these is returned: \describe{ \item{data}{will only
-#' return a \code{data.frame} of the contents of all DATA and CHARACTER
-#' blocks.} \item{tree}{will only return a \code{phylo4} object of the contents
-#' of the TREES block.} \item{all}{if only data or a tree are present in the
-#' file, this option will act as the options above, returning either a
-#' \code{data.frame} or a \code{phylo4} object respectively. If both are
-#' present then a \code{phylo4d} object is returned containing both.} } The
-#' function returns \code{NULL} if the \code{type} of data requested is not
-#' present in the file, or if neither data nor tree blocks are present.
-#'
-#' Depending on the context \code{readNexus} will call either the \code{phylo4}
-#' or \code{phylo4d} constructor. In addition with \code{type="all"}, the
-#' \code{phylo4d} constructor will be used if
-#' \code{check.node.labels="asdata"}.
-#'
-#' \code{readNewick} imports newick formatted tree files and will return a
-#' \code{phylo4} or a \code{phylo4d} object if the option
-#' \code{check.node.labels="asdata"} is invoked.
-#'
-#' For both \code{readNexus} and \code{readNewick}, the options for
-#' \code{check.node.labels} can take the values: \describe{ \item{keep}{the
-#' node labels of the trees will be passed as node labels in the \code{phylo4}
-#' object} \item{drop}{the node labels of the trees will be ignored in the
-#' \code{phylo4} object} \item{asdata}{the node labels will be passed as data
-#' and a \code{phylo4d} object will be returned.} } If you use the option
-#' \code{asdata} on a file with no node labels, a warning message is issued,
-#' and thus \code{check.node.labels} takes the value \code{drop}.
-#'
-#' For both \code{readNexus} and \code{readNewick}, additional arguments can be
-#' passed to the constructors such as \code{annote}, \code{missing.data} or
-#' \code{extra.data}. See the documentation of \link{phylo4-methods},
-#' \link{phylo4d} and \link{formatData} for the complete list of options.
-#'
-#' @name Import Nexus and Newick files
-#' @aliases readNexus readNCL readNewick
-#' @docType methods
-#' @param file a Nexus file for \code{readNexus} or a file that contains Newick
-#' formatted trees for \code{readNewick}
-#' @param simplify If there are multiple trees in the file, only the first one
-#' is returned if TRUE and a list of phylo4/phylo4d objects is returned if the
-#' file contains multiple trees.
-#' @param type Determines which type of objects to return, if present in the
-#' file (see Details).
-#' @param char.all If TRUE, returns all characters, even those excluded in the
-#' NEXUS file
-#' @param polymorphic.convert If TRUE, converts polymorphic characters to
-#' missing data
-#' @param levels.uniform If TRUE, uses the same levels for all characters
-#' @param quiet If FALSE the output of the NCL interface is printed. This is
-#' mainly for debugging purposes. This option can considerably slow down the
-#' process if the tree is big or there are many trees in the file.
-#' @param check.node.labels Determines how the node labels in the Nexus or
-#' Newick files should be treated in the phylo4 object, see Details for more
-#' information.
-#' @param return.labels Determines whether state names (if TRUE) or state codes
-#' should be returned.
-#' @param check.names logical. If \sQuote{TRUE} then the names of the
-#' characters from the NEXUS file are checked to ensure that they are
-#' syntactically valid variable names and are not duplicated. If necessary
-#' they are adjusted (by \sQuote{make.names}) so that they are.
-#' @param convert.edge.length logical. If \sQuote{TRUE} negative edge lengths
-#' are replaced with 0. At this time \code{phylobase} does not accept objects
-#' with negative branch lengths, this workaround allows to still use trees with
-#' negative branch lengths are an artifact of the method used to build the
-#' tree.
-#' @param \dots Additional arguments to be passed to phylo4 or phylo4d
-#' constructor (see Details)
-#' @return Depending on the value of \code{type} and the contents of the file,
-#' one of: a \code{data.frame}, a \linkS4class{phylo4} object, a
-#' \linkS4class{phylo4d} object or \code{NULL}. If several trees are included
-#' in the Nexus file and the option \code{simplify=FALSE} a list of
-#' \linkS4class{phylo4} or \linkS4class{phylo4d} objects is returned.
-#' @note Underscores in state labels (i.e. trait or taxon names) will be
-#' translated to spaces when read by NCL. Unless \code{check.names=FALSE},
-#' trait names will be converted to valid R names (see
-#' \code{\link{make.names}}) on input to R, so spaces will be translated to
-#' periods.
-#' @author Brian O'Meara, Francois Michonneau, Derrick Zwickl
-#' @seealso the \linkS4class{phylo4d} class, the \linkS4class{phylo4} class
-#' @keywords misc
+##' Create a phylo4, phylo4d or data.frame object from a Nexus or a Newick file
+##'
+##' \code{readNexus} reads a Nexus file and outputs a \code{phylo4} or
+##' \code{phylo4d} or \code{data.frame} object.
+##'
+##' \code{readNewick} reads a Newick file and outputs a \code{phylo4} or
+##' \code{phylo4d} object.
+##'
+##' \code{readNexus} extracts data held in a Nexus file, specifically from DATA,
+##' CHARACTER or TREES blocks present in the file. The \code{type} argument
+##' specifies which of these is returned: \describe{ \item{data}{will only
+##' return a \code{data.frame} of the contents of all DATA and CHARACTER
+##' blocks.} \item{tree}{will only return a \code{phylo4} object of the contents
+##' of the TREES block.} \item{all}{if only data or a tree are present in the
+##' file, this option will act as the options above, returning either a
+##' \code{data.frame} or a \code{phylo4} object respectively. If both are
+##' present then a \code{phylo4d} object is returned containing both.} } The
+##' function returns \code{NULL} if the \code{type} of data requested is not
+##' present in the file, or if neither data nor tree blocks are present.
+##'
+##' Depending on the context \code{readNexus} will call either the \code{phylo4}
+##' or \code{phylo4d} constructor. In addition with \code{type="all"}, the
+##' \code{phylo4d} constructor will be used if
+##' \code{check.node.labels="asdata"}.
+##'
+##' \code{readNewick} imports newick formatted tree files and will return a
+##' \code{phylo4} or a \code{phylo4d} object if the option
+##' \code{check.node.labels="asdata"} is invoked.
+##'
+##' For both \code{readNexus} and \code{readNewick}, the options for
+##' \code{check.node.labels} can take the values: \describe{ \item{keep}{the
+##' node labels of the trees will be passed as node labels in the \code{phylo4}
+##' object} \item{drop}{the node labels of the trees will be ignored in the
+##' \code{phylo4} object} \item{asdata}{the node labels will be passed as data
+##' and a \code{phylo4d} object will be returned.} } If you use the option
+##' \code{asdata} on a file with no node labels, a warning message is issued,
+##' and thus \code{check.node.labels} takes the value \code{drop}.
+##'
+##' For both \code{readNexus} and \code{readNewick}, additional arguments can be
+##' passed to the constructors such as \code{annote}, \code{missing.data} or
+##' \code{extra.data}. See the documentation of \link{phylo4-methods},
+##' \link{phylo4d} and \link{formatData} for the complete list of options.
+##'
+##' @name Import Nexus and Newick files
+##' @docType methods
+##' @param file a Nexus file for \code{readNexus} or a file that contains Newick
+##' formatted trees for \code{readNewick}
+##' @param simplify If there are multiple trees in the file, only the first one
+##' is returned if TRUE and a list of phylo4/phylo4d objects is returned if the
+##' file contains multiple trees.
+##' @param type Determines which type of objects to return, if present in the
+##' file (see Details).
+##' @param char.all If TRUE, returns all characters, even those excluded in the
+##' NEXUS file
+##' @param polymorphic.convert If TRUE, converts polymorphic characters to
+##' missing data
+##' @param levels.uniform If TRUE, uses the same levels for all characters
+##' @param quiet If FALSE the output of the NCL interface is printed. This is
+##' mainly for debugging purposes. This option can considerably slow down the
+##' process if the tree is big or there are many trees in the file.
+##' @param check.node.labels Determines how the node labels in the Nexus or
+##' Newick files should be treated in the phylo4 object, see Details for more
+##' information.
+##' @param return.labels Determines whether state names (if TRUE) or state codes
+##' should be returned.
+##' @param check.names logical. If \sQuote{TRUE} then the names of the
+##' characters from the NEXUS file are checked to ensure that they are
+##' syntactically valid variable names and are not duplicated. If necessary
+##' they are adjusted (by \sQuote{make.names}) so that they are.
+##' @param convert.edge.length logical. If \sQuote{TRUE} negative edge lengths
+##' are replaced with 0. At this time \code{phylobase} does not accept objects
+##' with negative branch lengths, this workaround allows to still use trees with
+##' negative branch lengths are an artifact of the method used to build the
+##' tree.
+##' @param \dots Additional arguments to be passed to phylo4 or phylo4d
+##' constructor (see Details)
+##' @return Depending on the value of \code{type} and the contents of the file,
+##' one of: a \code{data.frame}, a \linkS4class{phylo4} object, a
+##' \linkS4class{phylo4d} object or \code{NULL}. If several trees are included
+##' in the Nexus file and the option \code{simplify=FALSE} a list of
+##' \linkS4class{phylo4} or \linkS4class{phylo4d} objects is returned.
+##' @note Underscores in state labels (i.e. trait or taxon names) will be
+##' translated to spaces when read by NCL. Unless \code{check.names=FALSE},
+##' trait names will be converted to valid R names (see
+##' \code{\link{make.names}}) on input to R, so spaces will be translated to
+##' periods.
+##' @author Brian O'Meara, Francois Michonneau, Derrick Zwickl
+##' @seealso the \linkS4class{phylo4d} class, the \linkS4class{phylo4} class
+##' @export
+##' @rdname readNexus
+##' @keywords misc
readNCL <- function(file, simplify=FALSE, type=c("all", "tree", "data"),
char.all=FALSE, polymorphic.convert=TRUE,
levels.uniform=FALSE, quiet=TRUE,
@@ -318,6 +318,8 @@
toRet
}
+##' @rdname readNexus
+##' @aliases readNexus
readNexus <- function (file, simplify=FALSE, type=c("all", "tree", "data"),
char.all=FALSE, polymorphic.convert=TRUE,
levels.uniform=FALSE, quiet=TRUE,
@@ -332,6 +334,8 @@
check.names=check.names, convert.edge.length=convert.edge.length, ...))
}
+##' @rdname readNexus
+##' @aliases readNewick
readNewick <- function(file, simplify=FALSE, quiet=TRUE,
check.node.labels=c("keep", "drop", "asdata"),
convert.edge.length=FALSE, ...) {
Modified: pkg/R/summary-methods.R
===================================================================
--- pkg/R/summary-methods.R 2014-04-08 21:15:26 UTC (rev 920)
+++ pkg/R/summary-methods.R 2014-04-08 21:23:25 UTC (rev 921)
@@ -1,78 +1,78 @@
-#' Summary for phylo4/phylo4d objects
-#'
-#' Summary of information for the tree (\code{phylo4} only) and/or the
-#' associated data (\code{phylo4d}).
-#'
-#' @name summary-methods
-#' @docType methods
-#' @param object a phylo4d object
-#' @param quiet Should the summary be displayed on screen?
-#'
-#' @return The \code{nodeType} method returns named vector which has
-#' the type of node (internal, tip, root) for value, and the node number
-#' for name
-#'
-#' The \code{summary} method invisibly returns a list with the
-#' following components: \item{list("name")}{the name of the object}
-#'
-#' \item{list("nb.tips")}{the number of tips}
-#'
-#' \item{list("nb.nodes")}{the number of nodes}
-#'
-#' \item{list("mean.el")}{mean of edge lengths}
-#'
-#' \item{list("var.el")}{variance of edge lengths (estimate for population) }
-#'
-#' \item{list("sumry.el")}{summary (i.e. range and quartiles) of the
-#' edge lengths}
-#'
-#' \item{list("degree")}{(optional) type of polytomy for each node:
-#' \sQuote{node}, \sQuote{terminal} (all descendants are tips) or
-#' \sQuote{internal} (at least one descendant is an internal node);
-#' displayed only when there are polytomies}
-#'
-#' \item{list("sumry.tips")}{(optional) summary for the data
-#' associated with the tips}
-#'
-#' \item{list("sumry.nodes")}{(optional) summary for the data
-#' associated with the internal nodes}
-#'
-#' @author Ben Bolker, Thibaut Jombart, Francois Michonneau
-#' @seealso \code{\link{phylo4d}} constructor and
-#' \code{\linkS4class{phylo4d}} class.
-#' @keywords methods
-#' @include phylo4-methods.R
-#' @include phylo4d-methods.R
-#' @export
-#' @examples
-#' tOwls <- "(((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=tOwls)
-#' P1 <- as(tree.owls, "phylo4")
-#' P1
-#' summary(P1)
-#' nodeType(P1)
-#'
-#' ## summary of a polytomous tree
-#' E <- matrix(c(
-#' 8, 9,
-#' 9, 10,
-#' 10, 1,
-#' 10, 2,
-#' 9, 3,
-#' 9, 4,
-#' 8, 11,
-#' 11, 5,
-#' 11, 6,
-#' 11, 7,
-#' 0, 8), ncol=2, byrow=TRUE)
-#'
-#' P2 <- phylo4(E)
-#' nodeLabels(P2) <- as.character(nodeId(P2, "internal"))
-#' plot(P2, show.node.label=TRUE)
-#' sumryP2 <- summary(P2)
-#' sumryP2
-#'
+##' Summary for phylo4/phylo4d objects
+##'
+##' Summary of information for the tree (\code{phylo4} only) and/or the
+##' associated data (\code{phylo4d}).
+##'
+##' @name summary-methods
+##' @docType methods
+##' @param object a phylo4d object
+##' @param quiet Should the summary be displayed on screen?
+##'
+##' @return The \code{nodeType} method returns named vector which has
+##' the type of node (internal, tip, root) for value, and the node number
+##' for name
+##'
+##' The \code{summary} method invisibly returns a list with the
+##' following components: \item{list("name")}{the name of the object}
+##'
+##' \item{list("nb.tips")}{the number of tips}
+##'
+##' \item{list("nb.nodes")}{the number of nodes}
+##'
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/phylobase -r 921
More information about the Phylobase-commits
mailing list