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

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

Author: jarioksa
Date: 2009-06-09 10:45:34 +0200 (Tue, 09 Jun 2009)
New Revision: 859

Modified:
   pkg/vegan/R/capscale.R
   pkg/vegan/R/ordiGetData.R
   pkg/vegan/inst/doc/FAQ-vegan.texi
   pkg/vegan/man/capscale.Rd
Log:
capscale can now do square root transform of dissimilarities to produce more metric indices

Modified: pkg/vegan/R/capscale.R
===================================================================
--- pkg/vegan/R/capscale.R	2009-06-09 08:08:59 UTC (rev 858)
+++ pkg/vegan/R/capscale.R	2009-06-09 08:45:34 UTC (rev 859)
@@ -1,6 +1,7 @@
 `capscale` <-
-    function (formula, data, distance = "euclidean", comm = NULL, 
-              add = FALSE, dfun = vegdist, metaMDSdist = FALSE, ...) 
+    function (formula, data, distance = "euclidean", sqrt.dist = FALSE,
+              comm = NULL, add = FALSE, dfun = vegdist,
+              metaMDSdist = FALSE, ...) 
 {
     EPS <- sqrt(.Machine$double.eps)
     if (!inherits(formula, "formula")) 
@@ -27,12 +28,16 @@
             X <- dfun(X, distance)
         }
     }
+    if (sqrt.dist)
+        X <- sqrt(X)
     inertia <- attr(X, "method")
     if (is.null(inertia))
         inertia <- "unknown"
     inertia <- paste(toupper(substr(inertia, 1, 1)), substr(inertia, 
                                                             2, 256), sep = "")
-    inertia <- paste("squared", inertia, "distance")
+    inertia <- paste(inertia, "distance")
+    if (!sqrt.dist)
+        inertia <- paste("squared", inertia)
     if (add) 
         inertia <- paste(inertia, "(euclidified)")
     k <- attr(X, "Size") - 1 

Modified: pkg/vegan/R/ordiGetData.R
===================================================================
--- pkg/vegan/R/ordiGetData.R	2009-06-09 08:08:59 UTC (rev 858)
+++ pkg/vegan/R/ordiGetData.R	2009-06-09 08:45:34 UTC (rev 859)
@@ -1,10 +1,10 @@
 `ordiGetData` <-
 function (call, env) 
 {
-    call$scale <- call$distance <- call$comm <- call$add <- NULL
+    call$scale <- call$distance <- call$comm <- call$add <-
+        call$sqrt.dist <- NULL
     call$na.action <- na.pass
     call[[2]] <- NULL
     call[[1]] <- as.name("model.frame")
     eval(call, env)
 }
-

Modified: pkg/vegan/inst/doc/FAQ-vegan.texi
===================================================================
--- pkg/vegan/inst/doc/FAQ-vegan.texi	2009-06-09 08:08:59 UTC (rev 858)
+++ pkg/vegan/inst/doc/FAQ-vegan.texi	2009-06-09 08:45:34 UTC (rev 859)
@@ -311,7 +311,6 @@
 * Can you analyse binary or cover class data?::  
 * Why dissimilarities in vegan differ from other sources?::  
 * Zero dissimilarities in isoMDS::  
-* Warnings of negative eigenvalues in capscale::  
 * Variance explained by ordination axes::  
 * Is it possible to have passive points in ordination?::  
 * Class variables and dummies::  
@@ -346,7 +345,7 @@
 Another reason may be that indices indeed are defined differently,
 because people use same names for different indices.
 
- at node Zero dissimilarities in isoMDS, Warnings of negative eigenvalues in capscale, Why dissimilarities in vegan differ from other sources?, Ordination
+ at node Zero dissimilarities in isoMDS, Variance explained by ordination axes, Why dissimilarities in vegan differ from other sources?, Ordination
 @section Zero dissimilarities in isoMDS
 
 You can use argument @code{zerodist = "add"} in @code{metaMDS} or
@@ -359,30 +358,7 @@
 zero dissimilarity, and you have to resort to the kluge (or work
 harder with your data).
 
- at node Warnings of negative eigenvalues in capscale, Variance explained by ordination axes, Zero dissimilarities in isoMDS, Ordination
- at section Warnings of negative eigenvalues in capscale
-
-Function @code{capscale} regularly and normally gives warnings of
-negative eigenvalues. These warnings are harmless, and @code{capscale}
-will ignore the axes with negative eigenvalues. The warnings are
-generated by underlying function @code{cmdscale} or metric
-multidimensional scaling (a.k.a. principal coordinates analysis), The
-metric MDS assumes that dissimilarities are metric, but most
-ecologically useful indices are semimetric. The warnings only concern
-the very last minor axes, and the axes with negative eigenvalues will
-be ignored in @code{capscale}. If the warnings are
-disturbing, you can use argument @code{add = TRUE} in @code{capscale}
-which implements ``correction method 2'' of Legendre & Legendre (1998,
-p. 434) in @code{cmdscale}.
-
-You can get a warning about negative eigenvalues also with metric
-indices if you have deficit rank data. This happens, for instance,
-when number of species (columns) is lower than number of sites (rows),
-or if some sites are linear combinations of other sites. You can find
-the rank of the data using, for instance, vegan function @code{rda}
-which is identical to @code{capscale} with Euclidean distance.
-
- at node Variance explained by ordination axes, Is it possible to have passive points in ordination?, Warnings of negative eigenvalues in capscale, Ordination
+ at node Variance explained by ordination axes, Is it possible to have passive points in ordination?, Zero dissimilarities in isoMDS, Ordination
 @section Variance explained by ordination axes.
 
 In general, vegan does not directly give any statistics on the

