Description Usage Arguments Details Value Binary null models Quantitative Models for Counts with Fixed Marginal Sums Quantitative Swap Models Quantitative Swap and Shuffle Models Quantitative Shuffle Methods Author(s) References See Also Examples
The commsim
function can be used to feed Null Model algorithms into
nullmodel
analysis.
The make.commsim
function returns various predefined algorithm types
(see Details).
These functions represent low level interface for community null model
infrastructure in vegan with the intent of extensibility,
and less emphasis on direct use by users.
1 2 3 4  commsim(method, fun, binary, isSeq, mode)
make.commsim(method)
## S3 method for class 'commsim'
print(x, ...)

method 
Character, name of the algorithm. 
fun 
A function. For possible formal arguments of this function see Details. 
binary 
Logical, if the algorithm applies to presenceabsence or count matrices. 
isSeq 
Logical, if the algorithm is sequential (needs burnin) or not. 
mode 
Character, storage mode of the community matrix, either

x 
An object of class 
... 
Additional arguments. 
The function fun
must return an array of dim(nr, nc, n)
,
and must take some of the following arguments:
x
: input matrix,
n
: number of permuted matrices in output,
nr
: number of rows,
nc
: number of columns,
rs
: vector of row sums,
cs
: vector of column sums,
rf
: vector of row frequencies (nonzero cells),
cf
: vector of column frequencies (nonzero cells),
s
: total sum of x
,
fill
: matrix fill (nonzero cells),
thin
: thinning value for sequential algorithms,
...
: additional arguments.
Several null model algorithm are predefined and can be called by
their name. The predefined algorithms are described in detail in the
following chapters. The binary null models produce matrices of zeros
(absences) and ones (presences) also when input matrix is
quantitative. There are two types of quantitative data: Counts are
integers with a natural unit so that individuals can be shuffled, but
abundances can have real (floating point) values and do not have a
natural subunit for shuffling. All quantitative models can handle
counts, but only some are able to handle real values. Some of the null
models are sequential so that the next matrix is derived from the
current one. This makes models dependent on each other, and usually
you must thin these matrices and study the sequences for stability:
see oecosimu
for details and instructions.
See Examples for structural constraints imposed by each algorithm and defining your own null model.
An object of class commsim
with elements
corresponding to the arguments (method
, binary
,
isSeq
, mode
, fun
).
If the input of make.comsimm
is a commsim
object,
it is returned without further evaluation. If this is not the case,
the character method
argument is matched against
predefined algorithm names. An error message is issued
if none such is found. If the method
argument is missing,
the function returns names of all currently available
null model algorithms as a character vector.
All binary null models retain fill: number of absences or conversely
the number of absences. The classic models may also column (species)
frequencies (c0
) or row frequencies or species richness of each
site (r0
) and take into account commonness and rarity of
species (r1
, r2
). Algorithms swap
, tswap
,
quasiswap
and backtracking
preserve both row and column
frequencies. Two first of these are sequential but the two latter are
nonsequential and produce independent matrices. Basic algorithms are
reviewed by Wright et al. (1998).
"r00"
: nonsequential algorithm for binary matrices
that only maintains the number of presences (fill).
"r0", "r0_old"
: nonsequential algorithm for binary
matrices that maintains the site (row) frequencies.
Methods "r0"
and "r0_old"
implement the
same method, but use different random number sequences; use
"r0_old"
if you want to reproduce results in vegan
2.00 or older using commsimulator
(now deprecated).
"r1"
: nonsequential algorithm for binary matrices
that maintains the site (row) frequencies, but uses column marginal
frequencies as probabilities of selecting species.
"r2"
: nonsequential algorithm for binary matrices
that maintains the site (row) frequencies, and uses squared column
sums as as probabilities of selecting species.
"c0"
: nonsequential algorithm for binary matrices
that maintains species frequencies (Jonsson 2001).
"swap"
: sequential algorithm for binary matrices that
changes the matrix structure, but does not influence marginal sums
(Gotelli & Entsminger 2003). This inspects 2 by
2 submatrices so long that a swap can be done.
"tswap"
: sequential algorithm for binary matrices.
Same as the "swap"
algorithm, but it tries a fixed
number of times and performs zero to many swaps at one step
(according the thin argument in later call). This
approach was suggested by Miklós & Podani (2004)
because they found that ordinary swap may lead to biased
sequences, since some columns or rows may be more easily swapped.
"quasiswap"
: nonsequential algorithm for binary
matrices that 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 2 by 2 matrices and performs a quasiswap on them. Quasiswap is
similar to ordinary swap, but it can reduce numbers above one
to ones maintaining marginal totals (Miklós & Podani
2004). This is the recommended algorithm if you want to retain both
species and row frequencies.
"backtracking"
: nonsequential algorithm for binary
matrices that 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. The function may be very slow
for some matrices.
These models shuffle individuals of counts but keep marginal sums
fixed, but marginal frequencies are not preserved. Algorithm
r2dtable
uses standard R function r2dtable
also
used for simulated Pvalues in chisq.test
.
Algorithm quasiswap_count
uses the same, but retains the
original fill. Typically this means increasing numbers of zero cells
and the result is zeroinflated with respect to r2dtable
.
"r2dtable"
: nonsequential algorithm for count
matrices. This algorithm keeps matrix sum and row/column sums
constant. Based on r2dtable
.
"quasiswap_count"
: nonsequential algorithm for count
matrices. This algorithm is similar as Carsten Dormann's
swap.web
function in the package
bipartite. First, a random matrix is generated by the
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
"swap_count"
algorithm for details) to maintain row and
column totals.
Quantitative swap models are similar to binary swap
, but they
swap the largest permissible value. The models in this section all
maintain the fill and perform a quantitative swap only if this can be
done without changing the fill. Single step of swap often changes the
matrix very little. In particular, if cell counts are variable, high
values change very slowly. Checking the chain stability and
independence is even more crucial than in binary swap, and very strong
thin
ning is often needed. These models should never be used
without inspecting their properties for the current data.
"swap_count"
: sequential algorithm for count matrices.
This algorithm find 2 x 2 submatrices that can be
swapped leaving column and row totals and fill unchanged. The
algorithm finds the largest value in the submatrix that can be
swapped (d). 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 does not
change.
"abuswap_r"
: sequential algorithm for count or
nonnegative real valued matrices with fixed row frequencies (see
also permatswap
). The algorithm is similar to
swap_count
, but uses different swap value for each row of the
2 x 2 submatrix. Each step changes the the
corresponding column sums, but honours matrix fill, row sums, and
row/column frequencies (Hardy 2008; randomization scheme 2x).
"abuswap_c"
: sequential algorithm for count or
nonnegative real valued matrices with fixed column frequencies (see
also permatswap
). The algorithm is similar as the
previous one, but operates on columns. 2 x 2 submatrices. Each step
changes the the corresponding row sums, but honours matrix fill,
column sums, and row/column frequencies (Hardy 2008; randomization
scheme 3x).
Quantitative Swap and Shuffle methods (swsh
methods) preserve
fill and column and row frequencies, and also either row or column
sums. The methods first perform a binary quasiswap
and then
shuffle original quantitative data to nonzero cells. The
samp
methods shuffle original nonzero cell values and can be
used also with noninteger data. The both
methods
redistribute individuals randomly among nonzero cells and can only
be used with integer data. The shuffling is either free over the
whole matrix, or within rows (r
methods) or within columns
(c
methods). Shuffling within a row preserves row sums, and
shuffling within a column preserves column sums.
"swsh_samp"
: nonsequential algorithm for
quantitative data (either integer counts or noninteger values).
Original nonzero values values are shuffled.
"swsh_both"
: nonsequential algorithm for count data.
Individuals are shuffled freely over nonzero cells.
"swsh_samp_r"
: nonsequential algorithm for
quantitative data. Nonzero values (samples) are shuffled
separately for each row.
"swsh_samp_c"
: nonsequential algorithm for
quantitative data. Nonzero values (samples) are shuffled
separately for each column.
"swsh_both_r"
: nonsequential algorithm for count matrices.
Individuals are shuffled freely for nonzero values within each row.
"swsh_both_c"
: nonsequential algorithm for count matrices.
Individuals are shuffled freely for nonzero values with each column.
Quantitative shuffle methods are generalizations of binary models
r00
, r0
and c0
. The _ind
methods shuffle
individuals so that the grand sum, row sum or column sums are similar
as in the observed matrix. These methods are similar as
r2dtable
but with still slacker constraints on marginal
sums. The _samp
and _both
methods first perform the
correspongind binary model with similar restriction on marginal
frequencies, and then distribute quantitative values over nonzero
cells. The _samp
models shuffle original cell values and can
therefore handle also noncount real values. The _both
models
shuffle individuals among nonzero values. The shuffling is over the
whole matrix in r00_
, and within row in r0_
and within
column in c0_
in all cases.
"r00_ind"
: nonsequential algorithm for count matrices.
This algorithm keeps total sum constant,
individuals are shuffled among cells of the matrix.
"r0_ind"
: nonsequential algorithm for count matrices.
This algorithm keeps row sums constant,
individuals are shuffled among cells of each row of the matrix.
"c0_ind"
: nonsequential algorithm for count matrices.
This algorithm keeps column sums constant,
individuals are shuffled among cells of each column of the matrix.
"r00_samp"
: nonsequential algorithm for count
or nonnegative real valued (mode = "double"
) matrices.
This algorithm keeps total sum constant,
cells of the matrix are shuffled.
"r0_samp"
: nonsequential algorithm for count
or nonnegative real valued (mode = "double"
) matrices.
This algorithm keeps row sums constant,
cells within each row are shuffled.
"c0_samp"
: nonsequential algorithm for count
or nonnegative real valued (mode = "double"
) matrices.
This algorithm keeps column sums constant,
cells within each column are shuffled.
"r00_both"
: nonsequential algorithm for count matrices.
This algorithm keeps total sum constant,
cells and individuals among cells of the matrix are shuffled.
"r0_both"
: nonsequential algorithm for count matrices.
This algorithm keeps total sum constant,
cells and individuals among cells of each row are shuffled.
"c0_both"
: nonsequential algorithm for count matrices.
This algorithm keeps total sum constant,
cells and individuals among cells of each column are shuffled.
Jari Oksanen and Peter Solymos
Gotelli, N.J. & Entsminger, N.J. (2001). Swap and fill algorithms in null model analysis: rethinking the knight's tour. Oecologia 129, 281–291.
Gotelli, N.J. & Entsminger, N.J. (2003). Swap algorithms in null model analysis. Ecology 84, 532–535.
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.
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.
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.
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.
See permatfull
, permatswap
for
alternative specification of quantitative null models. Function
oecosimu
gives a higherlevel interface for applying null
models in hypothesis testing and analysis of models. Function
nullmodel
and simulate.nullmodel
are used to
generate arrays of simulated null model matrices.
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  ## 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
(cs < make.commsim("swap"))
## feeding a commsim object as argument
make.commsim(cs)
## 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"),
attr(y, "mode") == "double"))
names(z) < c("binary", "isSeq", "double")
c(z, out)
}
x < matrix(rbinom(10*12, 1, 0.5)*rpois(10*12, 3), 12, 10)
algos < make.commsim()
a < t(sapply(algos, evalfun, x=x, n=10))
print(as.table(ifelse(a==1,1,0)), zero.print = ".")

