nullmodel: Null Model and Simulation
In vegan: Community Ecology Package
nullmodel R Documentation
Null Model and Simulation
Description
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).
smbind binds together multiple simmat objects.
Usage
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, ...)
smbind(object, ..., MARGIN, strict = TRUE)
Arguments
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.
In case of smbind it is a simmat object
as returned by the update or simulate methods.
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.
MARGIN
Integer, indicating the dimension over which multiple
simmat objects are to be bound together by smbind.
1: matrices are stacked (row bound), 2: matrices are column bound,
3: iterations are combined. Needs to be of length 1.
The other dimensions are expected to match across the objects.
strict
Logical, if consistency of the time series attributes
("start", "end", "thin", and number of simulated matrices)
of simmat objects are strictly enforced when
binding multiple objects together using smbind.
Applies only to input objects based on sequential
null model algorithms.
...
Additional arguments supplied to algorithms.
In case of smbind it can contain multiple simmat objects.
Details
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 smbind function can be used to combine multiple
simmat objects. This comes handy when null model
simulations are stratified by sites (MARGIN = 1)
or by species (MARGIN = 2), or in the case when
multiple objects are returned by identical/consistent settings
e.g. during parallel computations (MARGIN = 3).
Sanity checks are made to ensure that combining multiple
objects is sensible, but it is the user's responsibility
to check independence of the simulated matrices
and the null distribution has converged
in case of sequential null model algorithms.
The strict = FALSE setting can relax
checks regarding start, end, and thinning values
for sequential null models.
Value
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.
The smbind function returns an object of class simmat.
Note
Care must be taken when the input matrix only contains a single
row or column. Such input is invalid for swapping and hypergeometric
distribution (calling r2dtable) based algorithms.
This also applies to cases when the input is stratified into subsets.
Author(s)
Jari Oksanen and Peter Solymos
See Also
commsim, make.commsim,
permatfull, permatswap
Examples
data(mite)
x <- as.matrix(mite)[1:12, 21:30]
## 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))
## combining multiple simmat objects
## stratification
nm1 <- nullmodel(x[1:6,], "r00")
sm1 <- simulate(nm1, nsim=10)
nm2 <- nullmodel(x[7:12,], "r00")
sm2 <- simulate(nm2, nsim=10)
smbind(sm1, sm2, MARGIN=1)
## binding subsequent samples from sequential algorithms
## start, end, thin retained
nm <- nullmodel(x, "swap")
nm <- update(nm, nsim=10)
sm1 <- simulate(nm, nsim=10, thin=5)
sm2 <- simulate(nm, nsim=20, thin=5)
sm3 <- simulate(nm, nsim=10, thin=5)
smbind(sm3, sm2, sm1, MARGIN=3)
## 'replicate' based usage which is similar to the output
## of 'parLapply' or 'mclapply' in the 'parallel' package
## start, end, thin are set, also noting number of chains
smfun <- function(x, burnin, nsim, thin) {
nm <- nullmodel(x, "swap")
nm <- update(nm, nsim=burnin)
simulate(nm, nsim=nsim, thin=thin)
}
smlist <- replicate(3, smfun(x, burnin=50, nsim=10, thin=5), simplify=FALSE)
smbind(smlist, MARGIN=3) # Number of permuted matrices = 30
## Not run:
## parallel null model calculations
library(parallel)
if (.Platform$OS.type == "unix") {
## forking on Unix systems
smlist <- mclapply(1:3, function(i) smfun(x, burnin=50, nsim=10, thin=5))
smbind(smlist, MARGIN=3)
}
## socket type cluster, works on all platforms
cl <- makeCluster(3)
clusterEvalQ(cl, library(vegan))
clusterExport(cl, c("smfun", "x"))
smlist <- parLapply(cl, 1:3, function(i) smfun(x, burnin=50, nsim=10, thin=5))
stopCluster(cl)
smbind(smlist, MARGIN=3)
## End(Not run)
vegan documentation built on Sept. 11, 2024, 7:57 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| nullmodel | R Documentation |
Null Model and Simulation
Description
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).
smbind binds together multiple simmat objects.
Usage
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, ...)
smbind(object, ..., MARGIN, strict = TRUE)
Arguments
x |
A community matrix.
For the |
method |
Character, specifying one of the null model algorithms
listed on the help page of |
object |
An object of class |
nsim |
Positive integer, the number of simulated matrices to return.
For the |
seed |
An object specifying if and how the random number
generator should be initialized ("seeded").
Either |
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. |
MARGIN |
Integer, indicating the dimension over which multiple
|
strict |
Logical, if consistency of the time series attributes
( |
... |
Additional arguments supplied to algorithms.
In case of |
Details
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 smbind function can be used to combine multiple
simmat objects. This comes handy when null model
simulations are stratified by sites (MARGIN = 1)
or by species (MARGIN = 2), or in the case when
multiple objects are returned by identical/consistent settings
e.g. during parallel computations (MARGIN = 3).
Sanity checks are made to ensure that combining multiple
objects is sensible, but it is the user's responsibility
to check independence of the simulated matrices
and the null distribution has converged
in case of sequential null model algorithms.
The strict = FALSE setting can relax
checks regarding start, end, and thinning values
for sequential null models.
Value
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 |
state: |
current state of the permutations,
a matrix similar to the original.
It is |
iter: |
current number of iterations
for sequential algorithms.
It is |
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.
The smbind function returns an object of class simmat.
Note
Care must be taken when the input matrix only contains a single
row or column. Such input is invalid for swapping and hypergeometric
distribution (calling r2dtable) based algorithms.
This also applies to cases when the input is stratified into subsets.
Author(s)
Jari Oksanen and Peter Solymos
See Also
commsim, make.commsim,
permatfull, permatswap
Examples
data(mite)
x <- as.matrix(mite)[1:12, 21:30]
## 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))
## combining multiple simmat objects
## stratification
nm1 <- nullmodel(x[1:6,], "r00")
sm1 <- simulate(nm1, nsim=10)
nm2 <- nullmodel(x[7:12,], "r00")
sm2 <- simulate(nm2, nsim=10)
smbind(sm1, sm2, MARGIN=1)
## binding subsequent samples from sequential algorithms
## start, end, thin retained
nm <- nullmodel(x, "swap")
nm <- update(nm, nsim=10)
sm1 <- simulate(nm, nsim=10, thin=5)
sm2 <- simulate(nm, nsim=20, thin=5)
sm3 <- simulate(nm, nsim=10, thin=5)
smbind(sm3, sm2, sm1, MARGIN=3)
## 'replicate' based usage which is similar to the output
## of 'parLapply' or 'mclapply' in the 'parallel' package
## start, end, thin are set, also noting number of chains
smfun <- function(x, burnin, nsim, thin) {
nm <- nullmodel(x, "swap")
nm <- update(nm, nsim=burnin)
simulate(nm, nsim=nsim, thin=thin)
}
smlist <- replicate(3, smfun(x, burnin=50, nsim=10, thin=5), simplify=FALSE)
smbind(smlist, MARGIN=3) # Number of permuted matrices = 30
## Not run:
## parallel null model calculations
library(parallel)
if (.Platform$OS.type == "unix") {
## forking on Unix systems
smlist <- mclapply(1:3, function(i) smfun(x, burnin=50, nsim=10, thin=5))
smbind(smlist, MARGIN=3)
}
## socket type cluster, works on all platforms
cl <- makeCluster(3)
clusterEvalQ(cl, library(vegan))
clusterExport(cl, c("smfun", "x"))
smlist <- parLapply(cl, 1:3, function(i) smfun(x, burnin=50, nsim=10, thin=5))
stopCluster(cl)
smbind(smlist, MARGIN=3)
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.