Modified: pkg/vegan/man/capscale.Rd
===================================================================
--- pkg/vegan/man/capscale.Rd	2009-06-09 08:08:59 UTC (rev 858)
+++ pkg/vegan/man/capscale.Rd	2009-06-09 08:45:34 UTC (rev 859)
@@ -19,8 +19,9 @@
   optionally using extended dissimilarities.
 }
 \usage{
-capscale(formula, data, distance = "euclidean", comm = NULL,
-         add = FALSE,  dfun = vegdist, metaMDSdist = FALSE, ...)
+capscale(formula, data, distance = "euclidean", sqrt.dist = FALSE,
+    comm = NULL, add = FALSE,  dfun = vegdist, metaMDSdist = FALSE,
+    ...)
 }
 
 \arguments{
@@ -43,6 +44,8 @@
   \item{distance}{Dissimilarity (or distance) index  in
     \code{\link{vegdist}} used if the LHS of the \code{formula} is a
     data frame instead of dissimilarity matrix. }
+  \item{sqrt.dist}{Take square roots of dissimilarities. See section
+  \code{Notes} below.}
   \item{comm}{ Community data frame which will be used for finding
     species scores when the LHS of the \code{formula} was a
     dissimilarity matrix. This is not used if the LHS is a data
@@ -157,22 +160,27 @@
   including negative ones. No ordination scores are given for negative
   eigenvalues.  If the negative eigenvalues are disturbing, you can use
   argument \code{add = TRUE} passed to \code{\link{cmdscale}}, or,
-  preferably, a distance measure that does not cause these warnings.  In
-  \code{\link{vegdist}}, \code{method = "jaccard"} gives such an index.
-  Alternatively, after square root transformation many indices do not
-  cause warnings.
-  
-  Function \code{\link{rda}} usually divides the ordination scores by
-  number of sites minus one. In this way, the inertia is variance
-  instead of sum of squares, and the eigenvalues sum up to
-  variance. Many dissimilarity measures are in the range 0 to 1, so they
-  have already made a similar division. If the largest original
+  preferably, a distance measure that does not cause these warnings.
+  Alternatively, after square root transformation of distances (argument
+  \code{sqrt.dist = TRUE}) many indices do not produce negative
+  eignevalues. 
+
+  The inertia is named after the dissimilarity index as defined in the
+  dissimilairty matrix, or as \code{unknown} distance if such an
+  information is missing.  Function \code{\link{rda}} usually divides
+  the ordination scores by number of sites minus one. In this way, the
+  inertia is variance instead of sum of squares, and the eigenvalues sum
+  up to variance. Many dissimilarity measures are in the range 0 to 1,
+  so they have already made a similar division. If the largest original
   dissimilarity is less than or equal to 4 (allowing for
   \code{\link{stepacross}}), this division is undone in \code{capscale}
-  and original dissimilarities are used. The inertia is named
-  \code{squared dissimilarity} (as defined in the dissimilarity matrix),
-  but keyword \code{mean} is added to the inertia in cases where
-  division was made, e.g. in Euclidean and Manhattan distances.
+  and original dissimilarities are used. Keyword \code{mean} is added to
+  the inertia in cases where division was made, e.g. in Euclidean and
+  Manhattan distances.  Inertia is based on squared index, and keyword
+  \code{squared} is added to the name of distance, unless data were
+  square root transformed (argument \code{sqrt.dist = TRUE}). If an
+  additive constant was used, keyword \code{euclidified} is added to the
+  the name of inertia (argument \code{add = TRUE}).
 }
 
 
@@ -182,11 +190,18 @@
 \examples{
 data(varespec)
 data(varechem)
+## Basic Analysis
 vare.cap <- capscale(varespec ~ N + P + K + Condition(Al), varechem,
                      dist="bray")
 vare.cap
 plot(vare.cap)
 anova(vare.cap)
+## Avoid negative eigenvalues with additive constant
+capscale(varespec ~ N + P + K + Condition(Al), varechem,
+                     dist="bray", add =TRUE)
+## Avoid negative eigenvalues wusing square roots of dissimilarities
+capscale(varespec ~ N + P + K + Condition(Al), varechem,
+                     dist = "bray", sqrt.dist= TRUE)
 ## Principal coordinates analysis with extended dissimilarities
 capscale(varespec ~ 1, dist="bray", metaMDS = TRUE)
 }