Simulate the process component of a TVVARSS model

simTVVAR simulates the process (state) component of a TVVARSS model.

simTVVAR(
  Bt = NULL,
  topo = NULL,
  TT,
  var_QX,
  cov_QX,
  var_QB,
  cov_QB = 0,
  QQ_XX = NULL,
  QQ_BB = NULL,
  X0 = NULL,
  CC = NULL,
  cc = NULL
)

Arguments

Bt	A matrix describing the topology of the food web (see 'Details'). If `Bt == NULL`, then the food web topology must be specified and passed as `topo`. See 'Details'.
topo	Optional list matrix describing the presumed topology of the community. Pairwise interactions are specified as density-dependent ("dd"), top-down ("td"), bottom-up ("bu"), competitive/facilitative ("cf"), or absent ("zero"). If specified, pairwise interactions will be constrained in an approporiate manner (e.g., top-down effects are between -1 and 0).
TT	Number of time steps to simulate.
var_QX	Scalar or vector of variances for process errors of states.
cov_QX	Covariance, if any, of the process errors of the states; if `cov_QX` > 0, then `var_QX` must be a scalar.
var_QB	Scalar or vector of variances for process errors of B.
cov_QB	Covariance, if any, of process errors of B; if `cov_QB` > 0, then `var_QB` must be a scalar.
QQ_XX	Optionally specify the explicit form for the var-cov matrix Q of the process errors of the states.
QQ_BB	Optionally specify the explicit form for the var-cov matrix Q of the process errors of B.
X0	Optionally specify vector of initial states; `nrow(X0)` must equal `nrow(Bt)`.
CC	Optionally specify matrix of covariate effects on states.
cc	Optionally specify matrix of covariates.

Value

A list with the following components:

B_mat: An array of the B matrix over time; dim(B_mat) = c(n,n,T+1).
WW_BB: The process errors for B; dim(WW_BB) = c(n^2,T).
QQ_BB: Variance-covariance matrix of the process errors for B; dim(QQ_BB) = c(n^2,n^2).
states: A matrix of the states over time; dim(states) = c(n,T+1).
WW_XX: The process errors (innovations) for the states; dim(WW_XX) = c(n,T).
QQ_XX: Variance-covariance matrix of the process errors for the states; dim(QQ_XX) = c(n,n).
call: The function call as returned by match.call().

Details

Bt can be used in one of two ways when simulating a TVVAR model:

An \(n x n\) matrix with initial numeric values of B (i.e., B0). If QQ_BB = matrix(0, n, n) then, a time-invariant (MARSS) model is simulated based on these values.
An \(n x n x (T+1)\) array with actual values of B for each time step, including B0. This is useful for simulating multiple realizations of the same process.

topo can be used to specify the food web topology by passing an \(n x n\) matrix with a combination of character and numeric values in the off-diagonal elements; the diagonal should always contain "dd" as density-dependence is implicit in this model. Use 0 or "zero" to indicate no interaction and the following character codes for ecological interactions:

"td" to indicate a top-down interaction
"bu" to indicate a bottom-up interaction
"cf" to indicate a competitive/facilitative interaction

See 'Examples' for details on formatting B0.

Examples

# set.seed(123)
# ## number of time steps
# TT <- 30
# ## number of spp/guilds
# nn <- 4
# ## CASE 1: linear food chain; starting values are random
# B0_lfc <- matrix(list(0),nn,nn)
# diag(B0_lfc) <- "dd"
# for(i in 1:(nn-1)) {
#   B0_lfc[i,i+1] <- "td"
#   B0_lfc[i+1,i] <- "bu"
# }
# ## inspect B0
# B0_lfc
# ## simulate & plot states
# lfc <- simTVVAR(Bt=NULL,topo=B0_lfc,TT=TT,var_QX=rev(seq(1,4)/40),cov_QX=0,var_QB=0.05,cov_QB=0)
# matplot(t(lfc$states),type="l")
#
# ## CASE 2: 1 consumer & n-1 producers; starting values are random
# B0_cp <- matrix(list("cf"),nn,nn)
# B0_cp[1:(nn-1),nn] <- "td"
# B0_cp[nn,1:(nn-1)] <- "bu"
# diag(B0_cp) <- "dd"
# ## inspect B0
# B0_cp
# ## simulate & plot states
# cp <- simTVVAR(Bt=NULL,topo=B0_lfc,TT=TT,var_QX=rev(seq(1,4)/40),cov_QX=0,var_QB=0.05,cov_QB=0)
# matplot(t(cp$states),type="l")
#
# ## simulate a second realization of CASE 2 using same B
# cp2 <- simTVVAR(Bt=cp$B_mat,topo=B0_lfc,TT=TT,var_QX=rev(seq(1,4)/40),cov_QX=0,var_QB=0.05,cov_QB=0)