Update Users Guide pages A through F for the expectation-fit change.
[openmx:openmx.git] / docs / source / DefinitionMeans_Path.rst
1     .. _definitionmeans-path-specification:
2
3 Definition Variables, Path Specification
4 ========================================
5
6 This example will demonstrate the use of OpenMx definition variables with the analysis of a simple two group dataset.  What are definition variables?  Essentially, definition variables can be thought of as observed variables that are used to change the statistical model on an individual case basis.  In essence, it is as though one or more variables in the raw data vectors are used to specify the statistical model for that individual.  Many different types of statistical model can be specified in this fashion; some  are readily specified in standard fashion, and some cannot.  To illustrate, we implement a two-group model.  The groups differ in their means but not in their variances and covariances.  This situation could easily be modeled in a regular multiple group fashion - it is only implemented using definition variables to illustrate their use.  The results are verified using summary statistics and an Mx 1.0 script for comparison is also available.
7
8 Mean Differences
9 ----------------
10
11 The example shows the use of definition variables to test for mean differences. It is available in the following file:
12
13 * http://openmx.psyc.virginia.edu/svn/trunk/demo/DefinitionMeans_PathRaw.R
14
15 A parallel version of this example, using matrix specification of models rather than paths, can be found here:
16
17 * http://openmx.psyc.virginia.edu/svn/trunk/demo/DefinitionMeans_MatrixRaw.R
18
19
20 Statistical Model
21 ^^^^^^^^^^^^^^^^^
22
23 Algebraically, we are going to fit the following model to the observed x and y variables:
24
25 .. math::
26    :nowrap:
27    
28    \begin{eqnarray*} 
29    x_{i} = \mu_{x} + \beta_x * def + \epsilon_{xi}\\
30    y_{i} = \mu_{y} + \beta_y * def + \epsilon_{yi}
31    \end{eqnarray*}
32
33 where :math:`def` is the definition variable and the residual sources of variance, :math:`\epsilon_{xi}` and :math:`\epsilon_{yi}` covary to the extent :math:`\rho`.  So, the task is to estimate: the two means :math:`\mu_{x}` and :math:`\mu_{y}`; the deviations from these means due to belonging to the group identified by having :math:`def` set to 1 (as opposed to zero), :math:`\beta_{x}` and :math:`\beta_{y}`; and the parameters of the variance covariance matrix: cov(:math:`\epsilon_{x},\epsilon_{y}`).
34
35 Our task is to implement the model shown in the figure below:
36
37 .. image:: graph/DefinitionMeansModel.png
38     :height: 2in
39
40 Data Simulation
41 ^^^^^^^^^^^^^^^
42
43 Our first step to running this model is to simulate the data to be analyzed. Each individual is measured on two observed variables, *x* and *y*, and a third variable *def* which denotes their group membership with a 1 or a 0.  These values for group membership are not accidental, and must be adhered to in order to obtain readily interpretable results.  Other values such as 1 and 2 would yield the same model fit, but would make the interpretation more difficult.  
44
45 .. code-block:: r
46
47     library(MASS)    # to get hold of mvrnorm function 
48
49     set.seed(200)    # to make the simulation repeatable
50     N <- 500    # sample size, per group
51   
52     Sigma <- matrix(c(1,.5,.5,1),2,2)
53     group1 <- mvrnorm(N, c(1,2), Sigma)
54     group2 <- mvrnorm(N, c(0,0), Sigma)
55
56 We make use of the superb R function ``mvrnorm`` in order to simulate N=500 records of data for each group.  These observations correlate .5 and have a variance of 1, per the matrix Sigma.  The means of *x* and *y* in group 1 are 1.0 and 2.0, respectively; those in group 2 are both zero.  The output of the ``mvrnorm`` function calls are matrices with 500 rows and 2 columns, which are stored in group 1 and group 2.  Now we create the definition variable
57
58 .. code-block:: r
59
60     # Put the two groups together, create a definition variable, 
61     # and make a list of which variables are to be analyzed (selVars)
62     xy <- rbind(group1,group2)
63     dimnames(xy)[2] <- list(c("x","y"))
64     def <- rep(c(1,0),each=N)
65     selVars <- c("x","y")
66
67 The objects ``xy`` and ``def`` might be combined in a data frame.  However, in this case we won't bother to do it externally, and simply paste them together in the ``mxData`` function call.
68
69 Model Specification
70 ^^^^^^^^^^^^^^^^^^^
71
72 The following code contains all of the components of our model.  Before specifying a model, the OpenMx library must be loaded into R using either the ``require()`` or ``library()`` function. This code uses the ``mxModel`` function to create an ``mxModel`` object, which we'll then run.  Note that all the objects required for estimation (data, matrices, an expectation function, and a fit function) are declared within the ``mxModel`` function.  This type of code structure is recommended for OpenMx scripts generally.
73
74 .. code-block:: r
75
76     defMeansModel <- mxModel("Definition Means Path Specification", 
77         type="RAM",
78         manifestVars=selVars,
79         latentVars  ="DefDummy",
80         # variances
81         mxPath(
82             from=c("x","y"), 
83             arrows=2, 
84             free= TRUE, 
85             values=1,  
86             labels=c("Varx","Vary")
87         ),
88         # covariances  
89         mxPath(
90             from="x", 
91             to="y", 
92             arrows=2, 
93             free= TRUE, 
94             values=.1, 
95             labels=c("Covxy")
96         ), 
97         # means      
98         mxPath(
99             from="one", 
100             to=c("x","y"), 
101             arrows=1, 
102             free= TRUE, 
103             values=1, 
104             labels=c("meanx","meany")
105         ), 
106         # definition value 
107         mxPath(
108             from="one", 
109             to="DefDummy", 
110             arrows=1, 
111             free= FALSE, 
112             values=1, 
113             labels="data.def"
114         ),    
115         # beta weights
116         mxPath(
117             from="DefDummy", 
118             to=c("x","y"), 
119             arrows=1, 
120             free= TRUE, 
121             values=1, 
122             labels=c("beta_1","beta_2")
123         ), 
124         mxData(
125             observed=data.frame(xy,def), 
126             type="raw"
127         )
128     )
129
130 The first argument in an ``mxModel`` function has a special function. If an object or variable containing an ``MxModel`` object is placed here, then ``mxModel`` adds to or removes pieces from that model. If a character string (as indicated by double quotes) is placed first, then that becomes the name of the model. Models may also be named by including a ``name`` argument. This model is named ``"Definition Means Path Specification"``.
131
132 .. code-block:: r
133
134     require(OpenMx)
135     
136     defMeansModel<-mxModel("Definition Means Path Specification", 
137         type="RAM",
138
139 The second line of the ``mxModel`` function call declares that we are going to be using RAM specification of the model, using directional and bidirectional path coefficients between the variables. 
140
141 .. code-block:: r
142
143     manifestVars=c("x","y"),
144     latentVars="DefDummy",
145
146 Model specification is carried out using two lists of variables, ``manifestVars`` and ``latentVars``.  Then ``mxPath`` functions are used to specify paths between them. In the present case, we need four mxPath commands to specify the model.  The first is for the variances of the *x* and *y* variables, and the second specifies their covariance.  The third specifies a path from the mean vector, always known by the special keyword ``one``, to each of the observed variables, and to the single latent variable ``DefDummy``.  This last path is specified to contain the definition variable, by virtue of the ``data.def`` label.  Definition variables are part of the data so the first part is always ``data.``.  The second part refers to the actual variable in the dataset whose values are modeled.  The Finally, two paths are specified from the ``DefDummy`` latent variable to the observed variables.  These parameters estimate the deviation of the mean of those with a ``data.def`` value of 1 from that of those with ``data.def`` values of zero.
147
148 .. code-block:: r
149
150     # variances
151     mxPath(
152         from=c("x","y"), 
153         arrows=2, 
154         free= TRUE, 
155         values=1,  
156         labels=c("Varx","Vary")
157     ),
158     # covariances  
159     mxPath(
160         from="x", 
161         to="y", 
162         arrows=2, 
163         free= TRUE, 
164         values=.1, 
165         labels=c("Covxy")
166     ), 
167     # means      
168     mxPath(
169         from="one", 
170         to=c("x","y"), 
171         arrows=1, 
172         free=TRUE, 
173         values=1, 
174         labels=c("meanx","meany")
175     ), 
176     # definition value
177     mxPath(
178         from="one", 
179         to="DefDummy", 
180         arrows=1, 
181         free= FALSE, 
182         values=1, 
183         labels="data.def"
184     ),    
185     # beta weights
186     mxPath(
187         from="DefDummy", 
188         to=c("x","y"), 
189         arrows=1, 
190         free= TRUE, 
191         values=1, 
192         labels=c("beta_1","beta_2")
193     ), 
194
195
196 Next, we declare where the data are, and their type, by creating an ``MxData`` object with the ``mxData`` function. This code first references the object where our data are, then uses the ``type`` argument to specify that this is raw data. Analyses using definition variables have to use raw data, so that the model can be specified on an individual data vector level.
197
198 .. code-block:: r
199
200     mxData(
201         observed=data.frame(xy,def), 
202         type="raw"
203     ))
204
205 We can then run the model and examine the output with a few simple commands.
206
207 Model Fitting
208 ^^^^^^^^^^^^^^
209
210 .. code-block:: r
211
212     # Run the model
213     defMeansFit<-mxRun(defMeansModel)
214
215     defMeansFit@matrices
216
217 The R object ``defmeansFit`` contains matrices and algebras; here we are interested in the matrices, which can be seen with the ``defmeansFi@matrices`` entry.  In path notation, the unidirectional, one-headed arrows appear in the matrix **A**, the two-headed arrows in **S**, and the mean vector single headed arrows in **M**.
218
219 .. code-block:: r
220
221     # Compare OpenMx estimates to summary statistics from raw data, 
222     # remembering to knock off 1 and 2 from group 1's data
223     # so as to estimate variance of combined sample without 
224     # the mean difference contributing to the variance estimate.
225  
226     # First compute some summary statistics from data
227     ObsCovs <- cov(rbind(group1 - rep(c(1,2), each=N), group2))
228     ObsMeansGroup1 <- c(mean(group1[,1]), mean(group1[,2]))
229     ObsMeansGroup2 <- c(mean(group2[,1]), mean(group2[,2]))
230
231     # Second extract parameter estimates and matrix algebra results from model
232     Sigma <- mxEval(S[1:2,1:2], defMeansFit)
233     Mu <- mxEval(M[1:2], defMeansFit)
234     beta <- mxEval(A[1:2,3], defMeansFit)
235
236     # Third, check to see if things are more or less equal
237     omxCheckCloseEnough(ObsCovs,Sigma,.01)
238     omxCheckCloseEnough(ObsMeansGroup1,as.vector(Mu+beta),.001)
239     omxCheckCloseEnough(ObsMeansGroup2,as.vector(Mu),.001)
240
241 These models may also be specified using matrices instead of paths. See :ref:`definitionmeans-matrix-specification` for matrix specification of these models.