From b7f912d3c8f661ee0f989c53a0dadca3455c284f Mon Sep 17 00:00:00 2001
From: mhunter
Date: Thu, 20 Mar 2014 16:49:28 +0000
Subject: [PATCH] Update Users Guide pages A through F for the expectation-fit
change.
git-svn-id: http://openmx.psyc.virginia.edu/svn/trunk@3166 df83fd30-4cca-4c36-ab9d-e8b5583ccbd1
---
docs/source/DefinitionMeans_Matrix.rst | 21 +++++++++++----------
docs/source/DefinitionMeans_Path.rst | 2 +-
docs/source/FactorAnalysisOrdinal_Matrix.rst | 21 ++++++++++++---------
docs/source/FactorAnalysis_Matrix.rst | 26 +++++++++++++++-----------
docs/source/File_Checkpointing.rst | 3 ++-
5 files changed, 41 insertions(+), 32 deletions(-)
diff --git a/docs/source/DefinitionMeans_Matrix.rst b/docs/source/DefinitionMeans_Matrix.rst
index cecace3..99ca388 100644
--- a/docs/source/DefinitionMeans_Matrix.rst
+++ b/docs/source/DefinitionMeans_Matrix.rst
@@ -3,7 +3,7 @@
Definition Variables, Matrix Specification
==========================================
-This example will demonstrate the use of OpenMx definition variables with the implementation of a simple two group dataset. What are definition variables? Essentially, definition variables can be thought of as observed variables which 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 that 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.
+This example will demonstrate the use of OpenMx definition variables with the implementation of a simple two group dataset. What are definition variables? Essentially, definition variables can be thought of as observed variables which 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 models can be specified in this fashion; some can be readily specified in standard fashion, and some that 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.
Mean Differences
----------------
@@ -30,7 +30,7 @@ Algebraically, we are going to fit the following model to the observed x and y v
y_{i} = \mu_{y} + \beta_y * def + \epsilon_{yi}
\end{eqnarray*}
-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}`).
+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}`) = :math:`\rho`.
Our task is to implement the model shown in the figure below:
@@ -74,18 +74,19 @@ The following code contains all of the components of our model. Before running a
.. code-block:: r
- defMeansModel <- mxModel("Definition Means Matrix Specification",
- mxFIMLObjective(
+ defMeansModel <- mxModel("Definition Means Matrix Specification",
+ mxFitFunctionML(),
+ mxExpectationNormal(
covariance="Sigma",
means="Mu",
dimnames=selVars
- ),
+ ),
-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 Matrix Specification"``.
+The first argument in an ``mxModel`` function has a special purpose. 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 Matrix Specification"``.
-The second argument in this ``mxModel`` call is itself a function. It declares that the objective function to be optimized is full information maximum likelihood (FIML) under normal theory, which is tagged as ``mxFIMLObjective``. There are in turn two arguments to this function: the covariance matrix ``Sigma`` and the mean vector ``Mu``. These matrices will be defined later in the ``mxModel`` function call.
+The second argument in this ``mxModel`` call is itself a function. It declares that the fit function to be optimized is maximum likelihood (ML), which is tagged ``mxFitFunctionML``. Full information maximum likelihood (FIML) is used whenever the data allow, and does not need to be requested specifically. The third argument in this ``mxModel`` is another function. It declares the expectation function to be a normal distribution, ``mxExpectationNormal``. This means the model is of a normal distribution with a particular mean and covariance. Hence, there are in turn two arguments to this function: the covariance matrix ``Sigma`` and the mean vector ``Mu``. These matrices will be defined later in the ``mxModel`` function call.
-Model specification is carried out using ``mxMatrix`` functions to create matrices for the model. In the present case, we need four matrices. First is the predicted covariance matrix, ``Sigma``. Next, we use three matrices to specify the model for the means. First is ``M`` which corresponds to estimates of the means for individuals with definition variables with values of zero. Individuals with definition variable values of 1 will have the value in ``M`` along with the value in the matrix ``beta``. So both matrices are of size 1x2 and both contain two free parameters. There is a separate deviation for each of the variables, which will be estimated in the elements 1,1 and 1,2 of the ``beta`` matrix. Last, but by no means least, is the matrix ``def`` which contains the definition variable. The variable *def* in ``mxData`` data frame is referred to as ``data.def``. In the present case, the definition variable contains a 1 for group 1, and a zero otherwise.
+Model specification is carried out using ``mxMatrix`` functions to create matrices for the model. In the present case, we need four matrices. First is the predicted covariance matrix, ``Sigma``. Next, we use three matrices to specify the model for the means. First is ``M`` which corresponds to estimates of the means for individuals with definition variables with values of zero. Individuals with definition variable values of 1 will have the value in ``M`` plus the value in the matrix ``beta``. So both matrices are of size 1x2 and both contain two free parameters. There is a separate deviation for each of the variables, which will be estimated in the elements 1,1 and 1,2 of the ``beta`` matrix. Last, but by no means least, is the matrix ``def`` which contains the definition variable. The variable *def* in the ``mxData`` data frame is referred to in the matrix label as ``data.def``. In the present case, the definition variable contains a 1 for group 1, and a zero otherwise.
.. code-block:: r
@@ -134,9 +135,9 @@ The trick - commonly used in regression models - is to multiply the ``beta`` mat
name="Mu"
),
-The result of this algebra is named ``Mu``, and this handle is referred to in the ``mxFIMLObjective`` function call.
+The result of this algebra is named ``Mu``, and this handle is referred to in the ``mxExpectationNormal`` function call.
-Next, we declare where the data are, and their type, by creating an ``MxData`` object with the ``mxData`` function. This piece of code creates an ``MxData`` object. It 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.
+Next, we declare where the data are, and their type, by creating an ``MxData`` object with the ``mxData`` function. This piece of code creates an ``MxData`` object. It first references the object where our data are, then uses the ``type`` argument to specify that this is raw data. Because the data are raw and the fit function is ``mxFitFunctionML``, full information maximum likelihood is used in this ``mxModel``. Analyses using definition variables have to use raw data, so that the model can be specified on an individual data vector level.
.. code-block:: r
diff --git a/docs/source/DefinitionMeans_Path.rst b/docs/source/DefinitionMeans_Path.rst
index a0bf39e..328eb81 100644
--- a/docs/source/DefinitionMeans_Path.rst
+++ b/docs/source/DefinitionMeans_Path.rst
@@ -69,7 +69,7 @@ The objects ``xy`` and ``def`` might be combined in a data frame. However, in t
Model Specification
^^^^^^^^^^^^^^^^^^^
-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, and an objective function) are declared within the ``mxModel`` function. This type of code structure is recommended for OpenMx scripts generally.
+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.
.. code-block:: r
diff --git a/docs/source/FactorAnalysisOrdinal_Matrix.rst b/docs/source/FactorAnalysisOrdinal_Matrix.rst
index 354b2ff..40f059f 100644
--- a/docs/source/FactorAnalysisOrdinal_Matrix.rst
+++ b/docs/source/FactorAnalysisOrdinal_Matrix.rst
@@ -79,7 +79,7 @@ Our first step to running this model is to include the data to be analyzed. The
Model Specification
^^^^^^^^^^^^^^^^^^^
-The following code contains all of the components of our model. Before running a model, the OpenMx library must be loaded into R using either the ``require()`` or ``library()`` function. All objects required for estimation (data, matrices, and an objective function) are included in their functions. This code uses the ``mxModel`` function to create an ``MxModel`` object, which we will then run. We pre-specify a number of 'variables', namely the number of variables analyzed ``nVariables``, in this case 5, the number of factors ``nFactors``, here one, and the number of thresholds ``nthresholds``, here 3 or one less than the number of categories in the simulated ordinal variable.
+The following code contains all of the components of our model. Before running a model, the OpenMx library must be loaded into R using either the ``require()`` or ``library()`` function. All objects required for estimation (data, matrices, an expectation function, and a fit function) are included in their functions. This code uses the ``mxModel`` function to create an ``MxModel`` object, which we will then run. We pre-specify a number of 'variables', namely the number of variables analyzed ``nVariables``, in this case 5, the number of factors ``nFactors``, here one, and the number of thresholds ``nthresholds``, here 3 or one less than the number of categories in the simulated ordinal variable.
.. code-block:: r
@@ -140,12 +140,13 @@ The following code contains all of the components of our model. Before running a
observed=ordinalData,
type='raw'
),
- mxFIMLObjective(
+ mxExpectationNormal(
covariance="expCovariances",
means="expMeans",
dimnames=bananaNames,
thresholds="expThresholds"
- )
+ ),
+ mxFitFunctionML()
)
@@ -247,18 +248,19 @@ We estimate the ``Full`` **nThresholds x nVariables** matrix. To make sure that
name="expThresholds"
)
-The final part of this model is the objective function. The choice of fit function determines the required arguments. Here we fit to raw ordinal data, thus we specify the matrices for the expected covariance matrix of the data, as well as the expected means and thresholds previously specified. We use ``dimnames`` to map the model for means, thresholds and covariances onto the observed variables.
+The final parts of this model are the expectation function and the fit function. The choice of expectation function determines the required arguments. Here we fit to raw ordinal data, thus we specify the matrices for the expected covariance matrix of the data, as well as the expected means and thresholds previously specified. We use ``dimnames`` to map the model for means, thresholds and covariances onto the observed variables.
.. code-block:: r
- mxFIMLObjective(
+ mxExpectationNormal(
covariance="expCovariances",
means="expMeans",
dimnames=bananaNames,
thresholds="expThresholds"
- )
+ ),
+ mxFitFunctionML()
-The free parameters in the model can then be estimated using full information maximum likelihood (FIML) for covariances, means and thresholds. To do so, the model is run using the ``mxRun`` function, and the output of the model can be accessed from the ``@output`` slot of the resulting model. A summary of the output can be reached using ``summary()``.
+The free parameters in the model can then be estimated using full information maximum likelihood (FIML) for covariances, means and thresholds. FIML is specified by using raw data with the ``mxFitFunctionML``. To estimate free parameters, the model is run using the ``mxRun`` function, and the output of the model can be accessed from the ``@output`` slot of the resulting model. A summary of the output can be reached using ``summary()``.
.. code-block:: r
@@ -356,12 +358,13 @@ As indicate above, the model can be re-parameterized such that means and varianc
observed=ordinalData,
type='raw'
),
- mxFIMLObjective(
+ mxExpectationNormal(
covariance="expCovariances",
means="expMeans",
dimnames=bananaNames,
thresholds="expThresholds"
- )
+ ),
+ mxFitFunctionML()
)
We will only highlight the changes from the previous model specification. By fixing the first and second threshold to 0 and 1 respectively for each variable, we are now able to estimate a mean and a variance for each variable instead. If we are estimating the variances of the observed variables, the factor loadings are no longer standardized, thus we relax the upper boundary on the factor loading matrix ``facLoadings`` to be 2. The residual variances are now directly estimated as a ``Diagonal`` matrix of size ``nVariables x nVariables``, and given a start value higher than that for the factor loadings. As the residual variances are already on the diagonal of the ``resVariances`` matrix, we no longer need to add the ``vec2diag`` function to obtain the ``expCovariances`` matrix.
diff --git a/docs/source/FactorAnalysis_Matrix.rst b/docs/source/FactorAnalysis_Matrix.rst
index 3cdcfe8..946f0a0 100644
--- a/docs/source/FactorAnalysis_Matrix.rst
+++ b/docs/source/FactorAnalysis_Matrix.rst
@@ -75,7 +75,7 @@ Our first step to running this model is to include the data to be analyzed. The
Model Specification
^^^^^^^^^^^^^^^^^^^
-The following code contains all of the components of our model. Before running a model, the OpenMx library must be loaded into R using either the ``require()`` or ``library()`` function. All objects required for estimation (data, matrices, and an objective function) are included in their functions. This code uses the ``mxModel`` function to create an ``MxModel`` object, which we will then run.
+The following code contains all of the components of our model. Before running a model, the OpenMx library must be loaded into R using either the ``require()`` or ``library()`` function. All objects required for estimation (data, matrices, an expectation function, and a fit function) are included in their functions. This code uses the ``mxModel`` function to create an ``MxModel`` object, which we will then run.
.. code-block:: r
@@ -170,8 +170,9 @@ The following code contains all of the components of our model. Before running a
labels=c("meanx1","meanx2","meanx3","meanx4","meanx5","meanx6",NA),
name="M"
),
- mxRAMObjective("A","S","F","M",
- dimnames=c(manifestVars, latentVars))
+ mxExpectationRAM("A","S","F","M",
+ dimnames=c(manifestVars, latentVars)),
+ mxFitFunctionML()
)
This ``mxModel`` function can be split into several parts. First, we give the model a name. 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 ``"Common Factor Model Matrix Specification"``.
@@ -303,7 +304,7 @@ The last matrix of our model is the **M** matrix, which defines the means and in
name="M"
)
-The final part of this model is the objective function. This defines both how the specified matrices combine to create the expected covariance matrix of the data, as well as the fit function to be minimized. In a RAM specified model, the expected covariance matrix is defined as:
+The final parts of this model are the expectation function and the fit function. The expectation defines how the specified matrices combine to create the expected covariance matrix of the data. The fit defines how the expectation is compared to the data to create a single scalar number that is minimized. In a RAM specified model, the expected covariance matrix is defined as:
.. math::
:nowrap:
@@ -321,13 +322,14 @@ The expected means are defined as:
ExpMean = F * (I - A)^{-1} * M
\end{eqnarray*}
-The free parameters in the model can then be estimated using maximum likelihood for covariance and means data, and full information maximum likelihood for raw data. While users may define their own expected covariance matrices using other objective functions in OpenMx, the ``mxRAMObjective`` function yields maximum likelihood estimates of structural equation models when the **A**, **S**, **F** and **M** matrices are specified. The **M** matrix is required both for raw data and for covariance or correlation data that includes a means vector. The ``mxRAMObjective`` function takes four arguments, which are the names of the **A**, **S**, **F** and **M** matrices in your model.
+The free parameters in the model can then be estimated using maximum likelihood for covariance and means data, and full information maximum likelihood for raw data. Although users may define their own expected covariance matrices using ``mxExpectationNormal`` and other functions in OpenMx, the ``mxExpectationRAM`` function computes the expected covariance and means matrices when the **A**, **S**, **F** and **M** matrices are specified. The **M** matrix is required both for raw data and for covariance or correlation data that includes a means vector. The ``mxExpectationRAM`` function takes four arguments, which are the names of the **A**, **S**, **F** and **M** matrices in your model. The ``mxFitFunctionML`` yields maximum likelihood estimates of structural equation models. It uses full information maximum likelihood when the data are raw.
.. code-block:: r
- mxRAMObjective("A", "S", "F", "M")
+ mxExpectationRAM("A", "S", "F", "M"),
+ mxFitFunctionML()
-The model now includes an observed covariance matrix (i.e., data) and the matrices and objective function required to define the expected covariance matrix and estimate parameters.
+The model now includes an observed covariance matrix (i.e., data), model matrices, an expectation function, and a fit function. So the model has all the required elements to define the expected covariance matrix and estimate parameters.
The model can now be run using the ``mxRun`` function, and the output of the model can be accessed from the ``@output`` slot of the resulting model. A summary of the output can be reached using ``summary()``.
@@ -374,13 +376,14 @@ We start with displaying the complete script. Note that we have used the succin
name="expCov" ),
mxAlgebra(expression= varMeans + t(facLoadings %*% facMeans),
name="expMean" ),
- mxFIMLObjective( covariance="expCov", means="expMean", dimnames=manifestVars)
+ mxExpectationNormal( covariance="expCov", means="expMean", dimnames=manifestVars),
+ mxFitFunctionML()
)
oneFactorFit<-mxRun(oneFactorModel)
The first ``mxMatrix`` statement declares a ``Full`` **6x1** matrix of factor loadings to be estimated, called "facLoadings". We fix the first factor loading to 1 for identification. Even though we specify just one start value of 1 which is recycled for each of the elements in the matrix, it becomes the fixed value for the first factor loading and the start value for the other factor loadings. The second ``mxMatrix`` is a ``symmetric`` **1x1** which estimates the variance of the factor, named "facVariances". The third ``mxMatrix`` is a ``Diag`` **6x6** matrix for the residual variances, named "resVariances". The fourth ``mxMatrix`` is a ``Full`` **1x6** matrix of free elements for the means of the observed variables, called "varMeans". The fifth ``mxMatrix`` is a ``Full`` **1x1** matrix with a fixed value of zero for the factor mean, named "facMeans".
-We then use two algebra statement to work out the expected mean and covariance matrices. Note that the formula's for the expression of the expected covariance and the expected mean vector map directly on to the mathematical equations. The arguments for the ``mxFIMLObjective`` now refer to these algebras for the expected covariance and expected means. The ``dimnames`` are used to map them onto the observed variables.
+We then use two algebra statements to work out the expected mean and covariance matrices. Note that the formula's for the expression of the expected covariance and the expected mean vector map directly on to the mathematical equations. The arguments for the ``mxExpectationNormal`` function now refer to these algebras for the expected covariance and expected means. The ``dimnames`` are used to map them onto the observed variables. The fit function compares the expectation and the observation (i.e. data) to optimize free parameters.
Two Factor Model
@@ -412,7 +415,7 @@ The data for the two factor model can be found in the ``myFAData`` files introdu
twoFactorMeans <- myFADataMeans[c(1:3,7:9)]
-Specifying the two factor model is virtually identical to the single factor case. The ``mxData`` function has been changed to reference the appropriate data, but is identical in usage. We've added a second latent variable, so the **A** and **S** matrices are now of order 8x8. Similarly, the **F** matrix is now of order 6x8 and the **M** matrix of order 1x8. The ``mxRAMObjective`` has not changed. The code for our two factor model looks like this:
+Specifying the two factor model is virtually identical to the single factor case. The ``mxData`` function has been changed to reference the appropriate data, but is identical in usage. We've added a second latent variable, so the **A** and **S** matrices are now of order 8x8. Similarly, the **F** matrix is now of order 6x8 and the **M** matrix of order 1x8. The ``mxExpectationRAM`` has not changed. The code for our two factor model looks like this:
.. code-block:: r
@@ -513,7 +516,8 @@ Specifying the two factor model is virtually identical to the single factor case
NA,NA),
name="M"
),
- mxRAMObjective("A","S","F","M")
+ mxExpectationRAM("A","S","F","M"),
+ mxFitFunctionML()
)
The four ``mxMatrix`` functions have changed slightly to accomodate the changes in the model. The **A** matrix, shown below, is used to specify the regressions of the manifest variables on the factors. The first three manifest variables (``"x1"``-``"x3"``) are regressed on ``"F1"``, and the second three manifest variables (``"y1"``-``"y3"``) are regressed on ``"F2"``. We must again constrain the model to identify and scale the latent variables, which we do by constraining the first loading for each latent variable to a value of one.
diff --git a/docs/source/File_Checkpointing.rst b/docs/source/File_Checkpointing.rst
index 07191f2..1a2846d 100644
--- a/docs/source/File_Checkpointing.rst
+++ b/docs/source/File_Checkpointing.rst
@@ -18,7 +18,8 @@ This section will cover how to periodically save the state of the optimizer to a
mxMatrix(type="Symm", nrow=1, ncol=1, values=1, free=FALSE, name="L"),
mxMatrix(type="Diag", nrow=5, ncol=5, values=1, free=TRUE, name="U"),
mxAlgebra(expression=A %*% L %*% t(A) + U, name="R"),
- mxMLObjective(covariance="R", dimnames=manifestVars),
+ mxExpectationNormal(covariance="R", dimnames=manifestVars),
+ mxFitFunctionML(),
mxData(observed=cov(demoOneFactor), type="cov", numObs=500)
)
--
2.1.4