Function evaluates a statistic or a vector of statistics in
community and evaluates its significance in a series of simulated
random communities. The approach has been used traditionally for
the analysis of nestedness, but the function is more general and can
be used with any statistics evaluated with simulated
communities. Function oecosimu
collects and evaluates the
statistics. The Null model communities are described in
make.commsim
and permatfull
/
permatswap
, the definition of Null models in
nullmodel
, and nestedness statistics in
nestednodf
(which describes several alternative
statistics, including nestedness temperature, N0, checker
board units, nestedness discrepancy and NODF).
1 2 3 4 5 6 7 
comm 
Community data, or a Null model object generated by

nestfun 
Function analysed. Some nestedness functions are
provided in vegan (see 
method 
Null model method: either a name (character string) of
a method defined in 
nsimul 
Number of simulated null communities (ignored if

burnin 
Number of null communities discarded before proper
analysis in sequential methods (such as 
thin 
Number of discarded null communities between two
evaluations of nestedness statistic in sequential methods (ignored
with nonsequential methods or when 
statistic 
The name of the statistic returned by

alternative 
a character string specifying the alternative
hypothesis, must be one of 
batchsize 
Size in Megabytes of largest simulation object. If
a larger structure would be produced, the analysis is broken
internally into batches. With default 
parallel 
Number of parallel processes or a predefined socket
cluster. With 
x 
An 
... 
Other arguments to functions. 
Function oecosimu
is a wrapper that evaluates a statistic
using function given by nestfun
, and then simulates a series
of null models based on nullmodel
, and evaluates the
statistic on these null models. The vegan packages contains
some nestedness functions that are described separately
(nestedchecker
, nesteddisc
,
nestedn0
, nestedtemp
,
nestednodf
), but many other functions can be used as
long as they are meaningful with simulated communities. An
applicable function must return either the statistic as a plain
number or a vector, or as a list element "statistic"
(like
chisq.test
), or in an item whose name is given in the
argument statistic
. The statistic can be a single number
(like typical for a nestedness index), or it can be a vector. The
vector indices can be used to analyse site (row) or species (column)
properties, see treedive
for an example. RaupCrick
index (raupcrick
) gives an example of using a
dissimilarities.
The Null model type can be given as a name (quoted character string)
that is used to define a Null model in make.commsim
.
These include all binary models described by Wright et al. (1998),
Jonsson (2001), Gotelli & Entsminger (2003), Miklós &
Podani (2004), and some others. There are several quantitative Null
models, such those discussed by Hardy (2008), and several that are
unpublished (see make.commsim
,
permatfull
, permatswap
for
discussion). The user can also define her own commsim
function (see Examples).
Function works by first defining a nullmodel
with
given commsim
, and then generating a series of
simulated communities with simulate.nullmodel
. A
shortcut can be used for any of these stages and the input can be
Community data (comm
), Null model function
(nestfun
) and the number of simulations (nsimul
).
A nullmodel
object and the number of
simulations, and argument method
is ignored.
A threedimensional array of simulated communities generated
with simulate.nullmodel
, and arguments
method
and nsimul
are ignored.
The last case allows analysing several statistics with the same simulations.
The function first generates simulations with given
nullmodel
and then analyses these using the
nestfun
. With large data sets and/or large number of
simulations, the generated objects can be very large, and if the
memory is exhausted, the analysis can become very slow and the
system can become unresponsive. The simulation will be broken into
several smaller batches if the simulated nullmodel
objective will be above the set batchsize
to avoid memory
problems (see object.size
for estimating the size of
the current data set). The parallel processing still increases the
memory needs. The parallel processing is only used for evaluating
nestfun
. The main load may be in simulation of the
nullmodel
, and parallel
argument does not help
there.
Function as.ts
transforms the simulated results of sequential
methods into a time series or a ts
object. This allows
using analytic tools for time series in studying the sequences (see
examples). Function as.mcmc
transforms the simulated results
of sequential methods into an mcmc
object of the
coda package. The coda package provides functions for
the analysis of stationarity, adequacy of sample size,
autocorrelation, need of burnin and much more for sequential
methods, and summary of the results. Please consult the
documentation of the coda package.
Function permustats
provides support to the standard
density
, densityplot
,
qqnorm
and qqmath
functions for
the simulated values.
Function oecosimu
returns an object of class
"oecosimu"
. The result object has items statistic
and
oecosimu
. The statistic
contains the complete object
returned by nestfun
for the original data. The
oecosimu
component contains the following items:
statistic 
Observed values of the statistic. 
simulated 
Simulated values of the statistic. 
means 
Mean values of the statistic from simulations. 
z 
Standardized effect sizes (SES, a.k.a. the zvalues) of the observed statistic based on simulations. 
pval 
The Pvalues of the statistic based on simulations. 
alternative 
The type of testing as given in argument 
method 
The 
isSeq 

If you wonder about the name of oecosimu
, look at journal
names in the References (and more in nestedtemp
).
The internal structure of the function was radically changed in
vegan 2.20 with introduction of commsim
and
nullmodel
and deprecation of
commsimulator
. However, the results and the basic user
interface remain the same (except that method = "r0_old"
must
be used to reproduce the old results of "method = r0"
).
Jari Oksanen and Peter Solymos
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. Journal of Ecology 96, 914–926.
Gotelli, N.J. & Entsminger, N.J. (2003). Swap algorithms in null model analysis. Ecology 84, 532–535.
Jonsson, B.G. (2001) A null model for randomization tests of nestedness in species assemblages. Oecologia 127, 309–313.
Miklós, I. & Podani, J. (2004). Randomization of presenceabsence matrices: comments and new algorithms. 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. Oecologia 113, 1–20.
Function oecosimu
currently defines null models with
commsim
and generates the simulated null model
communities with nullmodel
and
simulate.nullmodel
. For other applications of
oecosimu
, see treedive
and
raupcrick
.
Function rndtaxa
(labdsv package) randomizes a community table. See also
nestedtemp
(that also discusses other nestedness
functions) and treedive
for another application.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49  ## Use the first eigenvalue of correspondence analysis as an index
## of structure: a model for making your own functions.
data(sipoo)
## Traditional nestedness statistics (number of checkerboard units)
oecosimu(sipoo, nestedchecker, "r0")
## sequential model, onesided test, a vector statistic
out < oecosimu(sipoo, decorana, "swap", burnin=100, thin=10,
statistic="evals", alt = "greater")
out
## Inspect the swap sequence as a time series object
plot(as.ts(out))
lag.plot(as.ts(out))
acf(as.ts(out))
## Density plot
densityplot(permustats(out), as.table = TRUE, layout = c(1,4))
## Use quantitative null models to compare
## mean BrayCurtis dissimilarities
data(dune)
meandist < function(x) mean(vegdist(x, "bray"))
mbc1 < oecosimu(dune, meandist, "r2dtable")
mbc1
## Define your own null model as a 'commsim' function: shuffle cells
## in each row
foo < function(x, n, nr, nc, ...) {
out < array(0, c(nr, nc, n))
for (k in seq_len(n))
out[,,k] < apply(x, 2, function(z) sample(z, length(z)))
out
}
cf < commsim("myshuffle", foo, isSeq = FALSE, binary = FALSE,
mode = "double")
oecosimu(dune, meandist, cf)
## Use prebuilt null model
nm < simulate(nullmodel(sipoo, "curveball"), 99)
oecosimu(nm, nestedchecker)
## Several chains of a sequential model  this can be generalized
## for parallel processing (see ?smbind)
nm < replicate(5, simulate(nullmodel(sipoo, "swap"), 99,
thin=10, burnin=100), simplify = FALSE)
## nm is now a list of nullmodels: use smbind to combine these into one
## nullmodel with several chains
nm < smbind(nm, MARGIN = 3)
nm
oecosimu(nm, nestedchecker)
## After this you can use as.mcmc() and tools in the coda package to
## analyse the chains (these will show that thin, burnin and nsimul are
## all too low for real analysis).

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
All documentation is copyright its authors; we didn't write any of that.