[Vegan-commits] r459 - pkg/man

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

Author: psolymos
Date: 2008-08-05 23:25:56 +0200 (Tue, 05 Aug 2008)
New Revision: 459

Modified:
   pkg/man/permat.Rd
Log:
permat documentation extended


Modified: pkg/man/permat.Rd
===================================================================
--- pkg/man/permat.Rd	2008-08-05 07:05:09 UTC (rev 458)
+++ pkg/man/permat.Rd	2008-08-05 21:25:56 UTC (rev 459)
@@ -6,15 +6,15 @@
 \alias{summary.permat}
 \alias{print.summary.permat}
 
-\title{Matrix Permutation Algorithms or Presence-Absence and Count Data}
+\title{Matrix Permutation Algorithms for Presence-Absence and Count Data}
 
 \description{ Individual (for count data) or incidence (for
 presence-absence data) based null models can be generated for
 community level simulations. Options for preserving characteristics of
-the original matrix (sum, number of incidences, rows/columns sums) and
+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. The testing of
-different hypothesis is separated from the null model generation, thus
+classes or both) are discussed in the Details section. By using these functions,
+hypothesis testing is separated from the null model generation, thus
 several tests can be applied on the same set of random matrices.  }
 
 \usage{
@@ -29,26 +29,50 @@
   \item{fixedmar}{character, stating which of the row/column sums should be preserved (\code{"none", "rows", "columns", "both"}).}
   \item{reg}{numeric vector or factor with length same as \code{nrow(m)} for grouping rows within strata (regions) for restricted permutations. Unique values or levels are used.}
   \item{hab}{numeric vector or factor with length same as \code{nrow(m)} for grouping rows within strata (habitat classes) for restricted permutations. Unique values or levels are used.}
-  \item{mtype}{matrix data type, either \code{"count"} for count data, or \code{"prab"} for presence-absence data.}
+  \item{mtype}{matrix data type, either \code{"count"} for count data, or \code{"prab"} for presence-absence type incidence data.}
   \item{times}{number of permuted matrices.}
   \item{method}{character for method used for the swap algorithm (\code{"swap"}, \code{"tswap"}, \code{"backtrack"}) as described for function \code{\link{commsimulator}}. If \code{mtype="count"} only \code{"swap"} is available.}
-  \item{burnin}{number of null communities discarded before proper analysis in sequential \code{"swap", "tswap"} methods.}
-  \item{thin}{number of discarded permuted matrices between two evaluations in sequential \code{"swap", "tswap"} methods.}
+  \item{burnin}{number of null communities discarded before proper analysis in sequential (\code{"swap", "tswap"}) methods.}
+  \item{thin}{number of discarded permuted matrices between two evaluations in sequential (\code{"swap", "tswap"}) methods.}
   \item{x, object}{object of class \code{"permat"}}
   \item{digits}{number of digits used for rounding.}
   \item{\dots}{other arguments passed to methods.}
 } 
 
 \details{
+The function \code{permatfull} is useful when matrix fill is allowed to vary, and matrix type is \code{count}.
+The \code{fixedmar} argument is used to set constraints for permutation.
+If \code{none} of the margins are fixed, cells are randomised within the matrix.
+If \code{rows} or \code{columns} are fixed, cells within rows or columns are randomised, respectively.
+If \code{both} margins are fixed, the \code{\link{r2dtable}} function is used that is based on
+Patefield's (1981) algorithm. For presence absence data, matrix fill is necessarily fixed, and \code{permatfull}
+is a wrapper for the function \code{\link{commsimulator}}. The \code{r00}, r0, c0, quasiswap}
+algorithms of \code{\link{commsimulator}} are used for \code{"none", "rows", "columns", "both"} values 
+of the \code{fixedmar} argument, respectively 
+
+The function \code{permatswap} is useful when matrix fill (i.e. the proportion of empty cells) should be kept constant.
+\code{permatswap} uses different kinds of swap algorithms, and row and columns sums are fixed in all cases.
+For presence-absence data, the \code{swap} and \code{tswap} methods of \code{\link{commsimulator}} can be used.
+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.
+
+!!! THIS HAS TO BE EXTENDED WITH SWAPCOUNT ALGORITHM'S DOCUMENTATION !!!
+
+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 prmuted matrices, especially for the
+swap methods. If there are any tendency in the graph, higher \code{burnin} and 
+\code{thin} values can help.
+
 Unrestricted and restricted permutations: if both
 \code{reg} and \code{hab} are \code{NULL}, functions perform
 unrestricted permutations. If either of the two is given, it is used
 as is for restricted permutations. If both are given, interaction is
-used for restricted permutations.
+used for restricted permutations. Each strata should contain at least 2 rows
+in order to perform randomization (in case of low row numbers, swap methods
+can be more slower).
+}
 
-Constraints on row/colum sums, matrix fill, total sum and sums within
-strata can be chacked by the \code{summary} method.  }
-
 \value{
 Functions \code{permatfull} and \code{permatswap} return an object of class \code{"permat"}.
   \item{call}{the function call.}
@@ -60,9 +84,13 @@
 Bray-Curtis dissimilarities calculated pairvise among original and
 permuted matrices, and check results of the constraints.  }
 
-\references{ Original references are given on help pages of the
-functions used internally, listed in section 'See Also'.  }
+\references{
+Original references for presence-absence swap methods are given on help page of \link{commsimulator}}.
 
+Patefield, W. M. (1981) Algorithm AS159. An efficient method of generating r x c tables with given row and column totals. 
+Applied Statistics 30, 91-97.
+}
+
 \author{Peter Solymos, \email{Solymos.Peter at aotk.szie.hu}; Jari Oksanen translated the original swap algorithm for count data into C}
 
 \seealso{