4.4 Examples for each parameter
4.4.1 \(\mathbf{u}\), \(\mathbf{a}\) and \(\boldsymbol{\pi}\)
\(\mathbf{u}\), \(\mathbf{a}\) and \(\boldsymbol{\pi}\) are matrices with one column and the options for specifying their structures are the same. \(\mathbf{a}\) has one special option, "scaling" described below. The allowable structures are shown using \(\mathbf{u}\) as an example. Note that you should be careful about specifying shared structure in \(\boldsymbol{\pi}\) because you need to make sure the structure in \(\boldsymbol{\Lambda}\) matches. For example, if you require that all the \(\boldsymbol{\pi}\) values are shared (equal) then \(\boldsymbol{\Lambda}\) cannot be a diagonal matrix since that would be saying that the \(\boldsymbol{\pi}\) values are independent, which they are clearly not if you force them to be equal.
U=matrix(list(),m,1): This is the most general form and allows one to specify fixed and estimated elements in \(\mathbf{u}\). Each character string in \(\mathbf{u}\) is the name of one of the \(\mathbf{u}\) elements to be estimated. For example ifU=matrix(list(0.01,"u","u"),3,1), then \(\mathbf{u}\) in the model has the following structure: \[\begin{equation*} \left[ \begin{array}{c} 0.01 \\ u \\ u \end{array} \right] \end{equation*}\]U=matrix(c(),m,1), where the values inc()are all character strings: each character string is the name of an element to be estimated. For example ifU=matrix(c("u1","u1","u2"),3,1), then \(\mathbf{u}\) in the model has the following structure: \[\begin{equation*} \left[ \begin{array}{c} u_1 \\ u_1 \\ u_2 \end{array} \right] \end{equation*}\] with two values being estimated.U=matrix(list("u1","u1","u2"),3,1)has the same effect.U="unequal"orU="unconstrained": Both of these stings indicate that each element of \(\mathbf{u}\) is estimated. If \(m=3\), then \(\mathbf{u}\) would have the form: \[\begin{equation*} \left[ \begin{array}{c} u_1\\ u_2\\ u_3 \end{array} \right] \end{equation*}\]U="equal": There is only one value in \(\mathbf{u}\): \[\begin{equation*} \left[ \begin{array}{c} u \\ u \\ u \end{array} \right] \end{equation*}\]U=matrix(c(),m,1), where the values inc()are all numerical values: \(\mathbf{u}\) is fixed and has no estimated values. IfU=matrix(c(0.01,1,-0.5),3,1), then \(\mathbf{u}\) in the model is: \[\begin{equation*} \left[ \begin{array}{c} 0.01 \\ 1 \\ -0.5 \end{array} \right] \end{equation*}\]U=matrix(list(0.01,1,-0.5),3,1)would have the same effect.U="zero": \(\mathbf{u}\) is all zero: \[\begin{equation*} \left[ \begin{array}{c} 0 \\ 0 \\ 0 \end{array} \right] \end{equation*}\]
The \(\mathbf{a}\) parameter has a special option, "scaling", which is the default behavior. In this case, \(\mathbf{a}\) is treated like a scaling parameter. If there is only one \(\mathbf{y}\) row associated with an \(\mathbf{x}\) row, then the corresponding \(\mathbf{a}\) element is 0. If there are more than one \(\mathbf{y}\) rows associated with an \(\mathbf{x}\) row, then the first \(\mathbf{a}\) element is set to 0 and the others are estimated. For example, say \(m=2\) and \(n=4\) and \(\mathbf{Z}\) looks like the following:
\[\begin{equation*}
\mathbf{Z} =
\left[ \begin{array}{cc}
1 & 0 \\
1 & 0 \\
1 & 0 \\
0 & 1 \end{array} \right]
\end{equation*}\]
Then the 1st-3rd rows of \(\mathbf{y}\) are associated with the first row of \(\mathbf{x}\), and the 4th row of \(\mathbf{y}\) is associated with the last row of \(\mathbf{x}\). Then if \(\mathbf{a}\) is specified as "scaling", \(\mathbf{a}\) has the following structure:
\[\begin{equation*}
\left[ \begin{array}{c}
0 \\
a_1 \\
a_2 \\
0 \end{array} \right]
\end{equation*}\]
4.4.2 \(\mathbf{Q}\), \(\mathbf{R}\), \(\boldsymbol{\Lambda}\)
The possible \(\mathbf{Q}\), \(\mathbf{R}\), and \(\boldsymbol{\Lambda}\) model structures are identical, except that \(\mathbf{R}\) is \(n \times n\) while \(\mathbf{Q}\) and \(\boldsymbol{\Lambda}\) are \(m \times m\). All types of structures can be specified using a list matrix, but there are also text shortcuts for specifying common structures. The structures are shown using \(\mathbf{Q}\) as the example.
Q=matrix(list(),m,m): This is the most general way to specify the parameters and allows there to be fixed and estimated elements. Each character string in the list matrix is the name of one of the \(\mathbf{Q}\) elements to be estimated, and each numerical value is a fixed value. For example if
Q=matrix(list("s2a",0,0,0,"s2a",0,0,0,"s2b"),3,3)then \(\mathbf{Q}\) has the following structure:
\[\begin{equation*}
\left[ \begin{array}{ccc}
\sigma^2_a & 0 & 0\\
0 & \sigma^2_a & 0 \\
0 & 0 & \sigma^2_b \end{array} \right]
\end{equation*}\]
Note that diag(c("s2a","s2a","s2b")) will not have the desired effect of producing a matrix with numeric 0s on the off-diagonals. It will have character 0s and MARSS() will interpret "0" as the name of an element of \(\mathbf{Q}\) to be estimated. Instead, the following two lines can be used:
Q <- matrix(list(0),3,3)
diag(Q)=c("s2a","s2a","s2b")Q="diagonal and equal": There is only one process variance value in this case: \[\begin{equation*} \left[ \begin{array}{ccc} \sigma^2 & 0 & 0\\ 0 & \sigma^2 & 0 \\ 0 & 0 & \sigma^2 \end{array} \right] \end{equation*}\]Q="diagonal and unequal": There are \(m\) process variance values in this case:
\[\begin{equation*} \left[ \begin{array}{ccc} \sigma^2_1 & 0 & 0\\ 0 & \sigma^2_2 & 0 \\ 0 & 0 & \sigma^2_3 \end{array} \right] \end{equation*}\]Q="unconstrained": There are values on the diagonal and the off-diagonals of \(\mathbf{Q}\) and the variances and covariances are all different:
\[\begin{equation*} \left[ \begin{array}{ccc} \sigma^2_1 & \sigma_{1,2} & \sigma_{1,3}\\ \sigma_{1,2} & \sigma^2_2 & \sigma_{2,3} \\ \sigma_{1,3} & \sigma_{2,3} & \sigma^2_3 \end{array} \right] \end{equation*}\] There are \(m\) process variances and \((m^2-m)/2\) covariances in this case, so \((m^2+m)/2\) values to be estimated. Note that variance-covariance matrices are never truly unconstrained since the upper and lower triangles of the matrix must be equal.Q="equalvarcov": There is one process variance and one covariance: \[\begin{equation*} \left[ \begin{array}{ccc} \sigma^2 & \beta & \beta\\ \beta & \sigma^2 & \beta \\ \beta & \beta & \sigma^2 \end{array} \right] \end{equation*}\]Q=matrix(c(), m, m), where all values inc()are character strings: Each element in \(\mathbf{Q}\) is estimated and each character string is the name of a value to be estimated. Note if \(m=1\), you still need to wrap its value inmatrix()so that its class is matrix. You must be careful that your \(\mathbf{Q}\) specifies a statistically valid variance-covariance matrix.MARSS()will throw an error/warning telling you if it is not valid.Q=matrix(c(), m, m), where all values inc()are numeric values: Each element in \(\mathbf{Q}\) is fixed to the values in the matrix.Q="identity": The \(\mathbf{Q}\) matrix is the identity matrix: \[\begin{equation*} \left[ \begin{array}{ccc} 1 & 0 & 0\\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{array} \right] \end{equation*}\]Q="zero": The \(\mathbf{Q}\) matrix is all zeros: \[\begin{equation*} \left[ \begin{array}{ccc} 0 & 0 & 0\\ 0 & 0 & 0 \\ 0 & 0 & 0 \end{array} \right] \end{equation*}\]
Be careful when setting \(\boldsymbol{\Lambda}\) model structures. Mis-specifying the structure of \(\boldsymbol{\Lambda}\) can have catastrophic, but difficult to discern, effects on your estimates. The default behavior for \(\boldsymbol{\Lambda}\) is safe because it eliminates \(\boldsymbol{\Lambda}\) from the model. However, MARSS models in the literature often use a diffuse diagonal \(\boldsymbol{\Lambda}\), and you must be cautious when using that for general MARSS models. It can lead to mis-specification. What does “mis-specifying” mean? It means your \(\boldsymbol{\Lambda}\) matrix which specifies the variance-covariance structure of the initial \(\mathbf{x}\) is fundamentally inconsistent with your model. For example if \(\mathbf{B}\) has off-diagonal elements, then \(\boldsymbol{\Lambda}\) diagonal (diffuse or otherwise) is inconsistent with your model.
4.4.3 \(\mathbf{B}\)
Like the variance-covariance matrices (\(\mathbf{Q}\), \(\mathbf{R}\) and \(\boldsymbol{\Lambda}\)), \(\mathbf{B}\) can be specified with a list matrix to allow you to have both fixed and shared elements in the \(\mathbf{B}\) matrix. Character matrices and matrices with fixed values operate the same way as for the variance-covariance matrices. In addition, the same text shortcuts are available: "unconstrained", "identity", "diagonal and equal", "diagonal and unequal", "equalvarcov", and "zero". A fixed \(\mathbf{B}\) can be specified with a numeric matrix, but all eigenvalues must fall within the unit circle; meaning all(abs(eigen(B)\$values)<=1) must be true.
4.4.4 \(\mathbf{Z}\)
Like \(\mathbf{B}\) and the variance-covariance matrices, \(\mathbf{Z}\) can be specified with a list matrix to allow you to have both fixed and estimated elements in \(\mathbf{Z}\). If \(\mathbf{Z}\) is a square matrix, many of the same text shortcuts are available: "diagonal and equal", "diagonal and equal", and "equalvarcov". If \(\mathbf{Z}\) is a design matrix (a matrix with only 0s and 1s and where the row sums are all equal to 1), then a special shortcut is available using factor() which allows you to specify which \(\mathbf{y}\) rows are associated with which \(\mathbf{x}\) rows.
Z=factor(c(1,1,1)): All \(\mathbf{y}\) time series are observing the same (and only) hidden state trajectory \(x\) (\(n=3\) and \(m=1\)): \[\begin{equation*} \mathbf{Z} = \left[ \begin{array}{c} 1 \\ 1 \\ 1 \end{array} \right] \end{equation*}\]Z=factor(c(1,2,3)): Each time series in \(\mathbf{y}\) corresponds to a different hidden state trajectory. This is the default \(\mathbf{Z}\) model and in this case \(n=m\): \[\begin{equation*} \mathbf{Z} = \left[ \begin{array}{ccc} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{array} \right] \end{equation*}\]Z=factor(c(1,1,2)): The first two time series in \(\mathbf{y}\) corresponds to one hidden state trajectory and the third \(\mathbf{y}\) time series corresponds to a different hidden state trajectory. Here \(n=3\) and \(m=2\): \[\begin{equation*} \mathbf{Z} = \left[ \begin{array}{cc} 1 & 0 \\ 1 & 0 \\ 0 & 1 \end{array} \right] \end{equation*}\] The \(\mathbf{Z}\) model can be specified using either numeric or character factor levels.c(1,1,2)is the same asc("north","north","south").Z="identity": This is the default behavior. This means \(\mathbf{Z}\) is a \(n \times n\) identity matrix and \(m=n\). If \(n=3\), it is the same asZ=factor(c(1,2,3)).Z=matrix(c(), n, m), where the elements inc()are all character strings: Passing in a \(n \times m\) character matrix, means that each character string is a value to be estimated. Be careful that you are specifying an identifiable model when using this option.Z=matrix(c(), n, m), where the elements inc()are all numeric: Passing in a \(n \times m\) numeric matrix means that \(\mathbf{Z}\) is fixed to the values in the matrix. The matrix must be numeric but it does not need to be a design matrix.Z=matrix(list(), n, m): Passing in a \(n \times m\) list matrix allows you to combine fixed and estimated values in the \(\mathbf{Z}\) matrix. Be careful that you are specifying an identifiable model.Zfor dynamic linear models (DLM). In this case, you covariates will appear in the \(\mathbf{Z}\) matrix and \(\mathbf{Z}\) will be time-varying. Your regression coefficients appear in the \(\mathbf{x}\) part of the model. For example, for a DLM with a time-varying intercept and regression coefficient, yourZwould look like.Temp <- rnorm(10) Z <- array(1, dim=c(1, 2, 10)) Z[,2,] <- Temp