mxModel {OpenMx}

Create MxModel Object

Description

Create or modify an MxModel.

Usage

mxModel(model = NA, ..., manifestVars = NA, latentVars = NA,
          remove = FALSE, independent = NA, type = NA, name = NA)

Arguments

model

This argument is either an MxModel object or a string. If 'model' is an MxModel object, then all elements of that model are placed in the resulting MxModel object. If 'model' is a string, then a new model is created with the string as its name. If 'model' is either unspecified or 'model' is a named entity, data source, or MxPath object, then a new model is created.

...

An arbitrary number of mxMatrix, mxPath, mxData, and other functions such as mxConstraints and mxCI. These will all be added or removed from the model as specified in the 'model' argument, based on the 'remove' argument.

manifestVars

For RAM-type models, A list of manifest variables to be included in the model.

latentVars

For RAM-type models, A list of latent variables to be included in the model.

remove

logical. If TRUE, elements listed in this statement are removed from the original model. If FALSE, elements listed in this statement are added to the original model.

independent

logical. If TRUE then the model is evaluated independently of other models.

type

character vector. The model type to assign to this model. Defaults to options("mxDefaultType"). See below for valid types

name

An optional character vector indicating the name of the object.

Details

The mxModel function is used to create MxModels. Models created by this function may be new, or may be modified versions of existing MxModel objects. By default a new MxModel object will be created: To create a modified version of an existing MxModel object, include this model in the 'model' argument.

Other named-entities may be added as arguments to the mxModel function, which are then added to or removed from the model specified in the ‘model’ argument. Functions you can use to add objects to the model to this way include mxPath, mxCI, mxAlgebra, mxBounds, mxConstraint, mxData, and mxMatrix objects, as well as fit functions and expectations (see below). You can also include sub-models as components of a model. These sub-models may be estimated separately or jointly depending on shared parameters and the ‘independent’ flag (see below). Only one MxData object and one fit function and expectation may be included per model, but there are no restrictions on the number of other named-entities included in an mxModel statement.

All other arguments must be named (i.e. ‘latentVars = names’), or they will be interpreted as elements of the ellipsis list. The ‘manifestVars’ and ‘latentVars’ arguments specify the names of the manifest and latent variables, respectively, for use with the mxPath function.

The ‘remove’ argument may be used when mxModel is used to create a modified version of an existing MxMatrix object. When ‘remove’ is set to TRUE, the listed objects are removed from the model specified in the ‘model’ argument. When ‘remove’ is set to FALSE, the listed objects are added to the model specified in the ‘model’ argument.

Model independence may be specified with the ‘independent’ argument. If a model is independent (‘independent = TRUE’), then the parameters of this model are not shared with any other model. An independent model may be estimated with no dependency on any other model. If a model is not independent (‘independent = FALSE’), then this model shares parameters with one or more other models such that these models must be jointly estimated. These dependent models must be entered as arguments in another model, so that they are simultaneously optimized.

The model type is determined by a character vector supplied to the ‘type’ argument. The type of a model is a dynamic property, ie. it is allowed to change during the lifetime of the model. To see a list of available types, use the mxTypes command. When a new model is created and no type is specified, the type specified by options("mxDefaultType") is used.

Expectations and Fit functions

To be estimated, MxModel objects must include fit functions and expectations as arguments. Fit functions include mxFitFunctionML, mxFitFunctionMultigroup, mxFitFunctionWLS, mxFitFunctionAlgebra, mxFitFunctionGREML, mxFitFunctionR, and mxFitFunctionRow. Expectations include mxExpectationBA81, mxExpectationGREML, mxExpectationHiddenMarkov mxExpectationLISREL, mxExpectationMixture, mxExpectationNormal, mxExpectationRAM, mxExpectationStateSpace, mxExpectationStateSpaceContinuousTime. The 'type' of the model may imply a certain fit function or expectation (e.g. type = "RAM" implies mxExpectationRAM). The model data may also constrain which fit and expectation are appropriate.

The model, complete with fit function and expectation can then be executed using mxRun.

Accessing model components

You can view a model summary with summary. You can also access Named entities in MxModel directly via the $ symbol. For instance, for an MxModel named "yourModel" containing an MxMatrix named "yourMatrix", the contents of "yourMatrix" can be accessed as yourModel$yourMatrix. Slots (i.e., matrices, algebras, etc.) in an mxMatrix may also be referenced with the $ symbol (e.g., yourModel$matrices or yourModel$algebras). See the documentation for Classes and the examples in Classes for more information.

Value

Returns a new MxModel object. To be run, MxModel object must include a fit function and expectation.

References

The OpenMx User's guide can be found at https://openmx.ssri.psu.edu/documentation/.

See Also

See mxCI for information about adding Confidence Interval calculations to a model. See mxPath for information about adding paths to RAM-type models. See mxMatrix for information about adding matrices to models. See mxData for specifying the data a model is to be evaluated against. Many advanced options can be set via mxOption. More information about the OpenMx package may be found here.

Examples

library(OpenMx)

# At the simplest, you can create an empty model,
#  placing it in an object, and add to it later
emptyModel <- mxModel(model="IAmEmpty")

# Create a model named 'firstdraft' with one matrix 'A'
firstModel <- mxModel(model='firstdraft', 
                 mxMatrix(type='Full', nrow = 3, ncol = 3, name = "A"))

# Update 'firstdraft', and rename the model 'finaldraft'
finalModel <- mxModel(model=firstModel,
                 mxMatrix(type='Symm', nrow = 3, ncol = 3, name = "S"),
                 mxMatrix(type='Iden', nrow = 3, name = "F"),
                 name= "finaldraft")

# Add data to the model from an existing data frame in object 'data'
data(twinData)  # load some data
finalModel <- mxModel(model=finalModel, mxData(twinData, type='raw'))

# Two ways to view the matrix named "A" in MxModel object 'model'

finalModel$A

finalModel$matrices$A

# A working example using OpenMx Path Syntax
data(HS.ability.data)  # load the data

# The manifest variables loading on each proposed latent variable
Spatial   <- c("visual", "cubes", "paper")
Verbal    <- c("general", "paragrap", "sentence")
Math      <- c("numeric", "series", "arithmet")

latents   <- c("vis", "math", "text")
manifests <-  c(Spatial, Math, Verbal)

HSModel <- mxModel(model="Holzinger_and_Swineford_1939", type="RAM", 
    manifestVars = manifests, # list the measured variables (boxes)
    latentVars   = latents,   # list the latent variables (circles)
    # factor loadings from latents to  manifests
    mxPath(from="vis",  to=Spatial),# factor loadings
    mxPath(from="math", to=Math),   # factor loadings
    mxPath(from="text", to=Verbal), # factor loadings

    # Allow latent variables to covary 
    mxPath(from="vis" , to="math", arrows=2, free=TRUE),
    mxPath(from="vis" , to="text", arrows=2, free=TRUE),
    mxPath(from="math", to="text", arrows=2, free=TRUE),

    # Allow latent variables to have variance
    mxPath(from=latents, arrows=2, free=FALSE, values=1.0),
    # Manifest have residual variance
    mxPath(from=manifests, arrows=2),   
    # the data to be analysed
    mxData(cov(HS.ability.data[,manifests]), type = "cov", numObs = 301))
    
fitModel <- mxRun(HSModel) # run the model
summary(fitModel) # examine the output: Fit statistics and path loadings