[Vegan-commits] r2142 - in pkg/vegan: R inst man

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

Author: jarioksa
Date: 2012-04-23 10:52:54 +0200 (Mon, 23 Apr 2012)
New Revision: 2142

Added:
   pkg/vegan/R/scoverage.R
Modified:
   pkg/vegan/inst/ChangeLog
   pkg/vegan/man/clamtest.Rd
   pkg/vegan/man/decostand.Rd
Log:
Merge branch 'master' into r-forge-svn-local

Added: pkg/vegan/R/scoverage.R
===================================================================
--- pkg/vegan/R/scoverage.R	                        (rev 0)
+++ pkg/vegan/R/scoverage.R	2012-04-23 08:52:54 UTC (rev 2142)
@@ -0,0 +1,14 @@
+scoverage <- function(x, coverage.limit = 10) {
+    x <- as.matrix(x)
+    n <- rowSums(x)
+    if (any(n <= 0))
+        stop("negative or zero row totals not allowed")
+    ## check if comm contains integer, especially for singletons
+    if (any(x[x>0] < 1))
+        warning("<1 non integer values detected: analysis might not be meaningful")
+    if (abs(sum(x) - sum(as.integer(x))) > 10^-6)
+        warning("non integer values detected")
+    C1 <- 1 - rowSums(x==1) / n
+    a <- decostand(x, "total")
+    ifelse(x < coverage.limit, a * C1, a)
+}

Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog	2012-04-23 08:19:12 UTC (rev 2141)
+++ pkg/vegan/inst/ChangeLog	2012-04-23 08:52:54 UTC (rev 2142)
@@ -4,10 +4,15 @@
 
 Version 2.1-14 (opened March 9, 2012)
 
+  * scoverage: new function for sample coverage based 
+  correction for calculation of relative frequencies in count
+  community matrices (Good 1953, Biometrika 40, 237--264).
+
   * clamtest: wrongly used frequencies instead of the counts
   when calculating sample coverage to test x < coverage.limit. 
   No detectable differences were produced when rerunning 
-  examples from Chazdon et al. 2011 and vegan help page.
+  examples from Chazdon et al. 2011 (Ecology, 92, 1332--1343)
+  and vegan help page.
 
 	* Opened a new version with the CRAN release of vegan 2.0-3 on
 	March 3, 2012.

Modified: pkg/vegan/man/clamtest.Rd
===================================================================
--- pkg/vegan/man/clamtest.Rd	2012-04-23 08:19:12 UTC (rev 2141)
+++ pkg/vegan/man/clamtest.Rd	2012-04-23 08:52:54 UTC (rev 2142)
@@ -27,8 +27,9 @@
 two unique values or levels.
 }
   \item{coverage.limit}{
-Integer, below this limit the sample coverage based correction
-is applied to rare species. Sample coverage is calculated separately 
+Integer, the sample coverage based correction 
+is applied to rare species with counts below this limit. 
+Sample coverage is calculated separately 
 for the two habitats. Sample relative abundances are used for species 
 with higher than or equal to \code{coverage.limit} total counts per habitat.
 }

Modified: pkg/vegan/man/decostand.Rd
===================================================================
--- pkg/vegan/man/decostand.Rd	2012-04-23 08:19:12 UTC (rev 2141)
+++ pkg/vegan/man/decostand.Rd	2012-04-23 08:52:54 UTC (rev 2142)
@@ -2,6 +2,7 @@
 \name{decostand}
 \alias{decostand}
 \alias{wisconsin}
+\alias{scoverage}
 
 \title{Standardization Methods for Community Ecology}
 \description{
@@ -12,6 +13,8 @@
 decostand(x, method, MARGIN, range.global, logbase = 2, na.rm=FALSE, ...)
 
 wisconsin(x)
+
+scoverage(x, coverage.limit = 10)
 }
 
 \arguments{
@@ -25,6 +28,8 @@
     \code{x}. }
   \item{logbase}{The logarithm base used in \code{method = "log"}.}
   \item{na.rm}{Ignore missing values in row or column standardizations.}
+  \item{coverage.limit}{Integer, the sample coverage based correction 
+    is applied to rare species with counts below this limit.}
   \item{\dots}{Other arguments to the function (ignored).}
 }
 \details{
@@ -81,22 +86,37 @@
   data. If there are empty sites or species (or constant with
   \code{method =  "range"}), many standardization will change these into
   \code{NaN}.  
+
+  \code{scoverage} calculates sample relative frequencies
+  (divide by row total, \code{method = "total"} in \code{decostand})
+  for species with abundances larger than or equal to \code{coverage.limit}.
+  The sample coverage based correction proposed by Turing (see Good 1953)
+  is calculated for species with abundances smaller than 
+  \code{coverage.limit}. The correction is based on the number of
+  singleton species in each row.
+  The function expects nonnegative integer values in the community matrix
+  with no empty rows.
 }
 \value{
   Returns the standardized data frame, and adds an attribute
   \code{"decostand"} giving the name of applied standardization
   \code{"method"}.
 }
-\author{Jari Oksanen and Etienne \enc{Laliberté}{Laliberte}
-  (\code{method = "log"}).}
+\author{Jari Oksanen, Etienne \enc{Laliberté}{Laliberte}
+  (\code{method = "log"}),
+  Peter Solymos (\code{scoverage}).}
 \note{Common transformations can be made with standard \R functions.}
 
 \references{ 
   
   Anderson, M.J., Ellingsen, K.E. & McArdle, B.H. (2006) Multivariate
   dispersion as a measure of beta diversity. \emph{Ecology Letters} 
-  \strong{9}, 683--693.
+  \strong{9}; 683--693.
 
+  Good, I. J. 1953. The population frequencies of species and the
+  estimation of population parameters. \emph{Biometrika}
+  \strong{40};237--264.
+
   Legendre, P. & Gallagher, E.D. (2001) Ecologically meaningful
   transformations for ordination of species data. \emph{Oecologia}
   \strong{129}; 271--280.
@@ -116,6 +136,9 @@
 ## Use wcmdscale for weighted analysis and identical results.
 sptrans <- decostand(varespec, "chi.square")
 plot(procrustes(rda(sptrans), cca(varespec)))
+
+data(mite)
+sptrans <- scoverage(mite)
 }
-\keyword{ multivariate}%-- one or more ...
+\keyword{ multivariate}
 \keyword{ manip }