[Vegan-commits] r1915 - in pkg/vegan: inst man tests/Examples
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Sep 29 18:53:14 CEST 2011
Author: jarioksa
Date: 2011-09-29 18:53:13 +0200 (Thu, 29 Sep 2011)
New Revision: 1915
Modified:
pkg/vegan/inst/ChangeLog
pkg/vegan/man/oecosimu.Rd
pkg/vegan/man/vegan-deprecated.Rd
pkg/vegan/tests/Examples/vegan-Ex.Rout.save
Log:
Start the commsimulator() deprecation process by moving its
documentation from oecosimu.Rd to vegan-deprecated.Rd
Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog 2011-09-29 16:11:26 UTC (rev 1914)
+++ pkg/vegan/inst/ChangeLog 2011-09-29 16:53:13 UTC (rev 1915)
@@ -4,6 +4,12 @@
Version 2.1-2 (opened September 29, 20119
+ * commsimulator is going to be deprecated: it is no longer used in
+ oecosimu() ore elsewhere in other functions. Currently, functions
+ make.commsim(), nullmodel() and simulate.nullmodel() do the same,
+ and more. As the first step, its documenation in oecosimu.Rd is
+ moved to vegan-deprecated.Rd.
+
* examples: cut donw some excessively time consuming examples.
Profiling of all vegan examples showed that 25% of total time was
spent in anova.cca, and 12.6% in ordistep, but they probably are
Modified: pkg/vegan/man/oecosimu.Rd
===================================================================
--- pkg/vegan/man/oecosimu.Rd 2011-09-29 16:11:26 UTC (rev 1914)
+++ pkg/vegan/man/oecosimu.Rd 2011-09-29 16:53:13 UTC (rev 1915)
@@ -1,7 +1,6 @@
\encoding{UTF-8}
\name{oecosimu}
\alias{oecosimu}
-\alias{commsimulator}
\alias{as.ts.oecosimu}
\alias{as.mcmc.oecosimu}
\alias{density.oecosimu}
@@ -21,7 +20,6 @@
oecosimu(comm, nestfun, method, nsimul = 99, burnin = 0, thin = 1,
statistic = "statistic", alternative = c("two.sided", "less", "greater"),
...)
-commsimulator(x, method, thin=1)
\method{as.ts}{oecosimu}(x, ...)
\method{as.mcmc}{oecosimu}(x)
\method{density}{oecosimu}(x, ...)
@@ -38,9 +36,6 @@
and if \code{comm} is a \code{simmat} object, all other arguments
are ignored except \code{nestfun}, \code{statistic} and
\code{alternative}.}
- \item{x}{Community data for \code{commsimulator}, or an \code{oecosimu}
- result object for \code{as.ts}, \code{as.mcmc}, \code{density} and
- \code{densityplot}.}
\item{nestfun}{Function to analyse nestedness. Some functions are
provided in \pkg{vegan}, but any function can be used if it accepts the
community as the first argument, and returns either a plain number or
@@ -66,6 +61,7 @@
\item{alternative}{a character string specifying the alternative
hypothesis, must be one of \code{"two.sided"} (default), \code{"greater"}
or \code{"less"}. You can specify just the initial letter.}
+ \item{x}{An \code{oecosimu} result object.}
\item{data}{Ignored argument of the generic function.}
\item{xlab}{Label of the x-axis.}
\item{\dots}{Other arguments to functions.}
@@ -91,75 +87,6 @@
an example. Raup-Crick index (\code{\link{raupcrick}}) gives an
example of using a dissimilarities index.
- The description of the function \code{commsimulator} below is
- obsolescent: the function is not used any longer, but
- \code{oecosimu} uses null models described in \code{\link{commsim}}.
-
- Function \code{commsimulator} implements binary (presence/absence)
- null models for community composition.
- The implemented models are \code{r00} which maintains the
- number of presences but fills these anywhere so that neither species
- (column) nor site (row) totals are preserved. Methods \code{r0},
- \code{r1} and \code{r2} maintain the site (row) frequencies. Method \code{r0}
- fills presences anywhere on the row with no respect to species (column)
- frequencies, \code{r1} uses column marginal
- frequencies as probabilities, and \code{r2} uses squared column
- sums. Methods \code{r1} and \code{r2} try to simulate original species
- frequencies, but they are not strictly constrained. All these methods
- are reviewed by Wright et al. (1998). Method \code{c0} maintains
- species frequencies, but does not honour site (row) frequencies (Jonsson
- 2001).
-
- The other methods maintain both row and column frequencies.
- Methods \code{swap} and \code{tswap} implement sequential methods,
- where the matrix is changed only little in one step, but the changed
- matrix is used as an input if the next step.
- Methods \code{swap} and \code{tswap} inspect random 2x2 submatrices
- and if they are checkerboard units, the order of columns is
- swapped. This changes the matrix structure, but does not influence
- marginal sums (Gotelli & Entsminger
- 2003). Method \code{swap} inspects submatrices so long that a swap
- can be done. \enc{Miklós}{Miklos} & Podani (2004) suggest that this may lead into
- biased sequences, since some columns or rows may be more easily
- swapped, and they suggest trying a fixed number of times and
- doing zero to many swaps at one step. This method is implemented by
- method \code{tswap} or trial swap. Function \code{commsimulator} makes
- only one trial swap in time (which probably does nothing),
- but \code{oecosimu} estimates how many
- submatrices are expected before finding a swappable checkerboard,
- and uses that ratio to thin the results, so that on average one swap
- will be found per step of \code{tswap}. However, the checkerboard
- frequency probably changes during swaps, but this is not taken into
- account in estimating the \code{thin}. One swap still changes the
- matrix only little, and it may be useful to
- thin the results so that the statistic is only evaluated after
- \code{burnin} steps (and \code{thin}ned).
-
- Methods \code{quasiswap} and \code{backtracking} are not sequential,
- but each call produces a matrix that is independent of previous
- matrices, and has the same marginal totals as the original data. The
- recommended method is \code{quasiswap} which is much faster because
- it is implemented in C. Method \code{backtracking} is provided for
- comparison, but it is so slow that it may be dropped from future
- releases of \pkg{vegan} (or also implemented in C).
- Method \code{quasiswap} (\enc{Miklós}{Miklos} & Podani 2004)
- 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.
- Method \code{backtracking}
- 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 \dQuote{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. The \code{quasiswap} method is not sequential, but it produces
- a random incidence matrix with given marginal totals.
-
Function \code{as.ts} transforms the simulated results of sequential
methods into a time series or a \code{\link{ts}} object. This allows
using analytic tools for time series in studying the sequences (see
@@ -195,50 +122,19 @@
\code{commsimulator} returns a null model matrix or a swap of the
input matrix. }
-\references{
- 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.
+\author{Jari Oksanen and Peter Solymos}
- 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{ Jari Oksanen }
\note{
- Functions \code{commsimulator} and \code{oecosimu} do not have
- default \code{nestfun} nor default \code{method}, because there is
- no clear natural choice. If you use these methods, you must be able
- to choose your own strategy. The choice of nestedness index is
- difficult because the functions seem to imply very different
- concepts of structure and randomness. The choice of swapping method
- is also problematic. Method \code{r00} has some heuristic value of
- being really random. However, it produces null models which are
- different from observed communities in most respects, and a
- \dQuote{significant} result may simply mean that not all species are
- equally common (\code{r0} is similar with this respect). It is also
- difficult to find justification for \code{r2}. The methods
- maintaining both row and column totals only study the community
- relations, but they can be very slow. Moreover, they regard marginal
- totals as constraints instead of results of occurrence patterns. You
- should evaluate timings in small trials (one cycle) before launching
- an extensive simulation. One swap is fast, but it changes data only
- little, and you may need long \code{burnin} and strong
- \code{thin}ning in large matrices. You should plot the simulated
- values to see that they are more or less stationary and there is no
- trend. Method \code{quasiswap} is implemented
- in C and it is much faster than \code{backtrack}. Method
- \code{backtrack} may be removed from later releases of \pkg{vegan}
- because it is slow, but it is still included for comparison.
+
+ Function \code{oecosimu} does not have default \code{nestfun} nor
+ default \code{method}, because there is no clear natural choice. If
+ you use these methods, you must be able to choose your own
+ strategy. For description of canned null models and discussion, see
+ \code{\link{commsim}}. For canned nestedness functions see
+ \code{\link{nestedtemp}} (which describes several functions).
+ Although \code{oecosimu} is given in the Null model framework where
+ nestedness is typically analysed, the function is not limited to
+ study nestedness, but it is much more general (see Examples).
If you wonder about the name of \code{oecosimu}, look at journal
names in the References (and more in \code{\link{nestedtemp}}). }
Modified: pkg/vegan/man/vegan-deprecated.Rd
===================================================================
--- pkg/vegan/man/vegan-deprecated.Rd 2011-09-29 16:11:26 UTC (rev 1914)
+++ pkg/vegan/man/vegan-deprecated.Rd 2011-09-29 16:53:13 UTC (rev 1915)
@@ -1,5 +1,7 @@
+\encoding{UTF-8}
\name{vegan-deprecated}
\alias{metaMDSrotate}
+\alias{commsimulator}
\alias{vegan-deprecated}
%------ NOTE: ../R/vegan-deprecated.R must be synchronized with this!
@@ -11,13 +13,24 @@
}
\usage{
metaMDSrotate(object, vec, na.rm = FALSE, ...)
+commsimulator(x, method, thin=1)
}
\arguments{
+ ## metaMDSrotate
\item{object}{A result object from \code{metaMDS}.}
\item{vec}{A continuous site variable (vector).}
\item{na.rm}{Remove missing values from continuous variable \code{vec}.}
\item{\dots}{Other parameters passed to functions.}
+ ## commsimulator
+ \item{x}{Community data for \code{commsimulator}}
+ \item{method}{Null model method: either a name (character string) of
+ a method defined in \code{\link{make.commsim}} or a
+ \code{\link{commsim}} function.}
+ \item{thin}{Number of discarded null communities between two
+ evaluations of nestedness statistic in sequential methods
+ \code{"swap"} and \code{"tswap"} (ignored with non-sequential
+ methods)}
}
\details{
@@ -30,7 +43,108 @@
\code{\link{MDSrotate}} which can handle \code{\link{monoMDS}}
results in addition to \code{\link{metaMDS}}.
+ Function \code{commsimulator} is replaced with
+ \code{\link{make.commsim}} which defines the Null models, and
+ functions \code{\link{nullmodel}} and
+ \code{\link{simulate.nullmodel}} that check the input data and
+ generate the Null model communities. Function \code{commsimulator}
+ was used to generate a single Null model for presence/absence
+ (binary) data. Below is a copy of its original documentation in
+ \code{\link{oecosimu}}, where it is now replaced with
+ \code{\link{make.commsim}}, \code{\link{nullmodel}} and
+ \code{\link{simulate.nullmodel}}. Approximately the same
+ documentation for these models is found in
+ \code{\link{make.commsim}}. (However, the random number sequences
+ for model \code{r0} differ, and you must use \code{method =
+ "r0_old"} in \code{\link{make.commsim}} to reproduce the
+ \code{commsimulator} results.)
+
+ Function \code{commsimulator} implements binary (presence/absence)
+ null models for community composition.
+ The implemented models are \code{r00} which maintains the
+ number of presences but fills these anywhere so that neither species
+ (column) nor site (row) totals are preserved. Methods \code{r0},
+ \code{r1} and \code{r2} maintain the site (row) frequencies. Method \code{r0}
+ fills presences anywhere on the row with no respect to species (column)
+ frequencies, \code{r1} uses column marginal
+ frequencies as probabilities, and \code{r2} uses squared column
+ sums. Methods \code{r1} and \code{r2} try to simulate original species
+ frequencies, but they are not strictly constrained. All these methods
+ are reviewed by Wright et al. (1998). Method \code{c0} maintains
+ species frequencies, but does not honour site (row) frequencies (Jonsson
+ 2001).
+
+ The other methods maintain both row and column frequencies.
+ Methods \code{swap} and \code{tswap} implement sequential methods,
+ where the matrix is changed only little in one step, but the changed
+ matrix is used as an input if the next step.
+ Methods \code{swap} and \code{tswap} inspect random 2x2 submatrices
+ and if they are checkerboard units, the order of columns is
+ swapped. This changes the matrix structure, but does not influence
+ marginal sums (Gotelli & Entsminger
+ 2003). Method \code{swap} inspects submatrices so long that a swap
+ can be done. \enc{Miklós}{Miklos} & Podani (2004) suggest that this may lead into
+ biased sequences, since some columns or rows may be more easily
+ swapped, and they suggest trying a fixed number of times and
+ doing zero to many swaps at one step. This method is implemented by
+ method \code{tswap} or trial swap. Function \code{commsimulator} makes
+ only one trial swap in time (which probably does nothing),
+ but \code{oecosimu} estimates how many
+ submatrices are expected before finding a swappable checkerboard,
+ and uses that ratio to thin the results, so that on average one swap
+ will be found per step of \code{tswap}. However, the checkerboard
+ frequency probably changes during swaps, but this is not taken into
+ account in estimating the \code{thin}. One swap still changes the
+ matrix only little, and it may be useful to
+ thin the results so that the statistic is only evaluated after
+ \code{burnin} steps (and \code{thin}ned).
+
+ Methods \code{quasiswap} and \code{backtracking} are not sequential,
+ but each call produces a matrix that is independent of previous
+ matrices, and has the same marginal totals as the original data. The
+ recommended method is \code{quasiswap} which is much faster because
+ it is implemented in C. Method \code{backtracking} is provided for
+ comparison, but it is so slow that it may be dropped from future
+ releases of \pkg{vegan} (or also implemented in C).
+ Method \code{quasiswap} (\enc{Miklós}{Miklos} & Podani 2004)
+ 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.
+ Method \code{backtracking}
+ 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 \dQuote{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. The \code{quasiswap} method is not sequential, but it produces
+ a random incidence matrix with given marginal totals.
+
}
+
+\references{
+ 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.
+ }
+
\seealso{
\code{\link{Deprecated}}
}
Modified: pkg/vegan/tests/Examples/vegan-Ex.Rout.save
===================================================================
--- pkg/vegan/tests/Examples/vegan-Ex.Rout.save 2011-09-29 16:11:26 UTC (rev 1914)
+++ pkg/vegan/tests/Examples/vegan-Ex.Rout.save 2011-09-29 16:53:13 UTC (rev 1915)
@@ -23,7 +23,7 @@
> options(warn = 1)
> library('vegan')
Loading required package: permute
-This is vegan 2.1-1
+This is vegan 2.1-2
>
> assign(".oldSearch", search(), pos = 'CheckExEnv')
> cleanEx()
@@ -161,7 +161,7 @@
Formula:
y ~ poly(x1, 1) + poly(x2, 1)
-<environment: 0x1026163c0>
+<environment: 0x102616740>
Total model degrees of freedom 3
GCV score: 0.0427924
@@ -4132,8 +4132,8 @@
>
> ### Name: oecosimu
> ### Title: Evaluate Statistics with Null Models of Biological Communities
-> ### Aliases: oecosimu commsimulator as.ts.oecosimu as.mcmc.oecosimu
-> ### density.oecosimu densityplot.oecosimu
+> ### Aliases: oecosimu as.ts.oecosimu as.mcmc.oecosimu density.oecosimu
+> ### densityplot.oecosimu
> ### Keywords: multivariate datagen
>
> ### ** Examples
@@ -4732,7 +4732,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x1075ffb90>
+<environment: 0x1075fb590>
Estimated degrees of freedom:
6.4351 total = 7.435071
@@ -4748,7 +4748,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x107aa9f48>
+<environment: 0x1078fa348>
Estimated degrees of freedom:
6.1039 total = 7.103853
@@ -4904,7 +4904,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x10859b828>
+<environment: 0x1079ace28>
Estimated degrees of freedom:
8.9275 total = 9.927492
@@ -4917,7 +4917,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x1070ec438>
+<environment: 0x1070ece38>
Estimated degrees of freedom:
7.7529 total = 8.75294
@@ -4930,7 +4930,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x107471a68>
+<environment: 0x1079fcc68>
Estimated degrees of freedom:
8.8962 total = 9.89616
@@ -7192,7 +7192,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x1047b6498>
+<environment: 0x10775ea98>
Estimated degrees of freedom:
2 total = 3
@@ -7668,7 +7668,7 @@
> ### * <FOOTER>
> ###
> cat("Time elapsed: ", proc.time() - get("ptime", pos = 'CheckExEnv'),"\n")
-Time elapsed: 105.636 1.365 108.878 0 0
+Time elapsed: 175.18 2.895 213.598 0 0
> grDevices::dev.off()
null device
1
More information about the Vegan-commits
mailing list