Loading required package: permute
Loading required package: lattice
This is vegan 2.44
An object of class "commsim"
'r00' method (binary, nonsequential, integer mode)
An object of class "commsim"
'swap' method (binary, sequential, integer mode)
An object of class "commsim"
'swap' method (binary, sequential, integer mode)
binary isSeq double sum fill rowSums colSums rowFreq colFreq
r00 1 . . 1 1 . . . .
c0 1 . . 1 1 . 1 . 1
r0 1 . . 1 1 1 . 1 .
r0_old 1 . . 1 1 1 . 1 .
r1 1 . . 1 1 1 . 1 .
r2 1 . . 1 1 1 . 1 .
quasiswap 1 . . 1 1 1 1 1 1
swap 1 1 . 1 1 1 1 1 1
tswap 1 1 . 1 1 1 1 1 1
curveball 1 1 . 1 1 1 1 1 1
backtrack 1 . . 1 1 1 1 1 1
r2dtable . . . 1 . 1 1 . .
swap_count . 1 . 1 1 1 1 . .
quasiswap_count . . . 1 1 1 1 . .
swsh_samp . . 1 1 1 . . 1 1
swsh_both . . . 1 1 . . 1 1
swsh_samp_r . . 1 1 1 1 . 1 1
swsh_samp_c . . 1 1 1 . 1 1 1
swsh_both_r . . . 1 1 1 . 1 1
swsh_both_c . . . 1 1 . 1 1 1
abuswap_r . 1 1 1 1 1 . 1 1
abuswap_c . 1 1 1 1 . 1 1 1
r00_samp . . 1 1 1 . . . .
c0_samp . . 1 1 1 . 1 . 1
r0_samp . . 1 1 1 1 . 1 .
r00_ind . . . 1 . . . . .
c0_ind . . . 1 . . 1 . .
r0_ind . . . 1 . 1 . . .
r00_both . . . 1 1 . . . .
c0_both . . . 1 1 . 1 . 1
r0_both . . . 1 1 1 . 1 .
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.