[Vegan-commits] r548 - pkg/man

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

Author: psolymos
Date: 2008-11-02 21:24:31 +0100 (Sun, 02 Nov 2008)
New Revision: 548

Modified:
   pkg/man/permatfull.Rd
Log:
quasiswapcount option is documented


Modified: pkg/man/permatfull.Rd
===================================================================
--- pkg/man/permatfull.Rd	2008-11-02 20:23:56 UTC (rev 547)
+++ pkg/man/permatfull.Rd	2008-11-02 20:24:31 UTC (rev 548)
@@ -21,8 +21,8 @@
 \usage{
 permatfull(m, fixedmar = "both", shuffle = "ind", reg = NULL, 
 hab = NULL, mtype = "count", times = 100)
-permatswap(m, reg = NULL, hab = NULL, mtype = "count", 
-method = "swap", times = 100, burnin = 10000, thin = 1000)
+permatswap(m, method = "quasiswap", reg = NULL, hab = NULL, 
+mtype = "count", times = 100, burnin = 10000, thin = 1000)
 \method{plot}{permat}(x, ylab="Bray-Curtis dissimilarity", 
 xlab="Runs", col=c(2,4), lty=c(1,2), plot=TRUE, text=TRUE, ...)
 \method{summary}{permat}(object, ...)
@@ -64,10 +64,10 @@
 For count data, a special swap algorithm ('swapcount') is implemented that results in permuted matrices with
 fixed marginals and matrix fill at the same time.
 
-The 'swapcount' algorithm tries to find 2x2 submatrices (identified by 2 random row and 2 random column indices), that
-can be swapped in order to leave column and row totals and fill unchanged. First, the algorithm finds the largest value
-in the submatrix that can be swapped ($d$) and whether in diagonal or antidiagonal way. Submatrices that contain values larger than zero in either diagonal or antidiagonal position can be swapped. Swap means that the values in diagonal or antidiagonal positions are decreased by $d$, while remaining cells are increased by $d$. A swap is made only if fill doesn't change.
+The 'quasiswapcount' algorithm (\code{method="quasiswap"} and \code{mtype="count"}) uses the same trick as Carsten Dorman's \code{swap.web} function in the package 'bipartite'. First, a random matrix is generated by the \code{\link{r2dtable}} function retaining row and column sums. Than the original matrix fill is reconstructed by sequential steps to increase or decrease matrix fill in the random matrix. These steps are based on swaping 2x2 submatrices (see 'swapcount' algorithm for details) to maintain row and column totals. This algorithm generates independent matrices in each step, so \code{burnin} and \code{thin} arguments are not considered. (At the moment this option is not implemented in C, thus quite slow.)
 
+The 'swapcount' algorithm (\code{method="swap"} and \code{mtype="count"}) tries to find 2x2 submatrices (identified by 2 random row and 2 random column indices), that can be swapped in order to leave column and row totals and fill unchanged. First, the algorithm finds the largest value in the submatrix that can be swapped ($d$) and whether in diagonal or antidiagonal way. Submatrices that contain values larger than zero in either diagonal or antidiagonal position can be swapped. Swap means that the values in diagonal or antidiagonal positions are decreased by $d$, while remaining cells are increased by $d$. A swap is made only if fill doesn't change. This algorithm is sequential, subsequent matrices are not independent, because swaps modify little if the matrix is large. In these cases many burnin steps and thinning is needed to get independent random matrices. This algorithm is implemented in C for speed, but large burmin and thin values can slow it down considerably.
+
 Constraints on row/colum sums, matrix fill, total sum and sums within
 strata can be checked by the \code{summary} method. \code{plot} method is for
 visually testing the randomness of the permuted matrices, especially for the
@@ -107,7 +107,7 @@
 \author{\enc{P\'eter S\'olymos}{Peter Solymos}, \email{solymos at ualberta.ca}; Jari Oksanen translated the original 'swapcount' algorithm for count data into C}
 
 \seealso{
-\code{\link{commsimulator}}, \code{\link{r2dtable}}, \code{\link{sample}}
+\code{\link{commsimulator}}, \code{\link{r2dtable}}, \code{\link{sample}}, \code{\link[bipartite]{swap.web}}
 }
 \examples{
 ## A simple artificial community data matrix.
@@ -120,7 +120,7 @@
 ## Using the swap algorithm to create a 
 ## list of permuted matrices, where
 ## row/columns sums and matrix fill are preserved:
-x1 <- permatswap(m, burnin = 1000, thin = 100)
+x1 <- permatswap(m, "swap", burnin = 1000, thin = 100)
 summary(x1)
 plot(x1)
 ## Unrestricted permutation retaining