nullmodel: Null Model and Simulation
In vegan: Community Ecology Package

Description Usage Arguments Details Value Author(s) See Also Examples

The nullmodel function creates an object, which can serve as a basis for Null Model simulation via the simulate method. The update method updates the nullmodel object without sampling (effective for sequential algorithms).

nullmodel(x, method)
## S3 method for class 'nullmodel'
print(x, ...)
## S3 method for class 'nullmodel'
simulate(object, nsim = 1, 
seed = NULL, burnin = 0, thin = 1, ...)
## S3 method for class 'nullmodel'
update(object, nsim = 1, 
seed = NULL, ...)
## S3 method for class 'simmat'
print(x, ...)

`x`	A community matrix. For the `print` method, it is an object to be printed.
`method`	Character, specifying one of the null model algorithms listed on the help page of `commsim`. It can be a user supplied object of class `commsim`.
`object`	An object of class `nullmodel` returned by the function `nullmodel`.
`nsim`	Positive integer, the number of simulated matrices to return. For the `update` method, it is the number of burnin steps made for sequential algorithms to update the status of the input model `object`.
`seed`	An object specifying if and how the random number generator should be initialized ("seeded"). Either `NULL` or an integer that will be used in a call to `set.seed` before simulating the matrices. If set, the value is saved as the `"seed"` attribute of the returned value. The default, `NULL` will not change the random generator state, and return `.Random.seed` as the `"seed"` attribute, see Value.
`burnin`	Nonnegative integer, specifying the number of steps discarded before starting simulation. Active only for sequential null model algorithms. Ignored for non-sequential null model algorithms.
`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.
`...`	Additional arguments supplied to algorithms.

The purpose of the nullmodel function is to create an object, where all necessary statistics of the input matrix are calculated only once. This information is reused, but not recalculated in each step of the simulation process done by the simulate method.

The 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 nullmodel object. Therefore, it is possible to do diagnostic tests on the returned simmat object, and make further simulations, or use increased thinning value if desired.

The update method makes burnin steps in case of sequential algorithms to update the status of the input model without any attempt to return matrices. For non-sequential algorithms the method does nothing.

update is the preferred way of making burnin iterations without sampling. Alternatively, burnin can be done via the simulate method. For convergence diagnostics, it is recommended to use the 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.

The function nullmodel returns an object of class nullmodel. It is a set of objects sharing the same environment:

data: original matrix in integer mode.
nrow: number of rows.
ncol: number of columns.
rowSums: row sums.
colSums: column sums.
rowFreq: row frequencies (number of nonzero cells).
colFreq: column frequencies (number of nonzero cells).
totalSum: total sum.
fill: number of nonzero cells in the matrix.
commsim: the commsim object as a result of the method argument.
state: current state of the permutations, a matrix similar to the original. It is NULL for non-sequential algorithms.
iter: current number of iterations for sequential algorithms. It is NULL for non-sequential algorithms.

The simulate method returns an object of class simmat. It is an array of simulated matrices (third dimension corresponding to nsim argument).

The update method returns the current state (last updated matrix) invisibly, and update the input object for sequential algorithms. For non sequential algorithms, it returns NULL.

Jari Oksanen and Peter Solymos

commsim, make.commsim, permatfull, permatswap

x <- matrix(rbinom(12*10, 1, 0.5)*rpois(12*10, 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"))
nm <- update(nm, nsim=10)
(sm2 <- simulate(nm, nsim=10, thin=5))

Loading required package: permute
Loading required package: lattice
This is vegan 2.4-4
An object of class "nullmodel" 
'r00' method (binary, non-sequential)
12 x 10 matrix

An object of class "simmat" 
'r00' method (binary, non-sequential)
12 x 10 matrix
Number of permuted matrices = 10 

An object of class "nullmodel" 
'swap' method (binary, sequential)
12 x 10 matrix
Iterations = 0 

An object of class "simmat" 
'swap' method (binary, sequential)
12 x 10 matrix
Number of permuted matrices = 10 
Start = 5, End = 50, Thin = 5

An object of class "simmat" 
'swap' method (binary, sequential)
12 x 10 matrix
Number of permuted matrices = 10 
Start = 55, End = 100, Thin = 5

An object of class "nullmodel" 
'swap' method (binary, sequential)
12 x 10 matrix
Iterations = 0 

An object of class "simmat" 
'swap' method (binary, sequential)
12 x 10 matrix
Number of permuted matrices = 10 
Start = 15, End = 60, Thin = 5

An object of class "simmat" 
'swap' method (binary, sequential)
12 x 10 matrix
Number of permuted matrices = 10 
Start = 5, End = 50, Thin = 5

An object of class "nullmodel" 
'swap' method (binary, sequential)
12 x 10 matrix
Iterations = 0 

An object of class "simmat" 
'swap' method (binary, sequential)
12 x 10 matrix
Number of permuted matrices = 10 
Start = 15, End = 60, Thin = 5