Adding to State Space documentation. And fixing OpenMx citation.
[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. The mxExpectationStateSpace provides maximum likelihood estimates of free parameters in a model of the covariance of a given \link{MxData} object. This model is defined by reticular action modeling (McArdle and McDonald, 1984). The 'A', 'B', 'C', 'D', 'Q', 'R', 'x0', and 'P0' arguments must refer to \link{MxMatrix} objects with the associated properties of the A, B, C, D, Q, R, x0, and P0 matrices in the RAM modeling approach.
47
48 The state space expectation is defined by the following equations.
49
50 \deqn{x_{t+1} = A x_t + B u_t + q_t}
51 \deqn{y_t = C x_t + D u_t + r_t}
52
53 The 'dimnames' arguments takes an optional character vector.  If this argument is not a single NA, then this vector be assigned to be the column names of the '?' matrix and optionally to the '?' matrix, if the '?' matrix exists.
54
55 THE NEXT PART IS INCOMPLETE.  MIKE HUNTER NEEDS TO FINISH THIS PART.
56
57 The 'A' argument refers to the A matrix in the State Space approach. This matrix consists of . 
58
59 The 'B' argument refers to the A matrix in the State Space approach. This matrix consists of . 
60
61 The 'C' argument refers to the A matrix in the State Space approach. This matrix consists of . 
62
63 The 'D' argument refers to the A matrix in the State Space approach. This matrix consists of . 
64
65 The 'Q' argument refers to the A matrix in the State Space approach. This matrix consists of . 
66
67 The 'R' argument refers to the A matrix in the State Space approach. This matrix consists of . 
68
69 The 'x0' argument refers to the A matrix in the State Space approach. This matrix consists of . 
70
71 The 'P0' argument refers to the A matrix in the State Space approach. This matrix consists of . 
72
73
74 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.
75
76 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'.
77
78 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..
79 }
80
81 \value{
82     Returns a new MxExpectationStateSpace object. mxExpectationStateSpace objects should be included with models with referenced \link{MxAlgebra}, \link{MxData} and \link{MxMatrix} objects.
83 }
84
85 \references{
86 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.
87
88 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
89 }
90
91 \examples{
92    
93 # Create and fit a model using mxMatrix, mxAlgebra, mxExpectationNormal, and mxFitFunctionML
94
95 library(OpenMx)
96
97 # Simulate some data
98
99 # The example is that there is no example.
100
101 }