[Phylobase-commits] r693 - in pkg: R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Oct 14 22:56:12 CEST 2009
Author: regetz
Date: 2009-10-14 22:56:12 +0200 (Wed, 14 Oct 2009)
New Revision: 693
Added:
pkg/man/getNode.Rd
Modified:
pkg/R/treewalk.R
pkg/man/treewalk.Rd
Log:
created new documentation for getNode, getEdge, nodeId, and edgeId;
changed argument 'phy' to 'x' in getNode and getEdge, for consistency
Modified: pkg/R/treewalk.R
===================================================================
--- pkg/R/treewalk.R 2009-10-14 20:20:26 UTC (rev 692)
+++ pkg/R/treewalk.R 2009-10-14 20:56:12 UTC (rev 693)
@@ -7,7 +7,7 @@
## x = n-nTips(phy)
## so: n = x+nTips(phy)
-getNode <- function(phy, node, type=c("all", "tip", "internal"),
+getNode <- function(x, node, type=c("all", "tip", "internal"),
missing=c("warn","OK","fail")) {
type <- match.arg(type)
@@ -15,27 +15,27 @@
## if missing node arg, get all nodes of specified type
if (missing(node)) {
- node <- nodeId(phy, type)
+ node <- nodeId(x, type)
}
## match node to tree
if (is.character(node)) {
- irval <- match(node, labels(phy, type))
+ irval <- match(node, labels(x, type))
} else if (is.numeric(node) && all(floor(node) == node, na.rm=TRUE)) {
- irval <- match(as.character(node), names(labels(phy, type)))
+ irval <- match(as.character(node), names(labels(x, type)))
} else {
stop("Node must be a vector of class \'integer\' or \'character\'.")
}
## node numbers
- rval <- names(labels(phy, type))[irval]
+ rval <- names(labels(x, type))[irval]
rval[node == 0] <- NA # root ancestor gets special treatment
rval[is.na(node)] <- NA # return NA for any NA_character_ inputs
rval <- as.integer(rval)
## node labels
- nmNd <- labels(phy, type)[irval]
+ nmNd <- labels(x, type)[irval]
names(rval) <- nmNd
names(rval)[rval == 0] <- "0" # root ancestor gets special treatment
@@ -162,7 +162,7 @@
}
## Correct behavior when the root is part of the nodes
- testNodes <- lapply(nodes, getNode, phy=phy)
+ testNodes <- lapply(nodes, getNode, x=phy)
## BMB: why lapply, not sapply?
lNodes <- unlist(testNodes)
if (any(is.na(lNodes)))
@@ -229,35 +229,35 @@
###########
# getEdge
###########
-getEdge <- function(phy, node, type=c("descendant", "ancestor"),
+getEdge <- function(x, node, type=c("descendant", "ancestor"),
missing=c("warn", "OK", "fail")) {
- if(!identical(class(phy), "phylo4")) phy <- as(phy, "phylo4")
+ if(!identical(class(x), "phylo4")) x <- as(x, "phylo4")
type <- match.arg(type)
missing <- match.arg(missing)
if (missing(node)) {
if (type=="descendant") {
- node <- nodeId(phy, "all")
+ node <- nodeId(x, "all")
} else if (type=="ancestor") {
- node <- nodeId(phy, "internal")
+ node <- nodeId(x, "internal")
}
}
- node.id <- getNode(phy, node, missing="OK")
+ node.id <- getNode(x, node, missing="OK")
- nd <- lapply(node.id, function(x) {
- if (is.na(x)) {
+ nd <- lapply(node.id, function(nid) {
+ if (is.na(nid)) {
res <- NA
} else {
res <- switch(type,
- descendant = edgeId(phy)[edges(phy)[,2] %in% x],
- ancestor = edgeId(phy)[edges(phy)[,1] %in% x])
+ descendant = edgeId(x)[edges(x)[,2] %in% nid],
+ ancestor = edgeId(x)[edges(x)[,1] %in% nid])
## hack to return NA for tip nodes when type='ancestor'
if(length(res)==0) res <- NA
- names(res) <- rep(x, length(res))
+ names(res) <- rep(nid, length(res))
}
- names(res) <- rep(x, length(res))
+ names(res) <- rep(nid, length(res))
res
})
Added: pkg/man/getNode.Rd
===================================================================
--- pkg/man/getNode.Rd (rev 0)
+++ pkg/man/getNode.Rd 2009-10-14 20:56:12 UTC (rev 693)
@@ -0,0 +1,97 @@
+\name{getNode}
+\alias{getNode}
+\alias{getEdge}
+\alias{nodeId}
+\alias{nodeId,phylo4-method}
+\alias{edgeId}
+\alias{edgeId,phylo4-method}
+\title{node and edge look-up functions}
+\description{
+ Functions for retrieving node and edge IDs (possibly with
+ corresponding labels) from a phylogenetic tree.
+}
+\usage{
+getNode(x, node, type=c("all", "tip", "internal"),
+ missing=c("warn","OK","fail"))
+nodeId(x, type=c("all", "tip", "internal", "root"))
+edgeId(x, type=c("all", "tip", "internal", "root"))
+getEdge(x, node, type=c("descendant", "ancestor"),
+ missing = c("warn", "OK", "fail"))
+}
+\arguments{
+ \item{x}{a \linkS4class{phylo4} object (or one inheriting from
+ \linkS4class{phylo4}, e.g. a \linkS4class{phylo4d} object)
+ }
+ \item{node}{either an integer vector corresponding to node ID numbers,
+ or a character vector corresponding to node labels; if missing, all
+ nodes appropriate to the specified type will be returned by
+ \code{getNode}, and all edges appropriate to the specified type will
+ be returned by \code{getEdge}.}
+ \item{type}{
+ (\code{getNode}) specify whether to return nodes matching "all" tree
+ nodes (default), only "tip" nodes, or only "internal" nodes;
+ (\code{nodeId, edgeId}) specify whether to return "all" tree
+ nodes, or only those corresponding to "tip", "internal", or "root"
+ nodes;
+ (\code{getEdge}) specify whether to look up edges based on their
+ descendant node ("descendant") or ancestral node ("ancestor")}
+ \item{missing}{what to do if some requested node IDs or names are not
+ in the tree: warn, do nothing, or stop with an error}
+}
+\details{
+ \code{getNode} and \code{getEdge} are primarily intended for looking
+ up the IDs either of nodes themselves or of edges associated
+ with those nodes. Note that they behave quite differently. With
+ \code{getNode}, any input nodes are looked up against tree nodes of
+ the specified type, and those that match are returned as numeric node
+ IDs with node labels (if they exist) as element names. With
+ \code{getEdge}, any input nodes are looked up against edge ends of the
+ specified type, and those that match are returned as character edge
+ IDs with the corresponding node ID as element names.
+
+ If \code{missing} is \dQuote{warn} or \dQuote{OK}, \code{NA} is
+ returned for any nodes that are unmatched for the specified type. This
+ can provide a mechanism for filtering a set of nodes or edges.
+
+ \code{nodeId} provides similar output to \code{getNode} in the case
+ when no node is supplied, but it is faster and returns an unnamed
+ vector of the numeric IDs of all nodes of the specified node type.
+ Similarly, \code{edgeId} simply returns an unnamed vector of the
+ character IDs of all edges for which the descendant node is of the
+ specified node type.
+}
+\value{
+ \item{\code{getNode}}{returns a named integer vector of node IDs,
+ in the order of input nodes if provided, otherwise in nodeId order}
+ \item{\code{getEdge}}{returns a named character vector of edge IDs,
+ in the order of input nodes if provide, otherwise in nodeId order}
+ \item{\code{nodeId}}{returns an unnamed integer vector of node IDs,
+ in ascending order}
+ \item{\code{getEdge}}{returns an unnamed character vector of edge IDs,
+ in edge matrix order}
+}
+\examples{
+ data(geospiza)
+ nodeLabels(geospiza) <- LETTERS[1:nNodes(geospiza)]
+ plot(as(geospiza, "phylo4"), show.node.label=TRUE)
+ getNode(geospiza, 18)
+ getNode(geospiza, "D")
+ getEdge(geospiza, "D")
+ getEdge(geospiza, "D", type="ancestor")
+
+ ## match nodes only to tip nodes, flagging invalid cases as NA
+ getNode(geospiza, c(1, 18, 999), type="tip", missing="OK")
+
+ ## get all edges that descend from internal nodes
+ getEdge(geospiza, type="ancestor")
+
+ ## identify an edge from its terminal node
+ getEdge(geospiza, c("olivacea", "B", "fortis"))
+ getNode(geospiza, c("olivacea", "B", "fortis"))
+ geospiza at edge[c(26, 1, 11),]
+
+ ## quickly get all tip node IDs and tip edge IDs
+ nodeId(geospiza, "tip")
+ edgeId(geospiza, "tip")
+}
+\keyword{misc}
Property changes on: pkg/man/getNode.Rd
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: pkg/man/treewalk.Rd
===================================================================
--- pkg/man/treewalk.Rd 2009-10-14 20:20:26 UTC (rev 692)
+++ pkg/man/treewalk.Rd 2009-10-14 20:56:12 UTC (rev 693)
@@ -5,22 +5,15 @@
\alias{ancestors}
\alias{siblings}
\alias{MRCA}
-\alias{getNode}
-\alias{getEdge}
\alias{shortestPath}
\alias{sumEdgeLength}
\alias{sumEdgeLength,phylo4-method}
-\alias{nodeId}
-\alias{nodeId,phylo4-method}
-\alias{edgeId}
-\alias{edgeId,phylo4-method}
\title{tree traversal and utility functions}
\description{
Functions for describing relationships among
phylogenetic nodes (i.e. internal nodes or tips).
}
\usage{
-getNode(phy,node,type=c("all","tip","internal"),missing=c("warn","OK","fail"))
ancestors(phy, node, type=c("all","parent","ALL"))
ancestor(phy, node)
siblings(phy,node,include.self=FALSE)
@@ -49,16 +42,8 @@
or a vector of node numbers or names}
\item{node1}{a node number (or name)}
\item{node2}{a node number (or name)}
- \item{missing}{what to do if some requested node IDs or names are not
- in the tree: warn, do nothing, or stop with an error}
}
\value{
- \item{\code{getNode}}{
- takes character strings corresponding to tip or node labels, or node numbers; it returns a named
- vector of node numbers}
- \item{\code{getEdge}}{
- takes character strings naming terminal node of edges, or the corresponding node numbers; it
- returns a named vector of edge numbers}
\item{\code{ancestors} and \code{descendants}}{
return named vectors of the ancestors and descendants of a node; \code{ancestor} is a synonym
for \code{ancestors(\dots, type="parent")} (i.e. direct ancestor only), while \code{children}
@@ -81,8 +66,6 @@
data(geospiza)
nodeLabels(geospiza) <- LETTERS[1:nNodes(geospiza)]
plot(as(geospiza,"phylo4"), show.node.label=TRUE)
- getNode(geospiza,18)
- getNode(geospiza,"D")
ancestor(geospiza,"E")
children(geospiza,"C")
descendants(geospiza,"D",type="tips")
@@ -95,10 +78,6 @@
shortestPath(geospiza, "fortis","fuliginosa")
shortestPath(geospiza, "F","L")
- ## identifying an edge from its terminal node
- getEdge(geospiza,c("olivacea","B","fortis"))
- getNode(geospiza, c("olivacea","B","fortis"))
- geospiza at edge[c(26,1,11),]
## FIXME
## if(require(ape)){ edgelabels() }
More information about the Phylobase-commits
mailing list