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

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

Author: psolymos
Date: 2008-12-06 18:58:15 +0100 (Sat, 06 Dec 2008)
New Revision: 612

Modified:
   pkg/vegan/inst/ChangeLog
   pkg/vegan/man/permatfull.Rd
Log:
qusiswapcount effects documented


Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog	2008-12-06 17:39:22 UTC (rev 611)
+++ pkg/vegan/inst/ChangeLog	2008-12-06 17:58:15 UTC (rev 612)
@@ -4,6 +4,12 @@
 
 Version 1.16-6
 
+    * permatfull: Jari Oksanen made the C port for the quantitative
+    quasiswap algorithm. So the permat* null model family is now
+    can be used for a wide array of null model analyses and is
+    quick enough to make reliable testing. The permatswap function
+    and help page were modified accordingly.
+
 	* plot.rad: gained argument log = "y", allowing log = "xy" so that
 	Zipf model is a straight line, or log = "" with arithmetic
 	scales.  Not (yet) implemented for Lattice alternatives.

Modified: pkg/vegan/man/permatfull.Rd
===================================================================
--- pkg/vegan/man/permatfull.Rd	2008-12-06 17:39:22 UTC (rev 611)
+++ pkg/vegan/man/permatfull.Rd	2008-12-06 17:58:15 UTC (rev 612)
@@ -15,9 +15,7 @@
 community level simulations. Options for preserving characteristics of
 the original matrix (rows/columns sums, matrix fill) and
 restricted permutations (within strata based on spatial units, habitat
-classes or both) are discussed in the Details section. By using these functions,
-hypothesis testing can be separated from the null model generation, thus
-several tests might be applied on the same set of random matrices.  }
+classes or both) are discussed in the Details section.}
 
 \usage{
 permatfull(m, fixedmar = "both", shuffle = "ind", reg = NULL, 
@@ -69,14 +67,14 @@
 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 'quasiswapcount' algorithm (\code{method="quasiswap"} and \code{mtype="count"}) uses the same trick as Carsten Dormann's \code{\link[bipartite]{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 'quasiswapcount' algorithm (\code{method="quasiswap"} and \code{mtype="count"}) uses the same trick as Carsten Dormann's \code{\link[bipartite]{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. This is the default method, because this is not sequential (as 'swapcount' is) so independence of subsequent matrices does not have to be checked.
 
-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.
+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. Although this algorithm is implemented in C, 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
-swap algorithms. If there are any tendency in the graph, higher \code{burnin} and 
+sequential swap algorithms. If there are any tendency in the graph, higher \code{burnin} and 
 \code{thin} values can help.
 
 Unrestricted and restricted permutations: if both
@@ -85,9 +83,14 @@
 as is for restricted permutations. If both are given, interaction is
 used for restricted permutations. Each strata should contain at least 2 rows
 in order to perform randomization (in case of low row numbers, swap algorithms
-can be rather slow).
+can be rather slow). If the design given by \code{reg} and \code{hab} is not vell balanced
+(i.e. same number of observations within each stratum), permutad matrices may be biased
+because same constraints are forced on submatrices of different dimensions. This
+often means, that the munber of potential permutations will decrease with dimensions.
+So the more constraints we put, the less randomness can be expected.
 
-The function \code{permat.control} will be used to set up quantitative matrix permutations in other functions.
+The function \code{permat.control} is used to set up quantitative matrix permutations in other functions
+(e.g. \code{\link{oecosimu}} and \code{\link{adipart}}).
 }
 
 \value{
@@ -111,10 +114,11 @@
 Applied Statistics 30, 91-97.
 }
 
-\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}
+\author{\enc{P\'eter S\'olymos}{Peter Solymos}, \email{solymos at ualberta.ca} and Jari Oksanen}
 
 \seealso{
-\code{\link{commsimulator}}, \code{\link{r2dtable}}, \code{\link{sample}}, \code{\link[bipartite]{swap.web}}
+\code{\link{commsimulator}}, \code{\link{r2dtable}}, \code{\link{sample}}, \code{\link[bipartite]{swap.web},
+\code{\link{oecosimu}}, \code{\link{adipart}}}
 }
 \examples{
 ## A simple artificial community data matrix.