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