mxExpectationStateSpace {OpenMx}

Create an MxExpectationStateSpace Object

Description

This function creates a new MxExpectationStateSpace object.

Usage

mxExpectationStateSpace(A, B, C, D, Q, R, x0, P0, u,
                        dimnames = NA, thresholds = deprecated(),
                        threshnames = deprecated(),
                        ..., t = NA, scores=FALSE)

Arguments

A

A character string indicating the name of the 'A' matrix.

B

A character string indicating the name of the 'B' matrix.

C

A character string indicating the name of the 'C' matrix.

D

A character string indicating the name of the 'D' matrix.

Q

A character string indicating the name of the 'Q' matrix.

R

A character string indicating the name of the 'R' matrix.

x0

A character string indicating the name of the 'x0' matrix.

P0

A character string indicating the name of the 'P0' matrix.

u

A character string indicating the name of the 'u' matrix.

dimnames

An optional character vector to be assigned to the row names of the 'C' matrix.

thresholds

threshnames

...

Unused. Requires further arguments to be named.

t

Not to be used

scores

Not to be used

Details

This page presents details for both the mxExpectationStateSpace function and for state space modeling generally; however, for much more information on state space modeling see the paper by Hunter (2018) listed under references. Authors using state space modeling in OpenMx should cite Hunter (2018).

Expectation functions define the way that model expectations are calculated. When used in conjunction with the mxFitFunctionML, the mxExpectationStateSpace uses maximum likelihood prediction error decomposition (PED) to obtain estimates of free parameters in a model of the raw 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 hybrid Kalman filter (combination of classical Kalman and Kalman-Bucy filters) for continuous latent time with discrete observations is implemented and is available as mxExpectationStateSpaceContinuousTime. 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, and Rauch-Tung-Striebel smoother for updating forecast state estimates after a complete forward pass through the data has been made.

Missing data handling is implemented in the same fashion as full information maximum likelihood for partially missing rows of data. Additionally, completely missing rows of data are handled by only using the prediction step from the Kalman filter and omitting the update step.

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 MxMatrix or MxAlgebraobjects 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.

x_t = A x_{t-1} + B u_t + q_t

y_t = C x_t + D u_t + r_t

with q_t and r_t both independently and identically distributed random Gaussian (normal) variables with mean zero and covariance matrices Q and 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.

Note that the covariates, u, have "instantaneous" effects on both the state and output equations. If lagged effects are desired, then the user must create a lagged covariate by shifting their observed variable to the desired lag.

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 t is

S_{t} = C ( A P_{t-1} A^{\sf T} + Q ) C^{\sf T} + R

The expected means vector of row t is

\hat{y}_{t} = C x_{t} + D u_{t}

The 'dimnames' arguments takes an optional character vector.

The 'A' argument refers to the A matrix in the State Space approach. This matrix consists of time regressive coefficients from the latent variable in column j at time t-1 to the latent variable in row i at time t. Entries in the diagonal are autoregressive coefficients. Entries in the off-diagonal are cross-lagged regressive coefficients. If the A and B matrices are zero matrices, then the state space model reduces to a factor analysis. The A matrix is sometimes called the state-transition model.

The 'B' argument refers to the B matrix in the State Space approach. This matrix consists of regressive coefficients from the input (manifest covariate) variable j at time t to the latent variable in row i at time t. Note that the covariate effect is contemporaneous: the covariate at time t has influence on the latent state also at time t. A lagged effect can be created by lagged the observed variable. The B matrix is sometimes called the control-input model.

The 'C' argument refers to the C matrix in the State Space approach. This matrix consists of contemporaneous regression coefficients from the latent variable in column j to the observed variable in row i. This matrix is directly analogous to the factor loadings matrix in LISREL and Mplus models. The C matrix is sometimes called the observation model.

The 'D' argument refers to the D matrix in the State Space approach. This matrix consists of contemporaneous regressive coefficients from the input (manifest covariate) variable j to the observed variable in row i. The D matrix is sometimes called the feedthrough or feedforward matrix.

The 'Q' argument refers to the 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 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 C matrix, or fixing some factor variances in the Q matrix.

The 'R' argument refers to the 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 R matrix is the covariance of the observation noise.

The 'x0' argument refers to the 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 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 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 x_0. That is, the P_0 matrix gives the covariance of x_0 - xtrue_0 where xtrue_0 is the vector of true initial values. P_0 is a measure of the accuracy of the initial 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 x_0 matrix, these starting values are often difficult to choose.

The 'u' argument refers to the u matrix in the State Space approach. This matrix consists of the inputs or manifest covariates of the state space expectation. The u matrix must be a column vector with the same number of rows as the B and D matrices have columns. If no inputs are desired, u can be a zero matrix. If time-varying inputs are desired, then they should be included as columns in the MxData object and referred to in the labels of the u matrix as definition variables. There is an example of this below.

