[Vegan-commits] r1862 - in pkg/vegan: . inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Sep 20 18:40:55 CEST 2011
Author: psolymos
Date: 2011-09-20 18:40:55 +0200 (Tue, 20 Sep 2011)
New Revision: 1862
Added:
pkg/vegan/man/commsim.Rd
pkg/vegan/man/nullmodel.Rd
Modified:
pkg/vegan/NAMESPACE
pkg/vegan/inst/ChangeLog
Log:
documenting new nullmodel functions
Modified: pkg/vegan/NAMESPACE
===================================================================
--- pkg/vegan/NAMESPACE 2011-09-20 16:40:28 UTC (rev 1861)
+++ pkg/vegan/NAMESPACE 2011-09-20 16:40:55 UTC (rev 1862)
@@ -6,15 +6,16 @@
export(CCorA, MOStest, RsquareAdj, SSarrhenius, SSgitay, SSgleason,
SSlomolino, adipart, adonis, anosim, beals, betadisper, betadiver,
bgdispersal, bioenv, bstick, cIndexKM, calibrate, capscale, cascadeKM,
-cca, commsimulator, contribdiv, clamtest, decorana, decostand, designdist,
+cca, commsimulator, contribdiv, clamtest, commsim,
+decorana, decostand, designdist,
coverscale, dispindmorisita, distconnected, diversity, downweight,
drarefy, eigengrad, eigenvals, envfit, estaccumR, estimateR, eventstar,
factorfit, fisherfit, fitspecaccum, goodness, hiersimu, humpfit,
indpower, inertcomp, initMDS, intersetcor, isomapdist, isomap,
linestack, mantel, meandist, metaMDSdist, metaMDSiter, metaMDSredist,
-MDSrotate, metaMDS, monoMDS, mrpp, msoplot, mso, multipart,
-nestedchecker, nesteddisc, nestedn0, nestednodf, nestedtemp, oecosimu,
-ordiR2step, ordiarrows, ordicloud, ordicluster,
+MDSrotate, metaMDS, monoMDS, mrpp, msoplot, mso, multipart, make.commsim,
+nestedchecker, nesteddisc, nestedn0, nestednodf, nestedtemp, nullmodel,
+oecosimu, ordiR2step, ordiarrows, ordicloud, ordicluster,
ordiellipse, ordigrid, ordihull, ordilabel, ordiplot3d,
ordiplot, ordipointlabel, ordiresids, ordirgl, ordisegments,
ordispider, ordisplom, ordistep, ordisurf, orditkplot, orditorp,
@@ -269,6 +270,7 @@
S3method(print, bioenv)
S3method(print, capscale)
S3method(print, cca)
+S3method(print, commsim)
S3method(print, decorana)
S3method(print, eigenvals)
S3method(print, envfit)
@@ -289,6 +291,7 @@
S3method(print, nestedn0)
S3method(print, nestednodf)
S3method(print, nestedtemp)
+S3method(print, nullmodel)
S3method(print, oecosimu)
S3method(print, permat)
S3method(print, permutest.betadisper)
@@ -301,6 +304,7 @@
S3method(print, radfit.frame)
S3method(print, radline)
S3method(print, specaccum)
+S3method(print, simmat)
S3method(print, summary.bioenv)
S3method(print, summary.cca)
S3method(print, summary.clamtest)
@@ -355,6 +359,7 @@
S3method(simulate, capscale)
S3method(simulate, cca)
S3method(simulate, rda)
+S3method(simulate, nullmodel)
# stressplot: vegan
S3method(stressplot, default)
S3method(stressplot, monoMDS)
@@ -388,6 +393,8 @@
S3method(text, procrustes)
# tolerance: vegan -- or analogue?? Gav?
S3method(tolerance, cca)
+# update: stats
+S3method(update, nullmodel)
# vif: car -- but not used as a S3method within vegan
# because of car definition: could be defined as exported 'vif' generic
# in vegan with namespace
Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog 2011-09-20 16:40:28 UTC (rev 1861)
+++ pkg/vegan/inst/ChangeLog 2011-09-20 16:40:55 UTC (rev 1862)
@@ -9,6 +9,28 @@
call should now be defined as as.integer() instead of old
as.double().
+ * New functions: commsim is used to define Null Model Algorithms
+ via a function that returns n x m x nsim array of permuted
+ matrices based on structural constraints. make.commsim
+ contains Null Model Algorithms already defined in vegan
+ from commsimulator and permat* functions (and some more).
+ The nullmodel function creates an environment, where statistics
+ of the input matrix are stored. The environment also stores
+ updated status of sequential algorithms and current number of
+ iterations. The update and simulate methods are used to
+ update the nullmodel (for sequential algorithms) or
+ simulate random matrices, respectively. The simulate
+ method returns the n x m nsim array (simmat class).
+ Efficiency gains are sometimes high (because marginal
+ statistics are calculate only once by nullmodel),
+ but not significant in most cases.
+ Most advanageously, this implementation
+ can unite the commsimulator and permat* branches
+ and can serve as basis for further extensions.
+ Current intent is to investigate how this low level
+ infrastructure can be used within oecosimu and permat*
+ functions without breaking current vegan functionality.
+
Version 2.1-0 (closed September 20, 2011)
* New major version opened with the release of vegan_2.0-0 on
Added: pkg/vegan/man/commsim.Rd
===================================================================
--- pkg/vegan/man/commsim.Rd (rev 0)
+++ pkg/vegan/man/commsim.Rd 2011-09-20 16:40:55 UTC (rev 1862)
@@ -0,0 +1,349 @@
+\encoding{UTF-8}
+\name{commsim}
+\alias{commsim}
+\alias{make.commsim}
+\alias{print.commsim}
+\title{
+Create a Object for Null Model Algorithms
+}
+\description{
+The \code{commsim} function can be used to feed Null Model algorithms into
+\code{\link{nullmodel}} analysis.
+The \code{make.commsim} function returns various predefined algorithm type
+(see Details).
+These functions represent low level interface for community null model
+infrastructure in \pkg{vegan} with the intent of extensibility,
+and less emphasis on direct use by users.
+}
+\usage{
+commsim(method, fun, binary, isSeq, mode)
+make.commsim(method)
+\method{print}{commsim}(x, ...)
+}
+\arguments{
+ \item{method}{
+Character, name of the algorithm.
+}
+ \item{fun}{
+A function. For possible arguments see Details.
+}
+ \item{binary}{
+Logical, if the algorithm applies to presence-abseence or count matrices.
+}
+ \item{isSeq}{
+Logical, if the algorthm is sequential (needs burnin).
+}
+ \item{mode}{
+Character, storage mode of community matrix, either
+\code{"integer"} or \code{"double"}.
+}
+ \item{x}{
+A \code{commsim} object.
+}
+ \item{\dots}{
+Additional arguments.
+}
+}
+\details{
+The function \code{fun} must take some of the
+following arguments:
+\itemize{
+ item{\code{x}: }{input matrix,}
+ item{\code{n}: }{number of permuted matrices in output,}
+ item{\code{nr}: }{number of rows,}
+ item{\code{nc}: }{number of columns,}
+ item{\code{rs}: }{vector of row sums,}
+ item{\code{cs}: }{vector of column sums,}
+ item{\code{rf}: }{vector of row frequencies (nonzero cells),}
+ item{\code{cf}: }{vector of column frequencies (nonzero cells),}
+ item{\code{s}: }{total sum of \code{x}}
+ item{\code{fill}: }{matrix fill,}
+ item{\code{thin}: }{thinning value for sequential algorithms,}
+ item{\code{...}: }{additional arguments.}
+}
+Autput must be an array of \code{dim(nr, nc, n)}.
+
+The following algorithms are currently predefined:
+\itemize{
+%% commsimulator
+ \item{\code{"r00"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This maintains the number of presences but fills
+ these anywhere so that neither species (column) nor
+ site (row) totals are preserved. See Wright et al. (1998) for review.}
+ \item{\code{"r0"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This maintains the site (row) frequencies,
+ fills presences anywhere on the row with no respect to
+ species (column) frequencies. See Wright et al. (1998) for review.}
+ \item{\code{"r1"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This maintains the site (row) frequencies,
+ uses column marginal frequencies as probabilities.
+ It tries to simulate original species frequencies,
+ but it is not strictly constrained. See Wright et al. (1998) for review.}
+ \item{\code{"r2"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This maintains the site (row) frequencies,
+ uses squared column sums as as probabilities.
+ It tries to simulate original species frequencies,
+ but it is not strictly constrained. See Wright et al. (1998) for review.}
+ \item{\code{"c0"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This method maintains species frequencies,
+ but does not honour site (row) frequencies (Jonsson 2001). }
+ \item{\code{"swap"}: }{sequential algorithm for binary matrices
+ described in the page of \code{\link{commsimulator}}.
+ This changes the matrix structure, but does not influence
+ marginal sums (Gotelli & Entsminger 2003).
+ This inspects 2 x 2 submatrices so long that a swap can be done.}
+ \item{\code{"tswap"}: }{sequential algorithm for binary matrices
+ described in the page of \code{\link{commsimulator}}.
+ Same as the \code{"swap"} algorithm, but it
+ is trying a fixed number of times and doing zero to
+ many swaps at one step (according th thin argument in later call,
+ see Examples). This approach was suggested by
+ \enc{Miklós}{Miklos} & Podani (2004) because they found that ordinary swap
+ may lead into biased sequences,
+ since some columns or rows may be more easily swapped.}
+ \item{\code{"quasiswap"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This method implements a
+ method where matrix is first filled honouring row and
+ column totals, but with integers that may be larger than one.
+ Then the method inspects random 2x2 matrices and performs a
+ quasiswap on them. Quasiswap is similar to ordinary swap,
+ but it also can reduce numbers above one to ones maintaining
+ marginal totals (\enc{Miklós}{Miklos} & Podani 2004). }
+ \item{\code{"backtracking"}: }{non-sequential algorithm for binary matrices described
+ in the page of \code{\link{commsimulator}}.
+ This method implements a filling method with constraints
+ both for row and column frequencies (Gotelli & Entsminger 2001).
+ The matrix is first filled randomly using row and column frequencies
+ as probabilities. Typically row and column sums are reached before
+ all incidences are filled in. After that begins "backtracking",
+ where some of the points are removed, and then filling is
+ started again, and this backtracking is done so may times that
+ all incidences will be filled into matrix.}
+%% permatswap
+ \item{\code{"swap_count"}: }{sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ This algorithm tries to find 2 x 2 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 (\eqn{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 \eqn{d}, while remaining cells
+ are increased by \eqn{d}. A swap is made only if fill doesn't change.
+ \bold{WARNING}: according to simulations,
+ this algorithm seems to be biased and non random,
+ thus its use should be avoided!}
+ \item{\code{"quasiswap_count"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ This algorithm uses the same trick as
+ Carsten Dormann's \code{\link[bipartite]{swap.web}}
+ function in the package \pkg{bipartite}. First, a
+ random matrix is generated by the \code{\link{r2dtable}}
+ function retaining row and column sums.
+ Then the original matrix fill is reconstructed by
+ sequential steps to increase or decrease matrix fill in
+ the random matrix. These steps are based on swapping 2 x 2
+ submatrices (see \code{"swap_count"} algorithm for details)
+ to maintain row and column totals. }
+ \item{\code{"swsh_samp"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix.}
+ \item{\code{"swsh_both"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix, individuals of the
+ nonzero cells are also shuffled.}
+ \item{\code{"swsh_samp_r"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix, separately for each rows.}
+ \item{\code{"swsh_samp_c"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix, separately for each columns.}
+ \item{\code{"swsh_both_r"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix, individuals of the
+ nonzero cells are also shuffled, separately for each rows.}
+ \item{\code{"swsh_both_c"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}}.
+ The algorithm is a hybrid algorithm.
+ First, it makes binary quasiswaps to keep row and column
+ incidences constant, then non-zero values are
+ modified by shuffling original nonzero samples among the new
+ nonzero cells of the binary matrix, individuals of the
+ nonzero cells are also shuffled, separately for each columns.}
+ \item{\code{"abuswap_r"}: }{sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}} (\code{"abuswap"}
+ algorithm with fixed row freqencies).
+ The algorithm produces matrices by swapping
+ 2 x 2 submatrices. Each step changes the the corresponding
+ column sums, but honours matrix fill, row sums,
+ and row/column frequencies,
+ as described in Hardy (2008; randomization scheme 2x).}
+ \item{\code{"abuswap_c"}: }{sequential algorithm for count matrices
+ described in the page of \code{\link{permatswap}} (\code{"abuswap"}
+ algorithm with fixed column freqencies).
+ The algorithm produces matrices by swapping
+ 2 x 2 submatrices. Each step changes the the corresponding
+ row sums, but honours matrix fill, column sums,
+ and row/column frequencies,
+ as described in Hardy (2008; randomization scheme 3x).}
+%% permatfull
+ \item{\code{"r2dtable"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{r2dtable}} and \code{\link{permatfull}}.
+ This algorithm keeps matrix sum and row/column sums constant.}
+ \item{\code{"r00_ind"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps total sum constant,
+ individuals are shullfed among cells of the matrix.}
+ \item{\code{"r0_ind"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps row sums constant,
+ individuals are shullfed among cells of each row of the matrix.}
+ \item{\code{"c0_ind"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps column sums constant,
+ individuals are shullfed among cells of each column of the matrix.}
+ \item{\code{"r00_samp"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps total sum constant,
+ cells of the matrix are shuffled.}
+ \item{\code{"r0_samp"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps row sums constant,
+ cells within each row are shuffled.}
+ \item{\code{"c0_samp"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps column sums constant,
+ cells within each columns are shuffled.}
+ \item{\code{"r00_both"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps total sum constant,
+ cells and individuals among cells of the matrix are shuffled.}
+ \item{\code{"r0_both"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps total sum constant,
+ cells and individuals among cells of each row are shuffled.}
+ \item{\code{"c0_both"}: }{non-sequential algorithm for count matrices
+ described in the page of \code{\link{permatfull}}.
+ This algorithm keeps total sum constant,
+ cells and individuals among cells of each column are shuffled.}
+}
+For structural constraints imposed by each algorithm, see Examples.
+}
+\value{
+An object of class \code{"commsim"} with elements
+corresponding to the arguments (\code{method}, \code{binary},
+\code{isSeq}, \code{fun}).
+
+IF the input of \code{make.comsimm} is a \code{commsim} object,
+it is returned without further evaluation. If this is not the case,
+the character \code{method} argument is matched agains
+predefined algorithm names. An error message is issued
+if none such is found.
+}
+\references{
+ Hardy, O. J. (2008)
+ Testing the spatial phylogenetic structure of local communities:
+ statistical performances of different null models
+ and test statistics on a locally neutral community.
+ \emph{Journal of Ecology} 96, 914--926.
+
+ Patefield, W. M. (1981) Algorithm AS159.
+ An efficient method of generating r x c tables with
+ given row and column totals.
+ \emph{Applied Statistics} 30, 91--97.
+
+ Gotelli, N.J. & Entsminger, N.J. (2001). Swap and fill algorithms in
+ null model analysis: rethinking the knight's tour. \emph{Oecologia}
+ 129, 281--291.
+
+ Gotelli, N.J. & Entsminger, N.J. (2003). Swap algorithms in null model
+ analysis. \emph{Ecology} 84, 532--535.
+
+ Jonsson, B.G. (2001) A null model for randomization tests of
+ nestedness in species assemblages. \emph{Oecologia} 127, 309--313.
+
+ \enc{Miklós}{Miklos}, I. & Podani, J. (2004). Randomization of presence-absence
+ matrices: comments and new algorithms. \emph{Ecology} 85, 86--92.
+
+ Wright, D.H., Patterson, B.D., Mikkelson, G.M., Cutler, A. & Atmar,
+ W. (1998). A comparative analysis of nested subset patterns of species
+ composition. \emph{Oecologia} 113, 1--20.
+}
+\author{
+Peter Solymos \email{solymos at ualberta.ca}
+}
+\seealso{
+\code{\link{commsimulator}}, \code{\link{permatfull}},
+\code{\link{permatswap}}, \code{\link{oecosimu}}.
+}
+\examples{
+## write the r00 algorithm
+f <- function(x, n, ...)
+ array(replicate(n, sample(x)), c(dim(x), n))
+(cs <- commsim("r00", fun=f, binary=TRUE,
+ isSeq=FALSE, mode="integer"))
+
+## retrieving the sequential swap algorithm
+make.commsim("swap")
+
+## structural constraints
+diagfun <- function(x, y) {
+ c(sum = sum(y) == sum(x),
+ fill = sum(y > 0) == sum(x > 0),
+ rowSums = all(rowSums(y) == rowSums(x)),
+ colSums = all(colSums(y) == colSums(x)),
+ rowFreq = all(rowSums(y > 0) == rowSums(x > 0)),
+ colFreq = all(colSums(y > 0) == colSums(x > 0)))
+}
+evalfun <- function(meth, x, n) {
+ m <- nullmodel(x, meth)
+ y <- simulate(m, nsim=n)
+ out <- rowMeans(sapply(1:dim(y)[3],
+ function(i) diagfun(attr(y, "data"), y[,,i])))
+ z <- as.numeric(c(attr(y, "binary"), attr(y, "isSeq")))
+ names(z) <- c("binary", "isSeq")
+ c(z, out)
+}
+x <- matrix(rbinom(10*12, 1, 0.5)*rpois(10*12, 3), 12, 10)
+a <- t(sapply(c("r00","r0","r1","r2","c0",
+ "swap","tswap","quasiswap","backtrack",
+ "r2dtable","swap_count","quasiswap_count",
+ "swsh_samp","swsh_both","abuswap_r","abuswap_c",
+ "swsh_samp_r","swsh_samp_c","swsh_both_r","swsh_both_c",
+ "r00_ind","r0_ind","c0_ind",
+ "r00_samp","r0_samp","c0_samp",
+ "r00_both","r0_both","c0_both"),
+ evalfun, x=x, n=10))
+print(as.table(ifelse(a==1,1,0)), zero.print = ".")
+}
+\keyword{ multivariate }
+\keyword{ datagen }
Added: pkg/vegan/man/nullmodel.Rd
===================================================================
--- pkg/vegan/man/nullmodel.Rd (rev 0)
+++ pkg/vegan/man/nullmodel.Rd 2011-09-20 16:40:55 UTC (rev 1862)
@@ -0,0 +1,168 @@
+\name{nullmodel}
+\alias{nullmodel}
+\alias{print.nullmodel}
+\alias{simulate.nullmodel}
+\alias{update.nullmodel}
+\alias{print.simmat}
+\title{
+Null Model and Simulation
+}
+\description{
+The \code{nullmodel} function creates an object,
+which can serve as a basis for Null Model simulation
+via the \code{\link{simulate}} method.
+\code{\link{update}} method updated the nullmodel
+object without sampling (effective for sequential algorithms).
+}
+\usage{
+nullmodel(x, method)
+\method{print}{nullmodel}(x, ...)
+\method{simulate}{nullmodel}(object, nsim = 1,
+seed = NULL, burnin = 0, thin = 1, ...)
+\method{update}{nullmodel}(object, nsim = 1,
+seed = NULL, ...)
+\method{print}{simmat}(x, ...)
+}
+\arguments{
+ \item{x}{
+A community matrix.
+}
+ \item{method}{
+Character, specifying one of the null model algorithms
+listed in the help page of \code{\link{commsim}}.
+It can be a user supplied object of class \code{commsim}.
+For the \code{print} method, it is an object to be printed.
+}
+ \item{object}{
+A \code{nullmodel} object returned by
+the function \code{nullmodel}.
+}
+ \item{nsim}{
+Number of simulated matrices to return.
+For the \code{update} method, it is the number of
+burnin steps made for sequential algorithms
+to update the status of the input model.
+}
+ \item{seed}{
+An object specifying if and how the random number
+generator should be initialized ("seeded").
+Either \code{NULL} or an integer that will be
+used in a call to \code{\link{set.seed}} before
+simulating the matrices.
+If set, the value is saved as the
+\code{"seed"} attribute of the returned value.
+The default, \code{NULL} will not change the
+random generator state, and return
+\code{\link{.Random.seed}} as the \code{"seed"}
+ attribute, see Value.
+}
+ \item{burnin}{
+Nonnegative integer, specifying the number of steps
+discarded befor starting simulation.
+Active only for sequential null model algorithms.
+Ignored for non-sequential null model algorithms.
+}
+ \item{thin}{
+Positive integer, number of simulation steps
+made between each returned matrix.
+Active only for sequential null model algorithms.
+Ignored for non-sequential null model algorithms.
+}
+ \item{\dots}{
+Additional arguments supplied to algorithms.
+}
+}
+\details{
+The purpose of the \code{nullmodel} function is to
+create an object, where all necessari statistics of the
+input matrix is calculated only once.
+This information is reused, but not recalculated
+in each step of the simulation process dome by
+the \code{simulate} method.
+
+The \code{simulate} method carries out the simulation,
+the simulated matrices are stored in an array.
+For sequential algorithms, the method updates the state
+of the input \code{nullmodel} object.
+Therefore, it is possible to make disgnostic
+tests of the returned \code{simmat} object,
+and make further simulations, or use
+increased thinning value if desired.
+
+The \code{update} method makes burnin steps in case
+of sequential algorithms to update the status of the
+input model without any attempt to return any matrices.
+For non-sequential algorithms the method does nothing.
+
+\code{update} is the preferred way of making burnin iterations
+without sampling. Alternatively, burnin can be done
+via the \code{simulate} method. For convergence
+diagnistics, it is recommended to use the
+\code{simulate} method without burnin.
+The input nullmodel object is updated, so further
+samples can be simulated if desired without having
+to start the process all over again. See Examples.
+}
+\value{
+The function code{nullmodel} returns an object of class \code{"nullmodel"}.
+It is a set of objects sharing the same environment:
+\itemize{
+ \item{\code{data}: }{original matrix in ineger mode.}
+ \item{\code{nrow}: }{number of rows.}
+ \item{\code{ncol}: }{number of columns.}
+ \item{\code{rowSums}: }{row sums.}
+ \item{\code{colSums}: }{column sums.}
+ \item{\code{rowFreq}: }{row frequencies (number of nonzero cells).}
+ \item{\code{colFreq}: }{column frequencies (number of nonzero cells).}
+ \item{\code{totalSum}: }{total sum.}
+ \item{\code{fill}: }{number of nonzero cells in the matrix.}
+ \item{\code{commsim}: }{the \code{commsim} object as a result
+ of the \code{method} ergument}
+ \item{\code{state}: }{current state of the permutations,
+ a matrix similar to the original.
+ It is \code{NULL} for non-sequential algorithms.}
+ \item{\code{iter}: }{current number of iterations
+ for sequential algorithms.
+ It is \code{NULL} for non-sequential algorithms.}
+}
+
+The \code{simulate} method returns an object of class \code{simmat}.
+It is a list with element \code{data} for the original matrix,
+and \code{perm} for an array of simulated matrices (third dimension
+corresponding to \code{nsim} argument).
+
+The \code{update} method returns \code{NULL} invisibly,
+and update the input object for sequential algorithms.
+}
+\author{
+Peter Solymos \email{solymos at ualberta.ca}
+}
+\seealso{
+\code{\link{commsim}}, \code{\link{make.commsim}},
+\code{\link{permatfull}}, \code{\link{permatswap}}
+\code{\link{commsimulator}}
+}
+\examples{
+x <- matrix(rbinom(10*12, 1, 0.5)*rpois(10*12, 3), 12, 10)
+
+## non-sequential nullmodel
+(nm <- nullmodel(x, "r00"))
+(sm <- simulate(nm, nsim=10))
+
+## sequential nullmodel
+(nm <- nullmodel(x, "swap"))
+(sm1 <- simulate(nm, nsim=10, thin=5))
+(sm2 <- simulate(nm, nsim=10, thin=5))
+
+## sequential nullmodel with burnin and extra updating
+(nm <- nullmodel(x, "swap"))
+(sm1 <- simulate(nm, burnin=10, nsim=10, thin=5))
+(sm2 <- simulate(nm, nsim=10, thin=5))
+
+## sequential nullmodel with separate initial burnin
+(nm <- nullmodel(x, "swap"))
+update(nm, nsim=10)
+(sm2 <- simulate(nm, nsim=10, thin=5))
+}
+\keyword{ multivariate }
+\keyword{ datagen }
More information about the Vegan-commits
mailing list