Update state space documentation and adjust data sorting to the nuclear option.
[openmx:openmx.git] / man / mxExpectationStateSpace.Rd
1 %
2 %   Copyright 2007-2013 The OpenMx Project
3 %
4 %   Licensed under the Apache License, Version 2.0 (the "License");
5 %   you may not use this file except in compliance with the License.
6 %   You may obtain a copy of the License at
7
8 %        http://www.apache.org/licenses/LICENSE-2.0
9
10 %   Unless required by applicable law or agreed to in writing, software
11 %   distributed under the License is distributed on an "AS IS" BASIS,
12 %   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 %   See the License for the specific language governing permissions and
14 %   limitations under the License.
15
16 \name{mxExpectationStateSpace}
17 \alias{mxExpectationStateSpace}
18
19 \title{Create an MxExpectationStateSpace Object}
20
21 \description{
22 This function creates a new MxExpectationStateSpace object.
23 }
24
25 \usage{
26 mxExpectationStateSpace(A="A", B="B", C="C", D="D", Q="Q", R="R", x0="x0", P0="P0", 
27                         dimnames = NA, thresholds = NA, threshnames = dimnames)
28 }
29
30
31 \arguments{
32    \item{A}{A character string indicating the name of the 'A' matrix.}
33    \item{B}{A character string indicating the name of the 'B' matrix.}
34    \item{C}{A character string indicating the name of the 'C' matrix.}
35    \item{D}{A character string indicating the name of the 'D' matrix.}
36    \item{Q}{A character string indicating the name of the 'Q' matrix.}
37    \item{R}{A character string indicating the name of the 'R' matrix.}
38    \item{x0}{A character string indicating the name of the 'x0' matrix.}
39    \item{P0}{A character string indicating the name of the 'P0' matrix.}
40    \item{dimnames}{An optional character vector to be assigned to the column names of the 'F' and 'M' matrices.}   
41    \item{thresholds}{An optional character string indicating the name of the thresholds matrix.}
42    \item{threshnames}{An optional character vector to be assigned to the column names of the thresholds matrix.}
43 }
44
45 \details{
46 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.
47
48 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, Kalman-Bucy filter for continuous time modeling, hybrid Kalman filter for continuous latent time with discrete observations, and Rauch-Tung-Striebel smoother for updating forecast state estimates after a complete forward pass through the data has been made.
49
50 This model uses notation for the model matrices commonly found in engineering and control theory.  
51
52  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.
53
54 The state space expectation is defined by the following model equations.
55
56 \deqn{x_{t+1} = A x_t + B u_t + q_t}
57 \deqn{y_t = C x_t + D u_t + r_t}
58
59 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.
60
61 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.
62
63 The state and output equations, together with some minimal assumptions, imply ... covariance and means
64
65 The 'dimnames' arguments takes an optional character vector.  % TODO: Decide how dimnames are handled.
66 %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.
67
68 THE NEXT PART IS INCOMPLETE.  MIKE HUNTER NEEDS TO FINISH THIS PART.
69
70 The 'A' argument refers to the A matrix in the State Space approach. This matrix consists of . 
71
72 The 'B' argument refers to the A matrix in the State Space approach. This matrix consists of . 
73
74 The 'C' argument refers to the A matrix in the State Space approach. This matrix consists of . 
75
76 The 'D' argument refers to the A matrix in the State Space approach. This matrix consists of . 
77
78 The 'Q' argument refers to the A matrix in the State Space approach. This matrix consists of . 
79
80 The 'R' argument refers to the A matrix in the State Space approach. This matrix consists of . 
81
82 The 'x0' argument refers to the A matrix in the State Space approach. This matrix consists of . 
83
84 The 'P0' argument refers to the A matrix in the State Space approach. This matrix consists of . 
85
86
87 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.
88
89 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'.
90
91 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..
92 }
93
94 \value{
95     Returns a new MxExpectationStateSpace object. mxExpectationStateSpace objects should be included with models with referenced \link{MxAlgebra}, \link{MxData} and \link{MxMatrix} objects.
96 }
97
98 \references{
99 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,} 234-251.
100
101 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
102 }
103
104 \examples{
105    
106 # Create and fit a model using mxMatrix, mxAlgebra, mxExpectationNormal, and mxFitFunctionML
107
108 library(OpenMx)
109
110 # Simulate some data
111
112 # The example is that there is no example.
113
114 }