[Ecopd-commits] r64 - in branches/single-tree: R man

[noreply at r-forge.r-project.org]

Author: regetz
Date: 2009-11-14 01:53:29 +0100 (Sat, 14 Nov 2009)
New Revision: 64

Modified:
   branches/single-tree/R/utilities.R
   branches/single-tree/man/abundance.Rd
Log:
enhanced abundance and presence functions, and updated documentation


Modified: branches/single-tree/R/utilities.R
===================================================================
--- branches/single-tree/R/utilities.R	2009-11-09 18:15:32 UTC (rev 63)
+++ branches/single-tree/R/utilities.R	2009-11-14 00:53:29 UTC (rev 64)
@@ -45,36 +45,46 @@
 }
 
 # abundance extractor
-abundance <- function(phy, comm) {
-  communities <- names(phy at metadata$comms)
-  if (missing(comm)) {
-    return(tipData(phy)[communities])
-  }
-  doNotExist <- !comm %in% communities
-  if (any(doNotExist)) {
-    stop("one or more communities not found in phy: ",
-      paste(comm[doNotExist], collapse=", "))
-  }
-  return(tipData(phy)[comm])
+abundance <- function(phy, comm, tip) {
+    communities <- names(phy at metadata$comms)
+    if (missing(comm)) {
+        comm <- communities
+    }
+    doNotExist <- !comm %in% communities
+    if (any(doNotExist)) {
+        stop("one or more communities not found in phy: ",
+            paste(comm[doNotExist], collapse=", "))
+    }
+    if (missing(tip)) {
+        tip <- tipLabels(phy)
+    } else {
+        tip <- getNode(phy, tip, type="tip", missing="warn")
+        tip <- names(tip)[!is.na(tip)]
+    }
+    return(tipData(phy)[tip, comm, drop=FALSE])
 }
 
 # abundance assignment function
 `abundance<-` <- function(phy, comm, tip, value) {
-  if (!is.atomic(comm) || length(comm)!=1) {
-    stop("comm must be a vector of length 1")
-  } else if (!comm %in% names(phy at metadata$comms)) {
-    stop(paste("community", comm, "not found in phy", sep=" "))
-  }
-  if (missing(tip)) tip <- tipLabels(phy)
-  tipData(phy)[tip, comm] <- value
-  return(phy)
+    if (!is.atomic(comm) || length(comm)!=1) {
+        stop("when replacing, comm must be a vector of length 1")
+    } else if (!comm %in% names(phy at metadata$comms)) {
+        stop(paste("community", comm, "not found in phy", sep=" "))
+    }
+    if (missing(tip)) {
+        tip <- tipLabels(phy)
+    } else {
+        tip <- names(getNode(phy, tip, type="tip", missing="fail"))
+    }
+    tipData(phy)[tip, comm] <- value
+    return(phy)
 }
 
-presence <- function(phy) {
-    N <- abundance(phy)
+presence <- function(phy, comm, tip, na.zero=FALSE) {
+    N <- abundance(phy, comm, tip)
     N[N > 0] <- 1
     N[N <= 0] <- 0
-    N[is.na(N)] <- 0
+    if (na.zero) N[is.na(N)] <- 0
     N
 }
 

Modified: branches/single-tree/man/abundance.Rd
===================================================================
--- branches/single-tree/man/abundance.Rd	2009-11-09 18:15:32 UTC (rev 63)
+++ branches/single-tree/man/abundance.Rd	2009-11-14 00:53:29 UTC (rev 64)
@@ -7,38 +7,52 @@
 tree.
 }
 \usage{
-  abundance(phy)
-  abundance(phy) <- value
+  abundance(phy, comm, tip, na.zero=TRUE)
+  presence(phy, comm, tip, na.zero=TRUE)
+  abundance(phy, comm, tip) <- value
 }
 \arguments{
-  \item{phy}{a \code{phylo4d} object}
-  \item{value}{Numeric vector of length equal to the number of tips in
-    the tree. Order should correspond to the output of nodeId(tree,
-    type="tip").}
+  \item{phy}{a \code{phylo4com} object}
+  \item{comm}{a vector of community labels; if missing, all communities
+    (not allowed in the replacement form)}
+  \item{tip}{a vector of tip labels or numeric node IDs; if missing, all
+    tips}
+  \item{na.zero}{logical. should NAs be treated as zero abundances?}
+  \item{value}{a numeric vector of abundance values}
 }
 \details{
-  Any missing abundances will be represented by \code{NA}, including the
-  case when abundance data are missing from the tree altogether. All
-  abundance values can be removed by using an assignment value of
-  \code{NULL}.
+  Any missing abundances will be represented by \code{NA}, unless
+  \code{na.zero} is true, in which case they will be treated as zero.
+  This is also true of the corresponding presence/absence matrix.
 
-  Note that in the assignment form, subscripting can be used to replace
-  particular abundance values; see examples.
+  The \code{tip} vector can either be character, in which case tip
+  labels are matched, or integer, in which case the numeric node IDs of
+  tips in the phylo4d tree will be matched. Users should not assume that
+  these integer values will correspond to row positions in the tipData
+  data frame, as this is an implementation detail that may change at any
+  time.
+
+  In the assignment form, \code{comm} must be a \emph{single} community
+  label; it is not possible to update the abundances of multiple
+  communities simultaneously. In contrast, \code{tip} can be a single
+  value, multiple values, or missing (in which case all tip abundances
+  will be replaced). If the \code{value} vector is shorter than the
+  number of tips, normal R recycling rules will apply.
 }
 \value{
-  For \code{abundance}, a named vector of the same length as tips of
-  tree. For \code{abundance<-}, the updated tree.
+  For \code{abundance} and \code{presence}, a data frame.
+  For \code{abundance<-}, the updated tree.
 }
 \author{Jim Regetz (regetz at nceas.ucsb.edu)}
 \examples{
   data(weeds)
-  abundance(weeds$A)
+  abundance(weeds)
+  abundance(weeds, "A")
 
-  ## modify one particular abundance value
-  abundance(weeds$A)["Centaurea_alba"] <- 10
-  abundance(weeds$A)
+  ## abundance replacement
+  abundance(weeds, "A", "Centaurea_alba") <- NA
+  abundance(weeds, "B", 2:5) <- c(0, 100, 0)
+  abundance(weeds, "C") <- 25
 
-  ## remove abundance data altogether
-  abundance(weeds$A) <- NULL
-  abundance(weeds$A)
+  presence(weeds, na.zero=TRUE)
 }