The 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 mxRun function.

mxExpectationStateSpace evaluates with respect to an MxData object. The MxData object need not be referenced in the mxExpectationStateSpace function, but must be included in the MxModel object. mxExpectationStateSpace requires that the 'type' argument in the associated MxData object be equal to 'raw'. Neighboring rows of the MxData object are treated as adjacent, equidistant time points increasing from the first to the last row.

To evaluate, place mxExpectationStateSpace objects, the mxData object for which the expected covariance approximates, referenced MxAlgebra and MxMatrix objects, and optional MxBounds and MxConstraint objects in an MxModel object. This model may then be evaluated using the mxRun function. The results of the optimization can be found in the 'output' slot of the resulting model, and may be obtained using the mxEval function.

Value

Returns a new MxExpectationStateSpace object. mxExpectationStateSpace objects should be included with models with referenced MxAlgebra, MxData and MxMatrix objects.

References

K.J. Åström and R.M. Murray (2010). Feedback Systems: An Introduction for Scientists and Engineers. Princeton University Press.

J. Durbin and S.J. Koopman. (2001). Time Series Analysis by State Space Methods. Oxford University Press.

Hunter, M.D. (2018). State Space Modeling in an Open Source, Modular, Structural Equation Modeling Environment. Structural Equation Modeling: A Multidisciplinary Journal, 25(2), 307-324. DOI: 10.1080/10705511.2017.1369354

R.E. Kalman (1960). A New Approach to Linear Filtering and Prediction Problems. Basic Engineering, 82, 35-45.

G. Petris (2010). An R Package for Dynamic Linear Models. Journal of Statistical Software, 36, 1-16.

The OpenMx User's guide can be found at https://openmx.ssri.psu.edu/documentation/.

See Also

mxExpectationStateSpaceContinuousTime

Examples

# Create and fit a model using mxMatrix, mxExpectationStateSpace, and mxFitFunctionML
require(OpenMx)
data(demoOneFactor)
nvar <- ncol(demoOneFactor)
varnames <- colnames(demoOneFactor)
ssModel <- mxModel(model="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(varnames, "F1")),
    mxMatrix("Zero", nvar, 1, name="D"),
    mxMatrix("Diag", 1, 1, FALSE, 1, name="Q"),
    mxMatrix("Diag", nvar, nvar, TRUE, .2, name="R"),
    mxMatrix("Zero", 1, 1, name="x0"),
    mxMatrix("Diag", 1, 1, FALSE, 1, name="P0"),
    mxMatrix("Zero", 1, 1, name="u"),
    mxData(observed=demoOneFactor[1:100,], type="raw"),#fewer rows = fast
    mxExpectationStateSpace("A", "B", "C", "D", "Q", "R", "x0", "P0", "u"),
    mxFitFunctionML()
)
ssRun <- mxRun(ssModel)
summary(ssRun)
# Note the freely estimated Autoregressive parameter (A matrix)
#  is near zero as it should be for the independent rows of data
#  from the factor model.

# Create and fit a model with INPUTS using mxMatrix, mxExpectationStateSpace, and mxFitFunctionML
require(OpenMx)
data(demoOneFactor)
nvar <- ncol(demoOneFactor)
varnames <- colnames(demoOneFactor)
#demoOneFactorInputs <- cbind(demoOneFactor, V1=rep(1, nrow(demoOneFactor)))
demoOneFactorInputs <- cbind(demoOneFactor, V1=rnorm(nrow(demoOneFactor)))
ssModel <- mxModel(model="State Space Inputs Manual Example",
    mxMatrix("Full", 1, 1, TRUE, .3, name="A"),
    mxMatrix("Full", 1, 1, TRUE, values=1, name="B"),
    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"),
    mxMatrix("Zero", 1, 1, name="x0"),
    mxMatrix("Diag", 1, 1, FALSE, 1, name="P0"),
    mxMatrix("Full", 1, 1, FALSE, labels="data.V1", name="u"),
    mxData(observed=demoOneFactorInputs[1:100,], type="raw"),#fewer rows = fast
    mxExpectationStateSpace("A", "B", "C", "D", "Q", "R", "x0", "P0", u="u"),
    mxFitFunctionML()
)
ssRun <- mxRun(ssModel)
summary(ssRun)
# Note the freely estimated Autoregressive parameter (A matrix)
#  and the freely estimated Control-Input parameter (B matrix)
#  are both near zero as they should be for the independent rows of data
#  from the factor model that does not have inputs, covariates,
#  or exogenous variables.