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

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

Author: jarioksa
Date: 2013-09-10 08:12:46 +0200 (Tue, 10 Sep 2013)
New Revision: 2611

Modified:
   pkg/vegan/R/simulate.rda.R
   pkg/vegan/man/simulate.rda.Rd
Log:
rename arg 'iid' to 'correlated' and document

Modified: pkg/vegan/R/simulate.rda.R
===================================================================
--- pkg/vegan/R/simulate.rda.R	2013-09-09 08:05:19 UTC (rev 2610)
+++ pkg/vegan/R/simulate.rda.R	2013-09-10 06:12:46 UTC (rev 2611)
@@ -1,9 +1,9 @@
 `simulate.rda` <-
     function(object, nsim = 1, seed = NULL, indx = NULL, rank = "full",
-             iid = TRUE, ...) 
+             correlated = FALSE, ...) 
 {
-    ## is.null(indx) && !iid requires MASS
-    if(is.null(indx) && !iid)
+    ## is.null(indx) && correlated requires MASS
+    if(is.null(indx) && correlated)
         require(MASS) || stop("simulate options require MASS package")
     ## Handle RNG: code directly from stats::simulate.lm
     if (!exists(".Random.seed", envir = .GlobalEnv, inherits = FALSE)) 
@@ -39,10 +39,10 @@
         ftd <- ftd + object$pCCA$Fit
     ## if(is.null(indx)), we have parametric Gaussian simulation and
     ## need to generate sd matrices. The residuals sd is always taken
-    ## from the unconstrained (residual) component $CA$Xbar. If iid,
-    ## we need only species sd's, but if non-independent, we also need
-    ## species covariances.
-    if (iid)
+    ## from the unconstrained (residual) component $CA$Xbar. If
+    ## species are uncorrelated, we need only species sd's, but if
+    ## correlated, we also need species covariances.
+    if (!correlated)
         dev <- outer(rep(1, nrow(ftd)), apply(object$CA$Xbar, 2, sd))
     else
         dev <- cov(object$CA$Xbar)
@@ -51,7 +51,7 @@
     for (i in seq_len(nsim)) {
         if (!is.null(indx))
             ans[,,i] <- as.matrix(ftd + object$CA$Xbar[indx[i,],])
-        else if (iid)
+        else if (!correlated)
             ans[,,i] <- as.matrix(ftd + matrix(rnorm(length(ftd), sd = dev),
                                                nrow = nrow(ftd)))
         else {

Modified: pkg/vegan/man/simulate.rda.Rd
===================================================================
--- pkg/vegan/man/simulate.rda.Rd	2013-09-09 08:05:19 UTC (rev 2610)
+++ pkg/vegan/man/simulate.rda.Rd	2013-09-10 06:12:46 UTC (rev 2611)
@@ -13,7 +13,7 @@
 
 \usage{
 \method{simulate}{rda}(object, nsim = 1, seed = NULL, indx = NULL,
-    rank = "full", iid = TRUE, ...)
+    rank = "full", correlated = FALSE, ...)
 }
 \arguments{
 
@@ -42,27 +42,31 @@
   \item{rank}{The rank of the constrained component: passed to
     \code{\link{predict.rda}} or \code{\link{predict.cca}}. }
 
-  \item{iid}{Not yet documented (and implementation untested).}
+  \item{correlated}{Are species regarded as correlated in parametric
+    simulation or when \code{indx} is not given? If
+    \code{correlated = TRUE}, multivariate Gaussian random error is
+    generated, and if \code{FALSE}, Gaussian random error is
+    generated separately for each species. }
 
   \item{\dots}{additional optional arguments (ignored). }
 }
 
 \details{ The implementation follows \code{"lm"} method of
-  \code{\link{simulate}}, and adds Gaussian (Normal) error to the
-  fitted values (\code{\link{fitted.rda}}) using function
-  \code{\link{rnorm}}. The standard deviations are estimated
-  independently for each species (column) from the residuals after
-  fitting the constraints. Alternatively, the function can take a
-  permutation index that is used to add permuted residuals
-  (unconstrained component) to the fitted values. Raw data are used in
-  \code{\link{rda}}. Internal Chi-square transformed data are used in
-  \code{\link{cca}} within the function, but the returned matrix is 
-  similar to the original input data. The simulation is performed on
-  internal metric scaling data in \code{\link{capscale}}, but the
-  function returns the Euclidean distances calculated from the simulated
-  data.  The simulation uses only the real components, and the imaginary
-  dimensions are ignored.
-}
+  \code{\link{simulate}}, and adds Gaussian (Normal) error to the fitted
+  values (\code{\link{fitted.rda}}) using function \code{\link{rnorm}}
+  if \code{correlated = FALSE} or \code{\link[MASS]{mvrnorm}} if
+  \code{correlated = TRUE}. The standard deviations (\code{\link{rnorm}})
+  or covariance matrices for species (\code{\link[MASS]{mvrnorm}}) are
+  estimated from the residuals after fitting the constraints.
+  Alternatively, the function can take a permutation index that is used
+  to add permuted residuals (unconstrained component) to the fitted
+  values. Raw data are used in \code{\link{rda}}. Internal Chi-square
+  transformed data are used in \code{\link{cca}} within the function,
+  but the returned matrix is similar to the original input data. The
+  simulation is performed on internal metric scaling data in
+  \code{\link{capscale}}, but the function returns the Euclidean
+  distances calculated from the simulated data.  The simulation uses
+  only the real components, and the imaginary dimensions are ignored.  }
 
 \value{ If \code{nsim = 1}, returns a matrix or dissimilarities (in
   \code{\link{capscale}}) with similar additional arguments on random
@@ -77,7 +81,8 @@
   \code{\link{lm}} objects, and \code{\link{simulate.nullmodel}} for
   community null model simulation. Functions \code{\link{fitted.rda}}
   and \code{\link{fitted.cca}} return fitted values without the error
-  component.  }
+  component. See \code{\link{rnorm}} and \code{\link[MASS]{mvrnorm}}
+  (\pkg{MASS} package) for simulating Gaussian random error. }
 
 \examples{
 data(dune)