From 7cb24e5f578a15813c9bb2c26014964f6e920399 Mon Sep 17 00:00:00 2001
From: mhunter
Date: Fri, 20 Sep 2013 07:10:07 +0000
Subject: [PATCH] Finished man page for state space expectations.
gitsvnid: http://openmx.psyc.virginia.edu/svn/trunk@2897 df83fd304cca4c36ab9de8b5583ccbd1

man/mxExpectationStateSpace.Rd  52 +++++++++++++++++++++++++++
1 file changed, 33 insertions(+), 19 deletions()
diff git a/man/mxExpectationStateSpace.Rd b/man/mxExpectationStateSpace.Rd
index 2ae0657..3cfe350 100644
 a/man/mxExpectationStateSpace.Rd
+++ b/man/mxExpectationStateSpace.Rd
@@ 45,48 +45,55 @@ mxExpectationStateSpace(A="A", B="B", C="C", D="D", Q="Q", R="R", x0="x0", P0="P
\details{
Expectation functions define the way that model expectations are calculated. When used in conjunction with the \link{mxFitFunctionML}, the mxExpectationStateSpace uses maximum likelihood prediction error decomposition (PED) to obtain estimates of free parameters in a model of the raw \link{MxData} object. State space expectations treat the raw data as a multivariate time series of equally spaced times with each row corresponding to a single occasion. This is not a model of the block Toeplitz lagged autocovariance matrix. State space expectations implement a classical Kalman filter to produce expectations.
The following are not yet implemented: square root Kalman filter (in Cholesky or singular value decomposition form), extended Kalman filter for linear approximations to nonlinear state space models, unscented Kalman filter for highly nonlinear state space models, KalmanBucy filter for continuous time modeling, hybrid Kalman filter for continuous latent time with discrete observations, and RauchTungStriebel smoother for updating forecast state estimates after a complete forward pass through the data has been made.
+The following alternative filters are not yet implemented: square root Kalman filter (in Cholesky or singular value decomposition form), extended Kalman filter for linear approximations to nonlinear state space models, unscented Kalman filter for highly nonlinear state space models, KalmanBucy filter for continuous time modeling, hybrid Kalman filter for continuous latent time with discrete observations, and RauchTungStriebel smoother for updating forecast state estimates after a complete forward pass through the data has been made.
+
+Also not fully implemented is missing data handling.
This model uses notation for the model matrices commonly found in engineering and control theory.
 The 'A', 'B', 'C', 'D', 'Q', 'R', 'x0', and 'P0' arguments must be the names of \link{MxMatrix} objects with the associated properties of the A, B, C, D, Q, R, x0, and P0 matrices in the state space modeling approach.
+ The 'A', 'B', 'C', 'D', 'Q', 'R', 'x0', and 'P0' arguments must be the names of \link{MxMatrix} or \link{MxAlgebra}objects with the associated properties of the A, B, C, D, Q, R, x0, and P0 matrices in the state space modeling approach.
The state space expectation is defined by the following model equations.
\deqn{x_{t+1} = A x_t + B u_t + q_t}
\deqn{y_t = C x_t + D u_t + r_t}
+\deqn{x_{t+1} = A x_t + B u_t + q_t}{x[t+1] = A x[t] + B u[t] + q[t]}
+\deqn{y_t = C x_t + D u_t + r_t}{y[t] = C x[t] + D u[t] + r[t]}
+with \eqn{q_t}{q[t]} and \eqn{r_t}{r[t]} both independently and identically distributed random Gaussian (normal) variables with mean zero and covariance matrices \eqn{Q} and \eqn{R}, respectively.
The first equation is called the state equation. It describes how the latent states change over time. Also, the state equation in state space modeling is directly analogous to the structural model in LISREL structural equation modeling.
The second equation is called the output equation. It describes how the latent states relate to the observed states at a single point in time. The output equation shows how the observed output is produced by the latent states. Also, the output equation in state space modeling is directly analogous to the measurement model in LISREL structural equation modeling.
The state and output equations, together with some minimal assumptions, imply ... covariance and means
+The state and output equations, together with some minimal assumptions and the Kalman filter, imply a new expected covariance matrix and means vector for every row of data. The expected covariance matrix of row \eqn{t+1} is
+
+\deqn{S_{t+1} = C ( A P_{t} A^{\sf T} + Q ) C^{\sf T} + R}{S[t+1] = C ( A P[t] A^T + Q ) C^T + R}
+
+The expected means vector of row \eqn{t+1} is
+
+\deqn{\hat{y}_{t+1} = C x_t + D u_t}{yhat[t+1] = C x[t] + D u[t]}
The 'dimnames' arguments takes an optional character vector. % TODO: Decide how dimnames are handled.
%If this argument is not a single NA, then this vector be assigned to be the row names of the 'C' matrix and optionally to the '?' matrix, if the '?' matrix exists.
THE NEXT PART IS INCOMPLETE. MIKE HUNTER NEEDS TO FINISH THIS PART.

The 'A' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'A' argument refers to the \eqn{A} matrix in the State Space approach. This matrix consists of time regressive coefficients from the latent variable in column \eqn{j} at time \eqn{t} to the latent variable in row \eqn{i} at time \eqn{t+1}. Entries in the diagonal are autoregressive coefficient. Entries in the offdiagonal are crosslagged regressive coefficients. If the \eqn{A} and \eqn{B} matrices are zero matrices, then the state space model reduces to a factor analysis. The \eqn{A} matrix is sometimes called the statetransition model.
The 'B' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'B' argument refers to the \eqn{B} matrix in the State Space approach. This matrix consists of time regressive coefficients from the input (manifest covariate) variable \eqn{j} at time \eqn{t} to the latent variable in row \eqn{i} at time \eqn{t+1}. The \eqn{B} matrix is sometimes called the controlinput model.
The 'C' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'C' argument refers to the \eqn{C} matrix in the State Space approach. This matrix consists of contemporaneous regression coefficients from the latent variable in column \eqn{j} to the observed variable in row \eqn{i}. This matrix is directly analogous to the factor loadings matrix in LISREL and Mplus models. The \eqn{C} matrix is sometimes called the observation model.
The 'D' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'D' argument refers to the \eqn{D} matrix in the State Space approach. This matrix consists of contemporaneous regressive coefficients from the input (manifest covariate) variable \eqn{j} to the observed variable in row \eqn{i}. The \eqn{D} matrix is sometimes called the feedthrough or feedforward matrix.
The 'Q' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'Q' argument refers to the \eqn{Q} matrix in the State Space approach. This matrix consists of residual covariances among the latent variables. This matrix must be symmetric. As a special case, it is often diagonal. The \eqn{Q} matrix is the covariance of the process noise. Just as in factor analysis and general structural equation modeling, the scale of the latent variables is usually set by fixing some factor loadings in the \eqn{C} matrix, or fixing some factor variances in the \eqn{Q} matrix.
The 'R' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'R' argument refers to the \eqn{R} matrix in the State Space approach. This matrix consists of residual covariances among the observed (manifest) variables. This matrix must be symmetric As a special case, it is often diagonal. The \eqn{R} matrix is the covariance of the observation noise.
The 'x0' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'x0' argument refers to the \eqn{x_0}{x[0]} matrix in the State Space approach. This matrix consists of the column vector of the initial values for the latent variables. The state space expectation uses the \eqn{x_0}{x[0]} matrix as the starting point to recursively estimate the latent variables' values at each time. These starting values can be difficult to pick, however, for sufficiently long time series they often do not greatly impact the estimation.
The 'P0' argument refers to the A matrix in the State Space approach. This matrix consists of .
+The 'P0' argument refers to the \eqn{P_0}{P[0]} matrix in the State Space approach. This matrix consists of the initial values of the covariances of the error in the initial latent variable estimates given in \eqn{x_0}{x[0]}. That is, the \eqn{P_0}{P[0]} matrix gives the covariance of \eqn{x_0  xtrue_0}{x[0]  xtrue[0]} where \eqn{xtrue_0}{xtrue[0]} is the vector of true initial values. \eqn{P_0}{P[0]} is a measure of the accuracy of the intial latent state estimates. The Kalman filter uses this initial covariance to recursively generated a new covariance for each time point based on the previous time point. The Kalman filter updates this covariance so that it is as small as possible (minimum trace). Similar to the \eqn{x_0}{x[0]} matrix, these starting values are often difficult to choose.
The \link{MxMatrix} objects included as arguments may be of any type, but should have the properties described above. The mxExpectationStateSpace will not return an error for incorrect specification, but incorrect specification will likely lead to estimation problems or errors in the \link{mxRun} function.
mxExpectationStateSpace evaluates with respect to an \link{MxData} object. The \link{MxData} object need not be referenced in the mxExpectationStateSpace function, but must be included in the \link{MxModel} object. mxExpectationStateSpace requires that the 'type' argument in the associated \link{MxData} object be equal to 'cov' or 'cor'.
+mxExpectationStateSpace evaluates with respect to an \link{MxData} object. The \link{MxData} object need not be referenced in the mxExpectationStateSpace function, but must be included in the \link{MxModel} object. mxExpectationStateSpace requires that the 'type' argument in the associated \link{MxData} object be equal to 'raw'. Neighboring rows of the \link{MxData} object are treated as adjacent, equidistant time points increasing from the first to the last row.
To evaluate, place mxExpectationStateSpace objects, the \link{mxData} object for which the expected covariance approximates, referenced \link{MxAlgebra} and \link{MxMatrix} objects, and optional \link{MxBounds} and \link{MxConstraint} objects in an \link{MxModel} object. This model may then be evaluated using the \link{mxRun} function. The results of the optimization can be found in the 'output' slot of the resulting model, and may be obtained using the \link{mxEval} function..
}
@@ 95,8 +102,15 @@ To evaluate, place mxExpectationStateSpace objects, the \link{mxData} object for
Returns a new MxExpectationStateSpace object. mxExpectationStateSpace objects should be included with models with referenced \link{MxAlgebra}, \link{MxData} and \link{MxMatrix} objects.
}
+
\references{
McArdle, J. J. and MacDonald, R. P. (1984). Some algebraic properties of the Reticular Action Model for moment structures. \emph{British Journal of Mathematical and Statistical Psychology, 37,} 234251.
+K.J. \ifelse{latex}{\out{\rAstr\"om}}{\ifelse{html}{\out{Åström}}{Astrom}} and R.M. Murray (2010). \emph{ Feedback Systems: An Introduction for Scientists and Engineers}. Princeton University Press.
+
+J. Durbin and S.J. Koopman. (2001). \emph{Time Series Analysis by State Space Methods}. Oxford University Press.
+
+R.E. Kalman (1960). A New Approach to Linear Filtering and Prediction Problems. \emph{Basic Engineering, 82}, 3545.
+
+G. Petris (2010). An R Package for Dynamic Linear Models. \emph{Journal of Statistical Software, 36}, 116.
The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
}
@@ 108,11 +122,11 @@ The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/document
require(OpenMx)
data(demoOneFactor)
nvar < ncol(demoOneFactor)
+varnames < colnames(demoOneFactor)
ssModel < mxModel(name="State Space Manual Example",
mxMatrix("Full", 1, 1, TRUE, .3, name="A"),
mxMatrix("Zero", 1, 1, name="B"),
 mxMatrix("Full", nvar, 1, TRUE, .6, name="C", dimnames=list(colnames(demoOneFactor)
, "F1")),
+ mxMatrix("Full", nvar, 1, TRUE, .6, name="C", dimnames=list(varnames, "F1")),
mxMatrix("Zero", nvar, 1, name="D"),
mxMatrix("Diag", 1, 1, FALSE, 1, name="Q"),
mxMatrix("Diag", nvar, nvar, TRUE, .2, name="R"),

2.1.4