OpenMx: An package for Structural Equation Modeling and Matrix Algebra Optimization

Description

OpenMx is a package for structural equation modeling, matrix algebra optimization and other statistical estimation problems. Try the example below. We try and have useful help files: for instance help(mxRun) to learn more. Also the reference manual

Details

OpenMx solves algebra optimization and statistical estimation problems using matrix algebra. Most users use it for Structural equation modeling.

The core function is mxModel, which makes a model. Models are containers for mxData, matrices, mxPaths algebras, mxBounds, confidence intervals, and mxConstraints. Most models require an expectation (see the list below) to calculate the expectations for the model. Models also need a fit function, several of which are built-in (see below). OpenMx also allows user-defined fit functions for purposes not covered by the built-in functions. (e.g., mxFitFunctionR or mxFitFunctionAlgebra).

Note, for mxModels of type="RAM", the expectation and fit-function are set for you automatically.

Running and summarizing a model

Once built, the resulting mxModel can be run (i.e., optimized) using mxRun. This returns the fitted model.

You can summarize the results of the model using summary(yourModel)

Additional overview of model making and getting started

The OpenMx manual is online (see references below). However, mxRun, mxModel, mxMatrix all have working examples that will help get you started as well.

The main OpenMx functions are: mxAlgebra, mxBounds, mxCI, mxConstraint, mxData, mxMatrix, mxModel, and mxPath.

Expectation functions include mxExpectationNormal, mxExpectationRAM, mxExpectationLISREL, and mxExpectationStateSpace;

Fit functions include mxFitFunctionML, mxFitFunctionAlgebra, mxFitFunctionRow and mxFitFunctionR.

Datasets built into OpenMx

OpenMx comes with over a dozen useful datasets built-in. Discover them using data(package="OpenMx"), and open them with, for example, data("jointdata", package ="OpenMx", verbose= TRUE)

Please cite the 'OpenMx' package in any publications that make use of it:

Michael C. Neale, Michael D. Hunter, Joshua N. Pritikin, Mahsa Zahery, Timothy R. Brick Robert M. Kirkpatrick, Ryne Estabrook, Timothy C. Bates, Hermine H. Maes, Steven M. Boker. (2016). OpenMx 2.0: Extended structural equation and statistical modeling. Psychometrika, 81, 535–549. DOI: 10.1007/s11336-014-9435-8

Steven M. Boker, Michael C. Neale, Hermine H. Maes, Michael J. Wilde, Michael Spiegel, Timothy R. Brick, Jeffrey Spies, Ryne Estabrook, Sarah Kenny, Timothy C. Bates, Paras Mehta, and John Fox. (2011) OpenMx: An Open Source Extended Structural Equation Modeling Framework. Psychometrika, 306-317. DOI:10.1007/s11336-010-9200-6

Steven M. Boker, Michael C. Neale, Hermine H. Maes, Michael J. Wilde, Michael Spiegel, Timothy R. Brick, Ryne Estabrook, Timothy C. Bates, Paras Mehta, Timo von Oertzen, Ross J. Gore, Michael D. Hunter, Daniel C. Hackett, Julian Karch, Andreas M. Brandmaier, Joshua N. Pritikin, Mahsa Zahery, Robert M. Kirkpatrick, Yang Wang, and Charles Driver. (2016) OpenMx 2 User Guide. https://openmx.ssri.psu.edu/docs/OpenMx/latest/OpenMxUserGuide.pdf

Author(s)

Maintainer: Robert M. Kirkpatrick robert.kirkpatrick@vcuhealth.org

Authors:

• Steven M. Boker

• Michael C. Neale

• Hermine H. Maes

• Michael Spiegel

• Timothy R. Brick

• Ryne Estabrook

• Timothy C. Bates

• Ross J. Gore

• Michael D. Hunter

• Joshua N. Pritikin

• Mahsa Zahery

Other contributors:

• Michael J. Wilde [contributor]

• Paras Mehta [contributor]

• Timo von Oertzen [contributor]

• Daniel C. Hackett [contributor]

• Julian Karch [contributor]

• Andreas M. Brandmaier [contributor]

• Yang Wang [contributor]

• Ben Goodrich goodrich.ben@gmail.com [contributor]

• Charles Driver driver@mpib-berlin.mpg.de [contributor]

• Jannik H. Orzek jannik.orzek@mailbox.org [contributor]

• Massachusetts Institute of Technology [copyright holder]

• S. G. Johnson [copyright holder]

• Association for Computing Machinery [copyright holder]

• Dieter Kraft [copyright holder]

• Stefan Wilhelm [copyright holder]

• Sarah Medland [copyright holder]

• Carl F. Falk [copyright holder]

• Matt Keller [copyright holder]

• Manjunath B G [copyright holder]

• The Regents of the University of California [copyright holder]

• Lester Ingber [copyright holder]

• Wong Shao Voon [copyright holder]

• Juan Palacios [copyright holder]

• Jiang Yang [copyright holder]

• Gael Guennebaud [copyright holder]

• Jitse Niesen [copyright holder]

References

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

See Also

Useful links:

• https://openmx.ssri.psu.edu/

• https://github.com/OpenMx/OpenMx

• Report bugs at https://openmx.ssri.psu.edu/forums/

Examples

library(OpenMx)
data(demoOneFactor)
# ===============================
# = Make and run a 1-factor CFA =
# ===============================

latents  = c("G") # the latent factor
manifests = names(demoOneFactor) # manifest variables to be modeled
# ====================
# = Make the MxModel =
# ====================
m1 <- mxModel("One Factor", type = "RAM", 
	manifestVars = manifests, latentVars = latents, 
	mxPath(from = latents, to = manifests),
	mxPath(from = manifests, arrows = 2),
	mxPath(from = latents, arrows = 2, free = FALSE, values = 1.0),
	mxData(cov(demoOneFactor), type = "cov", numObs = 500)
)

# ===============================
# = mxRun it and get a summary! =
# ===============================

m1 = mxRun(m1)
summary(m1)

BaseCompute

Description

This is an internal class and should not be used directly.

See Also

mxComputeEM, mxComputeGradientDescent, mxComputeHessianQuality, mxComputeIterate, mxComputeNewtonRaphson, mxComputeNumericDeriv

Bollen Data on Industrialization and Political Democracy

Description

Data set used in some of OpenMx's examples, for instance WLS. The data were reported in Bollen (1989, p. 428, Table 9.4) This set includes data from 75 developing countries each assessed on four measures of democracy measured twice (1960 and 1965), and three measures of industrialization measured once (1960).

Usage

data("Bollen")

Format

A data frame with 75 observations on the following 11 numeric variables.

y1

Freedom of the press, 1960

y2

Freedom of political opposition, 1960

y3

Fairness of elections, 1960

y4

Effectiveness of elected legislature, 1960

y5

Freedom of the press, 1965

y6

Freedom of political opposition, 1965

y7

Fairness of elections, 1965

y8

Effectiveness of elected legislature, 1965

x1

GNP per capita, 1960

x2

Energy consumption per capita, 1960

x3

Percentage of labor force in industry, 1960

Details

Variables y1-y4 and y5-y8 are typically used as indicators of the latent trait of “political democracy” in 1960 and 1965 respectively. x1-x3 are used as indicators of industrialization (1960).

Source

The sem package (in turn, via personal communication Bollen to Fox)

References

Bollen, K. A. (1979). Political democracy and the timing of development. American Sociological Review, 44, 572-587.

Bollen, K. A. (1980). Issues in the comparative measurement of political democracy. American Sociological Review, 45, 370-390.

Bollen, K. A. (1989). Structural equation models. New York: Wiley-Interscience.

Examples

data(Bollen)
str(Bollen)
plot(y1 ~ y2, data = Bollen)

An S4 base class for discrete marginal distributions

Description

An S4 base class for discrete marginal distributions

See Also

mxMarginalPoisson, mxMarginalNegativeBinomial

Holzinger & Swineford (1939) Ability in 301 children from 2 schools

Description

This classic data set contains of intelligence-test scores from 301 children on 26 tests of cognitive ability.

The tests cover mental speed, memory, mathematical-ability, spatial, and verbal ability as listed below.

The data are also available in the MBESS package.

Usage

data("HS.ability.data")

Format

A data frame comprising 301 observations on 22 variables:

id

student ID number (int)

Gender

Sex (Factor w/ 2 levels “Female” and “Male”)

grade

Grade in school (integer 7 or 8)

agey

Age in years (integer)

agem

Age in months (integer)

school

School attended (Factor w/2 levels “Grant-White” and “Pasteur”)

addition

A speed test of addition (numeric)

code

A speed test (numeric)

counting

A speed test of counting groups of dots (numeric)

straight

A speed test discriminating straight and curved capitals (numeric)

wordr

A memory subtest of word recognition

numberr

A memory subtest of number recognition

figurer

A memory subtest of figure recognition

object

A memory subtest: object-number test

numberf

A memory subtest: number-figure test

figurew

A memory subtest: figure-word test

deduct

A mathematical subtest of deduction

numeric

A mathematical subtest of numerical puzzles

problemr

A mathematical subtest of problem reasoning

series

A mathematical subtest of series completion

arithmet

A mathematical subtest: Woody-McCall mixed fundamentals, form I

visual

A spatial subtest of visual perception

cubes

A spatial subtest

paper

A spatial subtest paper form board

flags

A spatial subtest (also known as lozenges)

paperrev

A spatial subtest additional paper form board test (can substitute for paper)

flagssub

A spatial subtest additional lozenges test (can substitute for flags)

general

A verbal subtest of general information

paragrap

A verbal subtest of paragraph comprehension

sentence

A verbal subtest of sentence completion

wordc

A verbal subtest of word classification

wordm

A verbal subtest of word meaning

Details

The data are from children who differ in grade (seventh- and eighth-grade) and are nested in one of two schools (Pasteur and Grant-White). You will see it in use elsewhere, both in R (lavaan, and MBESS), and in Joreskog (1969) reporting a CFA on the Grant-White school subject subset.

Some tests are alternate or substitute forms, e.g. paperrev (a paper form board test) can substitute for paper and flagssub for the lozenges test flags.

Source

Holzinger, K., and Swineford, F. (1939).

References

Holzinger, K., and Swineford, F. (1939). A study in factor analysis: The stability of a bifactor solution. Supplementary Educational Monograph, no. 48. Chicago: University of Chicago Press.

Joreskog, K. G. (1969). A general approach to confirmatory maximum likelihood factor analysis. Psychometrika, 34, 183-202.

Examples

data(HS.ability.data)
str(HS.ability.data)
levels(HS.ability.data$school)
plot(flags ~ flagssub, data = HS.ability.data)

Longitudinal, Overdispersed Count Data

Description

Four-timepoint longitudinal data generated from an arbitrary Monte Carlo simulation, for 1000 simulees. The response variable is a discrete count variable. There are three time-invariant covariates. The data are available in both "wide" and "long" format.

Usage

data("LongitudinalOverdispersedCounts")

Format

The "long" format dataframe, longData, has 4000 rows and the following variables (columns):

1. id: Factor; simulee ID code.

2. tiem: Numeric; represents the time metric, wave of assessment.

3. x1: Numeric; time-invariant covariate.

4. x2: Numeric; time-invariant covariate.

5. x3: Numeric; time-invariant covariate.

6. y: Numeric; the response ("dependent") variable.

The "wide" format dataset, wideData, is a numeric 1000x12 matrix containing the following variables (columns):

1. id: Simulee ID code.

2. x1: Time-invariant covariate.

3. x3: Time-invariant covariate.

4. x3: Time-invariant covariate.

5. y0: Response at initial wave of assessment.

6. y1: Response at first follow-up.

7. y2: Response at second follow-up.

8. y3: Response at third follow-up.

9. t0: Time variable at initial wave of assessment (in this case, 0).

10. t1: Time variable at first follow-up (in this case, 1).

11. t2: Time variable at second follow-up (in this case, 2).

12. t3: Time variable at third follow-up (in this case, 3).

Examples

data(LongitudinalOverdispersedCounts)
head(wideData)
str(longData)
#Let's try ordinary least-squares (OLS) regression:
olsmod <- lm(y~tiem+x1+x2+x3, data=longData)
#We will see in the diagnostic plots that the residuals are poorly approximated by normality, 
#and are heteroskedastic.  We also know that the residuals are not independent of one another, 
#because we have repeated-measures data:
plot(olsmod)
#In the summary, it looks like all of the regression coefficients are significantly different 
#from zero, but we know that because the assumptions of OLS regression are violated that 
#we should not trust its results:
summary(olsmod)

#Let's try a generalized linear model (GLM).  We'll use the quasi-Poisson quasilikelihood 
#function to see how well the y variable is approximated by a Poisson distribution 
#(conditional on time and covariates):
glm.mod <- glm(y~tiem+x1+x2+x3, data=longData, family="quasipoisson")
#The estimate of the dispersion parameter should be about 1.0 if the data are 
#conditionally Poisson.  We can see that it is actually greater than 2, 
#indicating overdispersion:
summary(glm.mod)

MxAlgebra Class

Description

MxAlgebra is an S4 class. An MxAlgebra object is a named entity. New instances of this class can be created using the function mxAlgebra.

Details

The MxAlgebra class has the following slots:

The ‘name’ slot is the name of the MxAlgebra object. Use of MxAlgebra objects in the mxConstraint function or an objective function requires reference by name.

The ‘formula’ slot is an expression containing the expression to be evaluated. These objects are operated on or related to one another using one or more operations detailed in the mxAlgebra help file.

The ‘result’ slot is used to hold the results of computing the expression in the ‘formula’ slot. If the containing model has not been executed, then the ‘result’ slot will hold a 0 x 0 matrix. Otherwise the slot will store the computed value of the algebra using the final estimates of the free parameters.

Slots may be referenced with the $ symbol. See the documentation for Classes and the examples in the mxAlgebra document for more information.

References

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

See Also

mxAlgebra, mxMatrix, MxMatrix

MxAlgebraFormula

Description

This is an internal class for the formulas used in mxAlgebra calls.

MxBaseExpectation

Description

The virtual base class for all expectations. Expectations contain enough information to generate simulated data. This is an internal class and should not be used directly.

See Also

mxExpectationNormal, mxExpectationRAM, mxExpectationLISREL, mxExpectationStateSpace, mxExpectationBA81

MxBaseFitFunction

Description

The virtual base class for all fit functions. This is an internal class and should not be used directly.

See Also

mxFitFunctionAlgebra, mxFitFunctionML, mxFitFunctionMultigroup, mxFitFunctionR, mxFitFunctionWLS, mxFitFunctionRow, mxFitFunctionGREML

MxBaseNamed

Description

This is an internal class and should not be used directly. It is the base class for named entities. Fit functions, expectations, and computes contain this class.

MxBaseObjectiveMetaData

Description

This is an internal class and should not be used directly. It is the virtual base class for all objective functions meta-data

MxBounds Class

Description

MxBounds is an S4 class. New instances of this class can be created using the function mxBounds.

Details

The MxBounds class has the following slots:

The 'min' and 'max' slots hold scalar numeric values for the lower and upper bounds on the list of parameters, respectively.

Parameters may be any free parameter or parameters from an MxMatrix object. Parameters may be referenced either by name or by referring to their position in the 'spec' matrix of an MxMatrix object. To affect an estimation or optimization, an MxBounds object must be included in an MxModel object with all referenced MxAlgebra and MxMatrix objects.

Slots may be referenced with the $ symbol. See the documentation for Classes and the examples in the mxBounds document for more information.

References

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

See Also

mxBounds for the function that creates MxBounds objects. MxMatrix and mxMatrix for free parameter specification. More information about the OpenMx package may be found here.

MxCI Class

Description

MxCI is an S4 class. An MxCI object is a named entity. New instances of this class can be created using the function mxCI. MxCI objects may be used as arguments in the mxModel function.

Details

The MxCI class has the following slots:

The reference slot contains a character vector of named free parameters, MxMatrices and MxAlgebras on which confidence intervals are desired. Individual elements of MxMatrices and MxAlgebras may be listed as well, using the syntax “matrix[row,col]” (see Extract for more information).

The lowerdelta and upperdelta slots give the changes in likelihoods used to define the confidence interval. The upper bound of the likelihood-based confidence interval is estimated by increasing the parameter estimate, leaving all other parameters free, until the model -2 log likelihood increased by ‘upperdelta’. The lower bound of the confidence interval is estimated by decreasing the parameter estimate, leaving all other parameters free, until the model -2 log likelihood increased by ‘lowerdata’.

Likelihood-based confidence intervals may be specified by including one or more MxCI objects in an MxModel object. Estimation of confidence intervals requires model optimization using the mxRun function with the ‘intervals’ argument set to TRUE. The calculation of likelihood-based confidence intervals can be computationally intensive, and may add a significant amount of time to model estimation when many confidence intervals are requested.

References

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

See Also

mxCI for creating MxCI objects. More information about the OpenMx package may be found here.

A character, list or NULL

Description

A character, list or NULL

A character or logical

Description

A character or logical

A character or integer

Description

A character or integer

The MxCompare Class

Description

The MxCompare Class

Details

This is an internal class structure. You should not use it directly. Use mxCompare instead.

MxCompute

Description

This is an internal class and should not be used directly.

Class "MxConstraint"

Description

MxConstraint is an S4 class. An MxConstraint object is a named entity. New instances of this class can be created using the function mxConstraint().

Details

Slots may be referenced with the $ symbol. See the documentation for Classes and the examples in the mxConstraint document for more information.

Slots

name:

Character string; the name of the object.

formula:

Object of class "MxAlgebraFormula". The MxAlgebra-like expression representing the constraint function.

alg1:

Object of class "MxCharOrNumber". For internal use.

alg2:

Object of class "MxCharOrNumber". For internal use.

relation:

Object of class "MxCharOrNumber". For internal use.

jac:

Object of class "MxCharOrNumber". Identifies the MxAlgebra representing the Jacobian for the constraint function.

linear:

Logical. For internal use.

strict:

Logical. Whether to require that all Jacobian entries reference free parameters.

verbose:

integer. For values greater than zero, enable runtime diagnostics.

Methods

$<-

signature(x = "MxConstraint")

$

signature(x = "MxConstraint")

imxDeparse

signature(object = "MxConstraint")

names

signature(x = "MxConstraint")

print

signature(x = "MxConstraint")

show

signature(object = "MxConstraint")

References

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

See Also

mxConstraint() for the function that creates MxConstraint objects.

Examples

showClass("MxConstraint")

MxData Class

Description

MxData is an S4 class. An MxData object is a named entity. New instances of this class can be created using the function mxData. MxData is an S4 class union. An MxData object is either NULL or a MxNonNullData object.

Details

The MxNonNullData class has the following slots:

The 'name' slot is the name of the MxData object.

The ‘observed’ slot is used to contain data, either as a matrix or as a data frame. Use of the data in this slot by other functions depends on the value of the 'type' slot. When 'type' is equal to 'cov' or 'cor', the data input into the 'matrix' slot should be a symmetric matrix or data frame.

The 'vector' slot is used to contain a vector of numeric values, which is used as a vector of means for MxData objects with 'type' equal to 'cov' or 'cor'. This slot may be used in estimation using the mxFitFunctionML function.

The 'type' slot may take one of four supported values:

raw

The contents of the ‘observed’ slot are treated as raw data. Missing values are permitted and must be designated as the system missing value. The 'vector' and 'numObs' slots cannot be specified, as the 'vector' argument is not relevant and the 'numObs' argument is automatically populated with the number of rows in the data. Data of this type may use the mxFitFunctionML function as its fit function in MxModel objects, which can deal with covariance estimation under full-information maximum likelihood.

cov

The contents of the ‘observed’ slot are treated as a covariance matrix. The 'vector' argument is not required, but may be included for estimations involving means. The 'numObs' slot is required. Data of this type may use fit functions such as the mxFitFunctionML, depending on the specified model.

cor

The contents of the ‘observed’ slot are treated as a correlation matrix. The 'vector' argument is not required, but may be included for estimations involving means. The 'numObs' slot is required. Data of this type may use fit functions such as the mxFitFunctionML, depending on the specified model.

The 'numObs' slot describes the number of observations in the data. If 'type' equals 'raw', then 'numObs' is automatically populated as the number of rows in the matrix or data frame in the ‘observed’ slot. If 'type' equals 'cov' or 'cor', then this slot must be input using the 'numObs' argument in the mxData function when the MxData argument is created.

MxData objects may not be included in MxAlgebra objects or use the mxFitFunctionAlgebra function. If these capabilities are desired, data should be appropriately input or transformed using the mxMatrix and mxAlgebra functions.

While column names are stored in the ‘observed’ slot of MxData objects, these names are not recognized as variable names in MxPath objects. Variable names must be specified using the 'manifestVars' argument of the mxModel function prior to use in MxPath objects.

The mxData function does not currently place restrictions on the size, shape, or symmetry of matrices input into the ‘observed’ argument. While it is possible to specify MxData objects as covariance or correlation matrices that do not have the properties commonly associated with these matrices, failure to correctly specify these matrices will likely lead to problems in model estimation.

References

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

See Also

mxData for creating MxData objects, matrix and data.frame for objects which may be entered as arguments in the 'matrix' slot. More information about the OpenMx package may be found here.

Create static data

Description

Internal static data class.

Details

Not to be used.

MxDirectedGraph

Description

This is an internal class and should not be used directly. It is a class for directed graphs.

MxExpectation

Description

This is an internal class and should not be used directly.

Class "MxExpectationGREML"

Description

MxExpectationGREML is a type of expectation class. It contains the necessary elements for specifying a GREML model. For more information, see mxExpectationGREML().

Objects from the Class

Objects can be created by calls of the form mxExpectationGREML(V, yvars, Xvars, addOnes, blockByPheno, staggerZeroes, dataset.is.yX, casesToDropFromV, REML, yhat).

Slots

V:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix to serve as the 'V' matrix.

yvars:

Character vector. Each string names a column of the raw dataset, to be used as a phenotype.

Xvars:

A list of data column names, specifying the covariates to be used with each phenotype.

addOnes:

Logical; pertains to data-handling at runtime.

blockByPheno:

Logical; pertains to data-handling at runtime.

staggerZeroes:

Logical; pertains to data-handling at runtime.

dataset.is.yX:

Logical; pertains to data-handling at runtime.

y:

Object of class "MxData". Its observed slot will contain the phenotype vector, 'y.'

X:

A matrix, to contain the 'X' matrix of covariates.

yXcolnames:

Character vector; used to store the column names of 'y' and 'X.'

casesToDrop:

Integer vector, specifying the rows and columns of the 'V' matrix to be removed at runtime.

b:

A matrix, to contain the vector of regression coefficients calculated at runtime.

bcov:

A matrix, to contain the sampling covariance matrix of the regression coefficients calculated at runtime.

numFixEff:

Integer number of covariates in 'X.'

REML:

Logical. Should restricted maximum-likelihood estimation be used?

yhat:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix to serve as the model-expected phenotypic mean vector.

fitted.values:

A matrix, specifically, the column vector of model-predicted phenotypic means calculated at runtime.

residuals:

A matrix, specifically, the column vector of residuals calculated at runtime.

dims:

Object of class "character".

numStats:

Numeric; number of observed statistics.

dataColumns:

Object of class "numeric".

name:

Object of class "character".

data:

Object of class "MxCharOrNumber".

.runDims:

Object of class "character".

Extends

Class "MxBaseExpectation", directly. Class "MxBaseNamed", by class "MxBaseExpectation", distance 2. Class "MxExpectation", by class "MxBaseExpectation", distance 2.

Methods

No methods defined with class "MxExpectationGREML" in the signature.

References

Kirkpatrick RM, Pritikin JN, Hunter MD, & Neale MC. (2021). Combining structural-equation modeling with genomic-relatedness matrix restricted maximum likelihood in OpenMx. Behavior Genetics 51: 331-342. doi:10.1007/s10519-020-10037-5

The first software implementation of "GREML":
Yang J, Lee SH, Goddard ME, Visscher PM. (2011). GCTA: a tool for genome-wide complex trait analysis. American Journal of Human Genetics 88: 76-82. doi:10.1016/j.ajhg.2010.11.011

One of the first uses of the acronym "GREML":
Benjamin DJ, Cesarini D, van der Loos MJHM, Dawes CT, Koellinger PD, et al. (2012). The genetic architecture of economic and political preferences. Proceedings of the National Academy of Sciences 109: 8026-8031. doi: 10.1073/pnas.1120666109

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

See Also

See mxExpectationGREML() for creating MxExpectationGREML objects, and for more information generally concerning GREML analyses, including a complete example. More information about the OpenMx package may be found here.

Examples

showClass("MxExpectationGREML")

MxFitFunction

Description

This is an internal class and should not be used directly.

Class "MxFitFunctionGREML"

Description

MxFitFunctionGREML is the fitfunction class for GREML analyses.

Objects from the Class

Objects can be created by calls of the form mxFitFunctionGREML(dV).

Slots

dV:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix object(s) to serve as the derivatives of 'V' with respect to free parameters.

dVnames:

Vector of character strings; names of the free parameters corresponding to slot dV. Provides the mapping from elements of augGrad and of rows and columns of augHess to free parameters.

MLfit:

Object of class "numeric", equal to the maximum-likelihood fitfunction value (as opposed to the restricted maximum-likelihood value).

numObsAdjust:

Object of class "integer". Number of observations adjustment.

aug:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix object used to "augment" the fitfunction value at each function evaluation during optimization.

augGrad:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix object(s) to serve as the first derivatives of aug with respect to free parameters.

augHess:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix object(s) to serve as the second derivatives of aug with respect to free parameters.

autoDerivType:

Object of class "character". Dictates whether fitfunction derivatives automatically calculated by OpenMx should be numerical or "semi-analytic."

infoMatType:

Object of class "character". Dictates whether to calculate the average- or expected-information matrix.

dyhat:

Object of class "MxCharOrNumber". Identifies the MxAlgebra or MxMatrix object(s) to serve as the derivatives of 'yhat' with respect to free parameters.

dyhatnames:

Vector of character strings; names of the free parameters corresponding to slot dyhat.

dNames:

Vector of character strings. If dV and/or dyhat have nonzero length, then populated at runtime by the set of non-redundant free-parameter names appearing in dVnames and/or dyhatnames.

.parallelDerivScheme:

Object of class "integer". Dictates how computation of the information matrix will be distributed across multiple threads. This slot is intended for use in testing and debugging by the OpenMx developers, and not to be modified by the end user.

info:

Object of class "list".

dependencies:

Object of class "integer".

expectation:

Object of class "integer".

vector:

Object of class "logical".

rowDiagnostics:

Object of class "logical".

result:

Object of class "matrix".

name:

Object of class "character".

Extends

Class "MxBaseFitFunction", directly. Class "MxBaseNamed", by class "MxBaseFitFunction", distance 2. Class "MxFitFunction", by class "MxBaseFitFunction", distance 2.

Methods

No methods defined with class "MxFitFunctionGREML" in the signature.

References

Kirkpatrick RM, Pritikin JN, Hunter MD, & Neale MC. (2021). Combining structural-equation modeling with genomic-relatedness matrix restricted maximum likelihood in OpenMx. Behavior Genetics 51: 331-342. doi:10.1007/s10519-020-10037-5

The first software implementation of "GREML":
Yang J, Lee SH, Goddard ME, Visscher PM. (2011). GCTA: a tool for genome-wide complex trait analysis. American Journal of Human Genetics 88: 76-82. doi:10.1016/j.ajhg.2010.11.011

One of the first uses of the acronym "GREML":
Benjamin DJ, Cesarini D, van der Loos MJHM, Dawes CT, Koellinger PD, et al. (2012). The genetic architecture of economic and political preferences. Proceedings of the National Academy of Sciences 109: 8026-8031. doi: 10.1073/pnas.1120666109

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

See Also

See mxFitFunctionGREML() for creating MxFitFunctionGREML objects. See mxExpectationGREML() for creating MxExpectationGREML objects, and for more information generally concerning GREML analyses, including a complete example. More information about the OpenMx package may be found here.

Examples

showClass("MxFitFunctionGREML")

MxFlatModel

Description

This is an internal class and should not be used.

MxInterval

Description

This is an internal class and should not be used directly.

See Also

mxCI

MxLISRELModel

Description

This is an internal class and should not be used directly.

An optional list

Description

An optional list

MxMatrix Class

Description

MxMatrix is a virtual S4 class that comprises the nine types of matrix objects used by OpenMx (see mxMatrix() for details). An MxMatrix object is a named entity. New instances of this class can be created using the function mxMatrix(). MxMatrix objects may be used as arguments in other functions from the OpenMx package, including mxAlgebra(), mxConstraint(), and mxModel().

Objects from the Class

All nine types of object that the class comprises can be created via mxMatrix().

Slots

name:

Character string; the name of the MxMatrix object. Note that this is the object's "Mx name" (so to speak), which identifies it in OpenMx's internal namespace, rather than the symbol identifying it in R's workspace. Use of MxMatrix objects in an mxAlgebra or mxConstraint function requires reference by name.

values:

Numeric matrix of values. If an element is specified as a fixed parameter in the 'free' matrix, then the element in the 'values' matrix is treated as a constant value and cannot be altered or updated by an objective function when included in an mxRun() function. If an element is specified as a free parameter in the 'free' matrix, the element in the 'value' matrix is considered a starting value and can be changed by an objective function when included in an mxRun() function.

labels:

Matrix of character strings which provides the labels of free and fixed parameters. Fixed parameters with identical labels must have identical values. Free parameters with identical labels impose an equality constraint. The same label cannot be applied to a free parameter and a fixed parameter. A free parameter with the label 'NA' implies a unique free parameter, that cannot be constrained to equal any other free parameter.

free:

Logical matrix specifying whether each element is free versus fixed. An element is a free parameter if-and-only-if the corresponding value in the 'free' matrix is 'TRUE'. Free parameters are elements of an MxMatrix object whose values may be changed by a fitfunction when that MxMatrix object is included in an MxModel object and evaluated using the mxRun() function.

lbound:

Numeric matrix of lower bounds on free parameters.

ubound:

Numeric matrix of upper bounds on free parameters.

.squareBrackets:

Logical matrix; used internally by OpenMx. Identifies which elements have labels with square brackets in them.

.persist:

Logical; used internally by OpenMx. Governs how mxRun() handles the MxMatrix object when it is inside the MxModel being run.

.condenseSlots:

Logical; used internally by OpenMx. If FALSE, then the matrices in the 'values', 'labels', 'free', 'lbound', and 'ubound' slots are all of equal dimensions. If TRUE, then the last four of those slots will "condense" a matrix consisting entirely of FALSE or NA down to 1x1.

display:

Character string; used internally by OpenMx when parsing MxAlgebras.

dependencies:

Integer; used internally by OpenMx when parsing MxAlgebras.

Methods

$

signature(x = "MxMatrix"): ...

$<-

signature(x = "MxMatrix"): ...

[

signature(x = "MxMatrix"): ...

[<-

signature(x = "MxMatrix"): ...

dim

signature(x = "MxMatrix"): ...

dimnames

signature(x = "MxMatrix"): ...

dimnames<-

signature(x = "MxMatrix"): ...

length

signature(x = "MxMatrix"): ...

names

signature(x = "MxMatrix"): ...

ncol

signature(x = "MxMatrix"): ...

nrow

signature(x = "MxMatrix"): ...

print

signature(x = "MxMatrix"): ...

show

signature(object = "MxMatrix"): ...

Note that some methods are documented separately (see below, under "See Also").

References

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

See Also

mxMatrix() for creating MxMatrix objects. Note that functions imxCreateMatrix(), imxDeparse(), imxSquareMatrix(), imxSymmetricMatrix(), and imxVerifyMatrix() are separately documented methods for this class. More information about the OpenMx package may be found here.

Examples

showClass("MxMatrix")

MxModel Class

Description

MxModel is an S4 class. An MxModel object is a named entity.

Details

The ‘matrices’ slot contains a list of the MxMatrix objects included in the model. These objects are listed by name. Two objects may not share the same name. If a new MxMatrix is added to an MxModel object with the same name as an MxMatrix object in that model, the added version replaces the previous version. There is no imposed limit on the number of MxMatrix objects that may be added here.

The ‘algebras’ slot contains a list of the MxAlgebra objects included in the model. These objects are listed by name. Two objects may not share the same name. If a new MxAlgebra is added to an MxModel object with the same name as an MxAlgebra object in that model, the added version replaces the previous version. All MxMatrix objects referenced in the included MxAlgebra objects must be included in the ‘matrices’ slot prior to estimation. There is no imposed limit on the number of MxAlgebra objects that may be added here.

The ‘constraints’ slot contains a list of the MxConstraint objects included in the model. These objects are listed by name. Two objects may not share the same name. If a new MxConstraint is added to an MxModel object with the same name as an MxConstraint object in that model, the added version replaces the previous version. All MxMatrix objects referenced in the included MxConstraint objects must be included in the ‘matrices’ slot prior to estimation. There is no imposed limit on the number of MxConstraint objects that may be added here.

The ‘intervals’ slot contains a list of the confidence intervals requested by included MxCI objects. These objects are listed by the free parameters, MxMatrices and MxAlgebras referenced in the MxCI objects, not the list of MxCI objects themselves. If a new MxCI object is added to an MxModel object referencing one or more free parameters MxMatrices or MxAlgebras previously listed in the ‘intervals’ slot, the new confidence interval(s) replace the existing ones. All listed confidence intervals must refer to free parameters MxMatrices or MxAlgebras in the model.

The ‘latentVars’ slot contains a list of latent variable names, which may be referenced by MxPath objects. This slot defaults to 'NA', and is only used when the mxPath function is used. In the context of a RAM model, this slot accepts a character vector of variable names. However, the LISREL model is partitioned into exogenous and endogenous parts. Both exogenous and endogenous variables can be specified using a list like, list(endo='a', exo='b'). If a character vector is passed to a LISREL model then those variables will be assumed endogenous.

The ‘manifestVars’ slot contains a list of latent variable names, which may be referenced by MxPath objects. This slot defaults to 'NA', and is only used when the mxPath function is used. In the context of a RAM model, this slot accepts a character vector of variable names. However, the LISREL model is partitioned into exogenous and endogenous parts. Both exogenous and endogenous variables can be specified using a list like, list(endo='a', exo='b'). If a character vector is passed to a LISREL model then those variables will be assumed endogenous.

The ‘data’ slot contains an MxData object. This slot must be filled prior to execution when a fitfunction referencing data is used. Only one MxData object may be included per model, but submodels may have their own data in their own ‘data’ slots. If an MxData object is added to an MxModel which already contains an MxData object, the new object replaces the existing one.

The ‘submodels’ slot contains references to all of the MxModel objects included as submodels of this MxModel object. Models held as arguments in other models are considered to be submodels. These objects are listed by name. Two objects may not share the same name. If a new submodel is added to an MxModel object with the same name as an existing submodel, the added version replaces the previous version. When a model containing other models is executed using mxRun, all included submodels are executed as well. If the submodels are dependent on one another, they are treated as one larger model for purposes of estimation.

The ‘independent’ slot contains a logical value indicating whether or not the model is independent. 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 submodels of another MxModel objects, so that they are simultaneously optimized.

The ‘options’ slot contains a list of options for the model. The name of each entry in the list is the option name to be used at runtime. The values in this list are the values of the optimizer options. The standard interface for updating options is through the mxOption function.

The ‘output’ slot contains a list of output added to the model by the mxRun function. Output includes parameter estimates, optimization information, model fit, and other information. If a model has not been optimized using the mxRun function, the 'output' slot will be 'NULL'.

Named entities in MxModel objects may be viewed and referenced by name using 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 mxModel for more information.

Objects from the Class

Objects can be created by calls of the form mxModel().

Slots

name:

Character string. The name of the model object.

matrices:

List of the model's MxMatrix objects.

algebras:

List of the model's MxAlgebra objects.

constraints:

List of the model's MxConstraint objects.

intervals:

List of the model's MxInterval objects, requested via mxCI().

penalties:

List of the model's MxPenalty objects.

latentVars:

"Latent variables;" object of class "MxCharOrList".

manifestVars:

"Manifest variables;" object of class "MxCharOrList".

data:

Object of class MxData.

submodels:

List of MxModel objects.

expectation:

Object of class MxExpectation; dictates the model's specification.

fitfunction:

Object of class MxFitFunction; dictates the cost function to be minimized when fitting the model.

compute:

Object of class MxCompute–the model's compute plan, which contains instructions on what the model is to compute and how to do so.

independent:

Logical; is the model to be run independently from other submodels?

options:

List of model-specific options, set by mxOption().

output:

List of model output produced during a call to mxRun().

.newobjects:

Logical; for internal use.

.resetdata:

Logical; for internal use.

.wasRun:

Logical; for internal use.

.modifiedSinceRun:

Logical; for internal use.

.version:

Object of class "package_version"; for internal use.

Methods

$

signature(x = "MxModel"): Accessor. Accesses slots by slot-name. Also accesses constituent named entities, by name.

$<-

signature(x = "MxModel"): Assignment. Generally, this method will not allow the user to make unsafe changes to the MxModel object.

[[

signature(x = "MxModel"): Accessor for constituent named entities.

[[<-

signature(x = "MxModel"): Assignment for a named entity.

names

signature(x = "MxModel"): Returns names of slots and named entities.

print

signature(x = "MxModel"): "Print" method.

show

signature(object = "MxModel"): "Show" method.

Note that imxInitModel(), imxModelBuilder(), imxTypeName(), and imxVerifyModel() are separately documented methods for class "MxModel".

References

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

See Also

mxExpectationRAM, mxExpectationLISREL, mxModel for creating MxModel objects. More information about the OpenMx package may be found here.

An optional character

Description

An optional character

A character, integer, or NULL

Description

A character, integer, or NULL

An optional data.frame

Description

An optional data.frame

An optional data.frame or matrix

Description

An optional data.frame or matrix

An optional integer

Description

An optional integer

An optional logical

Description

This is an internal class, the union of NULL and logical.

An optional matrix

Description

An optional matrix

An optional numeric

Description

An optional numeric

MxPenalty

Description

This is an internal class and should not be used directly.

MxRAMGraph

Description

This is an internal class and should not be used directly. It is a class for RAM directed graphs.

MxRAMModel

Description

This is an internal class and should not be used directly.

A package_version or character

Description

A package_version or character

Named Entities

Description

A named entity is an S4 object that can be referenced by name.

Details

Every named entity is guaranteed to have a slot called "name". Within a model, the named entities of that model can be accessed using the $ operator. Access is limited to one nesting depth, such that if 'B' is a submodel of 'A', and 'C' is a matrix of 'B', then 'C' must be accessed using A$B$C.

The following S4 classes are named entities in the OpenMx library: MxAlgebra, MxConstraint, MxMatrix, MxModel, MxData, and MxObjective.

Examples

library(OpenMx)

# Create a model, add a matrix to it, and then access the matrix by name.

testModel <- mxModel(model="anEmptyModel")

testMatrix <- mxMatrix(type="Full", nrow=2, ncol=2, values=c(1,2,3,4), name="yourMatrix")

yourModel <- mxModel(testModel, testMatrix, name="noLongerEmpty")

yourModel$yourMatrix

Oscillator Data for Latent Differential Equations

Description

Data set used in some of OpenMx's examples, for instance the LDE demo. The data were simulated by Steven M. Boker according to a noisy oscillator model.

Usage

data("Oscillator")

Format

A data frame with 100 observations on the following 1 numeric variable.

x

Noisy oscillator value

Details

The data appear to be sinusoidal with exponential decay on the amplitude. The rows of data are different times. The column is the variable.

Source

Simulated. Pulled from https://openmx.ssri.psu.edu/node/144

References

Boker, S., Neale, M., & Rausch, J. (2004). Latent differential equation modeling with multivariate multi-occasion indicators. In Recent developments on structural equation models van Montfort, K., Oud, H, and Satorra, A. (Eds.). 151-174. Springer, Dordrecht.

Examples

data(Oscillator)
plot(Oscillator$x, type='l')

Convert a numeric or character vector into an optimizer status code factor

Description

Below we provide a brief, technical description of each status code followed by a more colloquial, less precise desciption.

• 0,‘OK’: Optimization succeeded. Everything seems fine.

• 1,‘OK/green’: Optimization succeeded, but the sequence of iterates has not yet converged (Mx status GREEN). This condition is only detected by NPSOL. The solution is likely okay. You might want to re-run the model from its final esimates to resolve this.

• 2,‘infeasible linear constraint’: The linear constraints and bounds could not be satisfied. The problem has no feasible solution. Right now, it should not be possible obtain this status code, so call Ripley's.

• 3,‘infeasible non-linear constraint’: The nonlinear constraints and bounds could not be satisfied. The problem may have no feasible solution. Sometimes this happens when your starting values do not satisfy the constraints. Also, optimization could not satisfy the constraints and get a better fit.

• 4,‘iteration limit’: Optimization was stopped prematurely because the iteration limit was reached (Mx status BLUE). You might want to rerun: m1 = mxRun(m1) or increase the iteration limit (see mxOption). The optimizer took all the steps it could and did not finish. You can increase the number of steps or get better starting values.

• 5,‘not convex’: The Hessian at the solution does not appear to be convex (Mx status RED). There may be more than one solution to the model. See mxCheckIdentification. I would not trust this solution; it does not appear to be a good one. Perhaps, try mxTryHard.

• 6,‘nonzero gradient’: The model does not satisfy the first-order optimality conditions to the required accuracy, and no improved point for the merit function could be found during the final linesearch (Mx status RED). I would not trust this solution; it does not appear to be a good one. To search nearby, see mxTryHard.

• 7,‘bad deriv’: You have provided analytic derivatives. However, your provided derivatives differ too much from numerically approximated derivatives. Double check your math.

• 9,‘internal error’: An input parameter was invalid. The most likely cause is a bug in the code. Please report occurrences to the OpenMx developers.

• 10,‘infeasible start’: Starting values were infeasible. Modify the start values for one or more parameters. For instance, set means to their measured value, or set variances and covariances to plausible values. See mxAutoStart and mxTryHard.

Usage

as.statusCode(code)

Arguments

See Also

mxBootstrap summary.MxModel

Vectorize By Column

Description

This function returns the vectorization of an input matrix in a column by column traversal of the matrix. The output is returned as a column vector.

Usage

cvectorize(x)

Arguments

See Also

rvectorize, vech, vechs

Examples

cvectorize(matrix(1:9, 3, 3))
cvectorize(matrix(1:12, 3, 4))

Demonstration data for a one factor model

Description

Data set used in some of OpenMx's examples.

Usage

data("demoOneFactor")

Format

A data frame with 500 observations on the following 5 numeric variables.

x1

x2

x3

x4

x5

Details

Variables x1-x5 are typically used as indicators of the latent trait.

Source

Simulated.

References

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

Examples

data(demoOneFactor)
cov(demoOneFactor)
cor(demoOneFactor)

Demonstration data for a two factor model

Description

Data set used in some of OpenMx's examples.

Usage

data("demoTwoFactor")

Format

A data frame with 500 observations on the following 10 numeric variables.

x1

x2

x3

x4

x5

y1

y2

y3

y4

y5

Details

Variables x1-x5 are typically used as indicators of one latent trait. Variables y1-y5 are typically used as indicators of another latent trait.

Source

Simulated.

References

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

Examples

data(demoTwoFactor)
cov(demoTwoFactor)
cor(demoTwoFactor)

Extract Diagonal of a Matrix

Description

Given an input matrix, diag2vec returns a column vector of the elements along the diagonal.

Usage

diag2vec(x)

Arguments

Details

Similar to the function diag, except that the input argument is always treated as a matrix (i.e., it doesn't have diag()'s functions of returning an Identity matrix from an nrow specification, nor to return a matrix wrapped around a diagonal if provided with a vector). To get vector2matrix functionality, call vec2diag.

See Also

vec2diag

Examples

diag2vec(matrix(1:9, nrow=3))
#      [,1]
# [1,]    1
# [2,]    5
# [3,]    9

diag2vec(matrix(1:12, nrow=3, ncol=4))
#      [,1]
# [1,]    1
# [2,]    5
# [3,]    9

Example twin extended kinship data: DZ female data

Description

Data for extended twin example ETC88.R

Usage

data("dzfData")

Format

A data frame with 2007 observations on the following 37 variables.

famid

a numeric vector

e1

a numeric vector

e2

a numeric vector

e3

a numeric vector

e4

a numeric vector

e5

a numeric vector

e6

a numeric vector

e7

a numeric vector

e8

a numeric vector

e9

a numeric vector

e10

a numeric vector

e11

a numeric vector

e12

a numeric vector

e13

a numeric vector

e14

a numeric vector

e15

a numeric vector

e16

a numeric vector

e17

a numeric vector

e18

a numeric vector

a1

a numeric vector

a2

a numeric vector

a3

a numeric vector

a4

a numeric vector

a5

a numeric vector

a6

a numeric vector

a7

a numeric vector

a8

a numeric vector

a9

a numeric vector

a10

a numeric vector

a11

a numeric vector

a12

a numeric vector

a13

a numeric vector

a14

a numeric vector

a15

a numeric vector

a16

a numeric vector

a17

a numeric vector

a18

a numeric vector

Examples

data(dzfData)
str(dzfData)

Example twin extended kinship data: DZ Male data

Description

Data for extended twin example ETC88.R

Usage

data("dzmData")

Format

A data frame with 1990 observations on the following 37 variables.

famid

a numeric vector

e1

a numeric vector

e2

a numeric vector

e3

a numeric vector

e4

a numeric vector

e5

a numeric vector

e6

a numeric vector

e7

a numeric vector

e8

a numeric vector

e9

a numeric vector

e10

a numeric vector

e11

a numeric vector

e12

a numeric vector

e13

a numeric vector

e14

a numeric vector

e15

a numeric vector

e16

a numeric vector

e17

a numeric vector

e18

a numeric vector

a1

a numeric vector

a2

a numeric vector

a3

a numeric vector

a4

a numeric vector

a5

a numeric vector

a6

a numeric vector

a7

a numeric vector

a8

a numeric vector

a9

a numeric vector

a10

a numeric vector

a11

a numeric vector

a12

a numeric vector

a13

a numeric vector

a14

a numeric vector

a15

a numeric vector

a16

a numeric vector

a17

a numeric vector

a18

a numeric vector

Examples

data(dzmData)
str(dzmData)

Example twin extended kinship data: DZ opposite sex twins

Description

Data for extended twin example ETC88.R

Usage

data("dzoData")

Format

A data frame with 3981 observations on the following 37 variables.

famid

a numeric vector

e1

a numeric vector

e2

a numeric vector

e3

a numeric vector

e4

a numeric vector

e5

a numeric vector

e6

a numeric vector

e7

a numeric vector

e8

a numeric vector

e9

a numeric vector

e10

a numeric vector

e11

a numeric vector

e12

a numeric vector

e13

a numeric vector

e14

a numeric vector

e15

a numeric vector

e16

a numeric vector

e17

a numeric vector

e18

a numeric vector

a1

a numeric vector

a2

a numeric vector

a3

a numeric vector

a4

a numeric vector

a5

a numeric vector

a6

a numeric vector

a7

a numeric vector

a8

a numeric vector

a9

a numeric vector

a10

a numeric vector

a11

a numeric vector

a12

a numeric vector

a13

a numeric vector

a14

a numeric vector

a15

a numeric vector

a16

a numeric vector

a17

a numeric vector

a18

a numeric vector

Examples

data(dzoData)
str(dzoData)

Eigenvector/Eigenvalue Decomposition

Description

eigenval computes the real parts of the eigenvalues of a square matrix. eigenvec computes the real parts of the eigenvectors of a square matrix. ieigenval computes the imaginary parts of the eigenvalues of a square matrix. ieigenvec computes the imaginary parts of the eigenvectors of a square matrix. eigenval and ieigenval return nx1 matrices containing the real or imaginary parts of the eigenvalues, sorted in decreasing order of the modulus of the complex eigenvalue. For eigenvalues without an imaginary part, this is equivalent to sorting in decreasing order of the absolute value of the eigenvalue. (See Mod for more info.) eigenvec and ieigenvec return nxn matrices, where each column corresponds to an eigenvector. These are sorted in decreasing order of the modulus of their associated complex eigenvalue.

Usage

eigenval(x)
eigenvec(x)
ieigenval(x)
ieigenvec(x)

Arguments

Details

Eigenvectors returned by eigenvec and ieigenvec are normalized to unit length.

See Also

eigen

Examples

A <- mxMatrix(values = runif(25), nrow = 5, ncol = 5, name = 'A')
G <- mxMatrix(values = c(0, -1, 1, -1), nrow=2, ncol=2, name='G')

model <- mxModel(A, G, name = 'model')

mxEval(eigenvec(A), model)
mxEval(eigenvec(G), model)
mxEval(eigenval(A), model)
mxEval(eigenval(G), model)
mxEval(ieigenvec(A), model)
mxEval(ieigenvec(G), model)
mxEval(ieigenval(A), model)
mxEval(ieigenval(G), model)

Bivariate twin data, wide-format from Classic Mx Manual

Description

Data set used in some of OpenMx's examples.

Usage

data("example1")

Format

A data frame with 400 observations on the following variables.

IDNum

Twin pair ID

Zygosity

Zygosity of the twin pair

X1

X variable for twin 1

Y1

Y variable for twin 1

X2

X variable for twin 2

Y2

Y variable for twin 2

Details

Same as example2 but in wide format instead of tall.

Source

Classic Mx Manual.

References

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

Examples

data(example1)
plot(X2 ~ X1, data = example1)

Bivariate twin data, long-format from Classic Mx Manual

Description

Data set used in some of OpenMx's examples.

Usage

data("example2")

Format

A data frame with 800 observations on the following variables.

IDNum

ID number

TwinNum

Twin ID number

Zygosity

Zygosity of the twin

X

X variable for twins 1 and 2

Y

Y variable for twins 1 and 2

Details

Same as example1 but in tall format instead of wide.

Source

Classic Mx Manual.

References

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

Examples

data(example2)
plot(Y ~ X, data = example2)

Matrix exponential

Description

Matrix exponential

Usage

expm(x)

Arguments

Example Factor Analysis Data

Description

Data set used in some of OpenMx's examples.

Usage

data("factorExample1")

Format

A data frame with 500 observations on the following variables.

x1

x2

x3

x4

x5

x6

x7

x8

x9

Details

This appears to be a three factor model, but perhaps with an odd loading structure.

Source

Simulated

References

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

Examples

data(factorExample1)
round(cor(factorExample1), 2)

factanal(covmat=cov(factorExample1), factors=3, rotation="promax")

Example Factor Analysis Data for Scaling the Model

Description

Data set used in some of OpenMx's examples.

Usage

data("factorScaleExample1")

Format

A data frame with 200 observations on the following variables.

X1

X2

X3

X4

X5

X6

X7

X8

X9

X10

X11

X12

Details

This appears to be a three factor model with factor 1 loading on X1-X4, factor 2 on X5-X8, and factor 3 on X9-X12.

Source

Simulated

References

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

Examples

data(factorScaleExample1)
round(cor(factorScaleExample1), 2)

Example Factor Analysis Data for Scaling the Model

Description

Data set used in some of OpenMx's examples.

Usage

data("factorScaleExample2")

Format

A data frame with 200 observations on the following variables.

X1

X2

X3

X4

X5

X6

X7

X8

X9

X10

X11

X12

Details

Three-factor data with factor 1 loading on X1-X4, factor 2 on X5-X8, and factor 3 on X9-X12. It differs from factorScaleExample1 in the scaling of the variables.

Source

Simulated

References

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

Examples

data(factorScaleExample2)
round(cor(factorScaleExample2), 2)

data(factorScaleExample2)
plot(sapply(factorScaleExample1, var), type='l', ylim=c(0, 6), lwd=3)
lines(1:12, sapply(factorScaleExample2, var), col='blue', lwd=3)

Add dependencies

Description

If there is an expectation, then the fitfunction should always depend on it. Hence, subclasses that implement this method must ignore the passed-in dependencies and use "dependencies <- callNextMethod()" instead.

Usage

## S4 method for signature 'MxBaseFitFunction'
genericFitDependencies(.Object, flatModel, dependencies)

Arguments

Add a dependency

Description

The dependency tracking system ensures that algebra and fitfunctions are not recomputed if their inputs have not changed. Dependency information is computed prior to handing the model off to the optimizer to reduce overhead during optimization.

Usage

imxAddDependency(source, sink, dependencies)

Arguments

Details

Each free parameter keeps track of all the objects that store that free parameter and the transitive closure of all algebras and fit functions that depend on that free parameter. Similarly, each definition variable keeps track of all the objects that store that free parameter and the transitive closure of all the algebras and fit functions that depend on that free parameter. At each iteration of the optimization, when the free parameter values are updated, all of the dependencies of that free parameter are marked as dirty (see omxFitFunction.repopulateFun). After an algebra or fit function is computed, omxMarkClean() is called to to indicate that the algebra or fit function is updated. Similarly, when definition variables are populated in FIML, all of the dependencies of the definition variables are marked as dirty. Particularly for FIML, the fact that non-definition-variable dependencies remain clean is a big performance gain.

imxAutoOptionValue

Description

Convert "Auto" placeholders in global mxOptions to actual default values.

Usage

imxAutoOptionValue(optionName, optionList = options()$mxOption)

Arguments

Details

This is an internal function exported for documentation purposes. Its primary purpose is to convert the on-load value of "Auto"to valid values for mxOptions ‘Gradient step size’, ‘Gradient iterations’, and ‘Function precision’–respectively, 1.0e-7, 1L, and 1e-14.

imxCheckMatrices

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxCheckMatrices(model)

Arguments

imxCheckVariables

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxCheckVariables(flatModel, namespace)

Arguments

Condense/de-condense slots of an MxMatrix

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxConDecMatrixSlots(object)

Arguments

imxConstraintRelations

Description

A string vector of valid constraint binary relations.

Usage

imxConstraintRelations

Format

An object of class character of length 3.

imxConvertIdentifier

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxConvertIdentifier(identifiers, modelname, namespace, strict = FALSE)

Arguments

imxConvertLabel

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxConvertLabel(label, modelname, dataname, namespace)

Arguments

imxConvertSubstitution

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxConvertSubstitution(substitution, modelname, namespace)

Arguments

Create a matrix

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxCreateMatrix(
  .Object,
  labels,
  values,
  free,
  lbound,
  ubound,
  nrow,
  ncol,
  byrow,
  name,
  condenseSlots,
  joinKey,
  joinModel
)

Arguments

Valid types of data that can be contained by MxData

Description

Valid types of data that can be contained by MxData

Usage

imxDataTypes

Format

An object of class character of length 4.

imxDefaultGetSlotDisplayNames

Description

Returns a list of display-friendly object slot names This is an internal function exported for those people who know what they are doing.

Usage

imxDefaultGetSlotDisplayNames(x, pattern = ".*")

Arguments

Deparse for MxObjects

Description

Deparse for MxObjects

Usage

imxDeparse(object, indent = "   ")

Arguments

Are submodels dependence?

Description

Are submodels dependence?

Usage

imxDependentModels(model)

Arguments

imxDetermineDefaultOptimizer

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxDetermineDefaultOptimizer()

Details

Returns a character, the default optimizer

A C implementation of dmvnorm

Description

This API is visible to permit testing. Please do not use.

Usage

imxDmvnorm(loc, mean, sigma)

Arguments

imxEvalByName

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxEvalByName(name, model, compute = FALSE, show = FALSE)

Arguments

imxExtractMethod

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxExtractMethod(model, index)

Arguments

imxExtractNames

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxExtractNames(lst)

Arguments

imxExtractReferences

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxExtractReferences(lst)

Arguments

imxExtractSlot

Description

Checks for and extracts a slot from the object This is an internal function exported for those people who know what they are doing.

Usage

imxExtractSlot(x, name)

Arguments

Remove hierarchical structure from model

Description

Remove hierarchical structure from model

Usage

imxFlattenModel(model, namespace, unsafe = FALSE)

Arguments

Freeze model

Description

Remove free parameters and fit function from model.

Usage

imxFreezeModel(model)

Arguments

imxGenSwift

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxGenSwift(tc, sites, sfile)

Arguments

imxGenerateLabels

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxGenerateLabels(model)

Arguments

imxGenerateNamespace

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxGenerateNamespace(model)

Arguments

imxGenericModelBuilder

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxGenericModelBuilder(
  model,
  lst,
  name,
  manifestVars,
  latentVars,
  productVars,
  submodels,
  remove,
  independent
)

Arguments

Resize an MxMatrix while preserving entries

Description

Resize an MxMatrix while preserving entries

Usage

imxGentleResize(matrix, dimnames)

Arguments

Value

a resized MxMatrix

Examples

m1 <- mxMatrix(values=1:9, nrow=3, ncol=3,
               dimnames=list(paste0('r',1:3), paste0('c',1:3)))

imxGentleResize(m1, dimnames=list(paste0('r',c(1,3,5)),
                                  paste0('c',c(2,4,6))))

imxGetNumThreads

Description

This is an internal function exported for those people who know what they are doing.

This function hard codes responses to a set of environments, like detecting snowfall, or running on a cluster where "OMP_NUM_THREADS" is set or otherwise returning 1 or 2 cores to avoid consuming all the resources on CRAN's test machines during release cycles.

This makes it not suitable for getting the number of available threads.

To get the number of cores available locally you want omxDetectCores or perhaps the detectCores function in the parallel package.

Usage

imxGetNumThreads()

imxGetSlotDisplayNames

Description

Returns a list of display-friendly object slot names This is an internal function exported for those people who know what they are doing.

Usage

imxGetSlotDisplayNames(
  object,
  pattern = ".*",
  slotList = slotNames(object),
  showDots = FALSE,
  showEmpty = FALSE
)

Arguments

imxHasAlgebraOnPath

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model (or any of its submodels) either (1) has labels on MxPaths that reference one or more MxAlgebras, or (2) defines any of the RAM matrices as MxAlgebras.

Usage

imxHasAlgebraOnPath(model, submodels = TRUE, strict = FALSE)

Arguments

imxHasConstraint

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model (or its submodels) has at least one MxConstraint.

Usage

imxHasConstraint(model)

Arguments

imxHasDefinitionVariable

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model (or its submodels) has at least one definition variable.

Usage

imxHasDefinitionVariable(model)

Arguments

imxHasNPSOL

Description

imxHasNPSOL

Usage

imxHasNPSOL()

Value

Returns TRUE if the NPSOL proprietary optimizer is compiled and linked with OpenMx. Otherwise FALSE.

imxHasOpenMP

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxHasOpenMP()

imxHasPenalty

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model (or its submodels) has any penalties.

Usage

imxHasPenalty(model)

Arguments

imxHasThresholds

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model (or its submodels) has any thresholds.

Usage

imxHasThresholds(model, submodels = TRUE)

Arguments

imxHasWLS

Description

This is an internal function exported for those people who know what they are doing. This function checks if a model uses a fitfunction with WLS units.

Usage

imxHasWLS(model)

Arguments

imxIdentifier

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxIdentifier(namespace, name)

Arguments

Are submodels independent?

Description

Are submodels independent?

Usage

imxIndependentModels(model)

Arguments

imxInitModel

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxInitModel(model)

Arguments

imxIsDefinitionVariable

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxIsDefinitionVariable(name)

Arguments

imxIsMultilevel

Description

This is an internal function exported for those people who know what they are doing. If you don't know what you're doing, but want to, here's a brief description of the function. You give this function an MxModel. It returns TRUE if the model is multilevel and FALSE otherwise.

Usage

imxIsMultilevel(model)

Arguments

imxIsPath

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxIsPath(value)

Arguments

imxIsStateSpace

Description

This is an internal function exported for those people who know what they are doing. If you don't know what you're doing, but want to, here's a brief description of the function. You give this function an MxModel. It returns TRUE if the model is a state space model and FALSE otherwise.

Usage

imxIsStateSpace(model)

Arguments

imxLocateFunction

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxLocateFunction(function_name)

Arguments

imxLocateIndex

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxLocateIndex(model, name, referant)

Arguments

imxLocateLabel

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxLocateLabel(label, model, parameter)

Arguments

Test thread-safe output code

Description

This is the code that the backend uses to write diagnostic information to standard error. This function should not be called from R. We make it available only for testing.

Usage

imxLog(str)

Arguments

imxLookupSymbolTable

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxLookupSymbolTable(name)

Arguments

imxModelBuilder

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxModelBuilder(
  model,
  lst,
  name,
  manifestVars,
  latentVars,
  productVars,
  submodels,
  remove,
  independent
)

Arguments

Details

TODO: It probably makes sense to split this into separate methods. For example, modelAddVariables and modelRemoveVariables could be their own methods. This would reduce some cut&paste duplication.

imxModelTypes

Description

A list of supported model types

Usage

imxModelTypes

Format

An object of class list of length 3.

imxMpiWrap

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxMpiWrap(fun)

Arguments

Run an classic mx script

Description

For this to work, classic mx must be installed, and callable from the command line.

Usage

imxOriginalMx(mx.filename, output.directory)

Arguments

Value

processed matrix output.

Examples

## Not run: 
output = imxOriginalMx(mx.filename = "power1.mx", "~/Desktop")

## End(Not run)

imxPPML

Description

Potentially enable the PPML optimization for the given model.

Usage

imxPPML(model, flag = TRUE)

Arguments

imxPPML.Test.Battery

Description

PPML can be applied to a number of special cases. This function will test the given model for all of these special cases.

Usage

imxPPML.Test.Battery(
  model,
  verbose = FALSE,
  testMissingness = TRUE,
  testPermutations = TRUE,
  testEstimates = TRUE,
  testFakeLatents = TRUE,
  tolerances = c(0.001, 0.001, 0.001)
)

Arguments

Details

Requirements for model passed to this function: - Path-specified - Means vector must be present - Covariance data (with data means vector) - (Recommended) All error variances should be specified on the diagonal of the S matrix, and not as a latent with a loading only on to that manifest

Function will test across all permutations of: - Covariance vs Raw data - Means vector present vs Means vector absent - Path versus Matrix specification - All orders of permutations of latents with manifests

imxPPML.Test.Test

Description

Test that PPML solutions match non-PPML solutions.

Usage

imxPPML.Test.Test(
  model,
  checkLL = TRUE,
  checkByName = FALSE,
  tolerance = 0.5,
  testEstimates = TRUE
)

Arguments

Details

This is an internal function used for comparing PPML and non-PPML solutions. Generally, non-developers will not use this function.

imxPenaltyTypes

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxPenaltyTypes

Format

An object of class character of length 3.

Details

Types of regularization penalties.

imxPreprocessModel

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxPreprocessModel(model)

Arguments

imxReplaceMethod

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxReplaceMethod(x, name, value)

Arguments

Replace parts of a model

Description

Replace parts of a model

Usage

imxReplaceModels(model, replacements)

Arguments

imxReplaceSlot

Description

Checks for and replaces a slot from the object This is an internal function exported for those people who know what they are doing.

Usage

imxReplaceSlot(x, name, value, check = TRUE)

Arguments

Report backend progress

Description

Prints a show status string to the console without emitting a newline.

Usage

imxReportProgress(info, eraseLen)

Arguments

Examples

library(OpenMx)

previousLen <<- 0

easyReportProcess <- function(msg) {
	imxReportProgress(msg, previousLen)
	previousLen <<- nchar(msg)
}

demo <- function() {
	easyReportProcess("abc123")
	Sys.sleep(1)
	easyReportProcess("this is much longer")
	Sys.sleep(1)
	easyReportProcess("this is short")
	Sys.sleep(1)
	easyReportProcess("almost done")
	Sys.sleep(1)
	easyReportProcess("")
	cat("DONE!", fill=TRUE)
}

demo()

imxReservedNames

Description

Vector of reserved names

Usage

imxReservedNames

Format

An object of class character of length 7.

imxReverseIdentifier

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxReverseIdentifier(model, name)

Arguments

imxRobustSE

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxRobustSE(model, details = FALSE, dependencyModels = character(0))

Arguments

Details

This function computes robust standard errors via a sandwich estimator. The "bread" of the sandwich is the numerically computed inverse Hessian of the likelihood function. This is what is typically used for standard errors throughout OpenMx. The "meat" of the sandwich is proportional to the covariance matrix of the numerically computed row derivatives of the likelihood function (i.e. row gradients).

When details=FALSE, only the standard errors are returned.

When details=TRUE, a list with five named elements is returned. Element SE is the vector of standard errors that is also returned when details=FALSE. Element cov is the full robust covariance matrix of the parameter estimates; the square root of the diagonal of cov gives the standard errors. Element bread is the aforementioned "bread"–the naive (non-robust) covariance matrix of the parameter estimates. Element meat is the aforementioned "meat," proportional to the covariance matrix of the row gradients. Element TIC is the model's Takeuchi Information Criterion, which is a generalization of AIC calculated from the "bread," the "meat," and the loglikelihood at the maximum-likelihood solution.

This function does not work correctly with multigroup models in which the groups themselves contain subgroups. This function also does not correctly handle multilevel data.

imxRowGradients

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxRowGradients(model, robustSE = FALSE, dependencyModels = character(0))

Arguments

Details

This function computes the gradient for each row of data. The returned object is a matrix with the same number of rows as the data, and the same number of columns as there are free parameters.

imxSameType

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxSameType(a, b)

Arguments

imxSeparatorChar

Description

The character between the model name and the named entity inside the model.

Usage

imxSeparatorChar

Format

An object of class character of length 1.

imxSfClient

Description

As of snowfall 1.84, the snowfall supervisor process stores an internal state information in a variable named ".sfOption" that is located in the "snowfall" namespace. The snowfall client processes store internal state information in a variable named ".sfOption" that is located in the global namespace.

Usage

imxSfClient()

Details

As long as the previous statement is true, then the current process is a snowfall client if-and-only-if exists(".sfOption").

imxSimpleRAMPredicate

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxSimpleRAMPredicate(model)

Arguments

Sparse symmetric matrix invert

Description

This API is visible to permit testing. Please do not use.

Usage

imxSparseInvert(mat)

Arguments

imxSquareMatrix

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxSquareMatrix(.Object)

Arguments

imxStanMathMajor

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxStanMathMajor()

imxSymmetricMatrix

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxSymmetricMatrix(.Object)

Arguments

imxTypeName

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxTypeName(model)

Arguments

imxUntitledName

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxUntitledName()

Details

Returns a character, the name of the next untitled entity

imxUntitledNumber

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxUntitledNumber()

Details

Increments the untitled number counter and returns its value

imxUntitledNumberReset

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxUntitledNumberReset()

Details

Resets the imxUntitledNumber counter

imxUpdateModelValues

Description

Deprecated. This function does not handle parameters with equality constraints. Do not use.

Usage

imxUpdateModelValues(model, flatModel, values)

Arguments

imxVariableTypes

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxVariableTypes

Format

An object of class character of length 2.

Details

The acceptable variable types

imxVerifyMatrix

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxVerifyMatrix(.Object)

Arguments

imxVerifyModel

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxVerifyModel(model)

Arguments

imxVerifyName

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxVerifyName(name, stackNumber)

Arguments

imxVerifyReference

Description

This is an internal function exported for those people who know what they are doing.

Usage

imxVerifyReference(reference, stackNumber)

Arguments

Calculate Chi Square for a WLS Model

Description

This is an internal function used to calculate the Chi Square distributed fit statistic for weighted least squares models.

Usage

imxWlsChiSquare(model, J=NA)

Arguments

Details

The Chi Square fit statistic for models fit with maximum likelihood depends on the difference in model fit in minus two log likelihood units between the saturated model and the more restricted model under investigation. For models fit with weighted least squares a different expression is required. If J is the first derivative (Jacobian) of the mapping from the free parameters to the unique elements of the expected covariance, means, and threholds, J_c is the orthogonal complement of J, W is the inverse of the full weight matrix, and e is the difference between the sample-estimated and model-implied covariance, means, and thresholds, then the Chi Square fit statistic is

\chi^2 = e' J_c (J'_c W J_c)^-1 J'_c e

with e' indicating the transpose of e. This Equation 2.20a from Browne (1984) where he showed that this statistic is chi-square distributed with the conventional degrees of freedom.

Mean and variance adjusted Chi Square statistics are also computed following Asparouhov and Muthen (2006).

Value

A named list with components

Chi

numeric value of the Chi Square fit statistic.

ChiDoF

degrees of freedom for the Chi Square fit statistic.

ChiM

numeric value of the mean adjusted Chi Square fit statistic

ChiMV

numeric value of the mean and variance adjusted Chi Square fit statistic

mAdjust

numeric value of the mean adjustment

mvAdjust

numeric value of the mean and variance adjustment

dstar

adjusted degrees of freedom for the mean and variance adjusted Chi Square fit statistic

References

M. W. Browne. (1984). Asymptotically Distribution-Free Methods for the Analysis of Covariance Structures. British Journal of Mathematical and Statistical Psychology, 37, 62-83.

T. Asparouhov and B. O. Muthen. (2006). Robust Chi Square Difference Testing with Mean and Variance Adjusted Test Statistics. Mplus Web Notes: No. 10.

Calculate Standard Errors for a WLS Model

Description

This is an internal function used to calculate standard errors for weighted least squares models.

Usage

imxWlsStandardErrors(model)

Arguments

Details

The standard errors for models fit with maximum likelihood are related to the second derivative (Hessian) of the likelihood function with respect to the free parameters. For models fit with weighted least squares a different expression is required. If J is the first derivative (Jacobian) of the mapping from the free parameters to the unique elements of the expected covariance, means, and thresholds, V is the weight matrix used, W is the inverse of the full weight matrix, and U= V J (J' V J)^{-1}, then the asymptotic covariance matrix of the free parameters is

Acov(\theta) = U' W U

with U' indicating the transpose of U.

Value

A named list with components

SE

The standard errors of the free parameters

Cov

The full covariance matrix of the free parameters. The square root of the diagonal elements of Cov equals SE.

Jac

The Jacobian computed to obtain the standard errors.

References

M. W. Browne. (1984). Asymptotically Distribution-Free Methods for the Analysis of Covariance Structures. British Journal of Mathematical and Statistical Psychology, 37, 62-83.

F. Yang-Wallentin, K. G. Jöreskog, & H. Luo. (2010). Confirmatory Factor Analysis of Ordinal Variables with Misspecified Models. Structural Equation Modeling, 17, 392-423.

Joint Ordinal and continuous variables to be modeled together

Description

Data set used in some of OpenMx's examples.

Usage

data("jointdata")

Format

A data frame with 250 observations on the following variables.

z1

Continuous variable

z2

Ordinal variable with 2 levels (0, 1)

z3

Continuous variable

z4

Ordinal variable with 4 levels (0, 1, 2, 3)

z5

Ordinal variable with 3 levels (0, 1, 3)

Details

Data generated to test the joint ML algorithm thoroughly.

Source

Simulated.

References

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

Examples

data(jointdata)
head(jointdata)

Example data for multiple regression among latent variables

Description

Data set used in some of OpenMx's examples.

Usage

data("latentMultipleRegExample1")

Format

A data frame with 200 observations on the following variables.

X1

Factor 1 indicator

X2

Factor 1 indicator

X3

Factor 1 indicator

X4

Factor 1 indicator

X5

Factor 2 indicator

X6

Factor 2 indicator

X7

Factor 2 indicator

X8

Factor 2 indicator

X9

Factor 3 indicator

X10

Factor 3 indicator

X11

Factor 3 indicator

X12

Factor 3 indicator

Details

Factor 1 strongly predicts factor 3. Factor 2 weakly predicts factor 3.

Source

Simulated.

References

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

Examples

data(latentMultipleRegExample1)
round(cor(latentMultipleRegExample1), 2)

Example data for multiple regression among latent variables

Description

Data set used in some of OpenMx's examples.

Usage

data("latentMultipleRegExample2")

Format

A data frame with 200 observations on the following variables.

X1

Factor 1 indicator

X2

Factor 1 indicator

X3

Factor 1 indicator

X4

Factor 1 indicator

X5

Factor 2 indicator

X6

Factor 2 indicator

X7

Factor 2 indicator

X8

Factor 2 indicator

X9

Factor 3 indicator

X10

Factor 3 indicator

X11

Factor 3 indicator

X12

Factor 3 indicator

Details

Factor 1 strongly predicts factor 3. Factor 2 weakly predicts factor 3. Very similar to latentMultipleRegExample1.

Source

Simulated.

References

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

Examples

data(latentMultipleRegExample2)
round(cor(latentMultipleRegExample2), 2)

Respondent-soldiers on four dichotomous items

Description

Data set used in some of OpenMx's examples.

Usage

data("lazarsfeld")

Format

A data frame with 1000 observations on four dichotomous items.

armyrun

In general how do you feel the Army is run?

favatt

Do you think when you are discharged you will [have] a favorable attitude toward the Army?

squaredeal

In general do you feel you yourself have gotten a square deal from the Army?

welfare

Do you feel that the Army is trying its best to look out for the welfare of enlisted men?

frequency

Frequency of response pattern.

Details

A straightforward descriptive analysis of these data shows that negative responses are more numerous except on item 1; and that there is a positive association between each pair of items. A soldier who responds positively to any one item is more likely to respond positively to a second item. Lazarsfeld's analysis is based on the assumption that each soldier can be thought of as belong to one of two latent classes. The probability of positive response to an item is different in one group than in the other. Most importantly, he is willing to assume that for an individual respondent the responses to items are statistically independent.

Source

Lazarsfeld, Paul F. (1950b) "Some Latent Structures", Chapter 11 in Stouffer (1950).

References

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

See Also

http://www.people.vcu.edu/~nhenry/LSA50.htm

Examples

data(lazarsfeld)

Matrix logarithm

Description

Matrix logarithm

Usage

logm(x, tol = .Machine$double.eps)

Arguments

Data for multiple regression

Description

Data set used in some of OpenMx's examples.

Usage

data("multiData1")

Format

A data frame with 500 observations on the following variables.

x1

x2

x3

x4

y

Details

x1-x4 are predictor variables, and y is the outcome.

Source

Simulated.

References

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

Examples

data(multiData1)
summary(lm(y ~ ., data=multiData1))
#results can be replicated in OpenMx.

Create MxAlgebra Object

Description

This function creates a new MxAlgebra. The common use is to compute a value in a model: for instance a standardized value of a parameter, or a parameter which is a function of other values. It is also used in models with an mxFitFunctionAlgebra objective function.

note: Unless needed in the model objective, algebras are only computed twice: once at the beginning and once at the end of running a model, so adding them doesn't often add a lot of overhead.

Usage

mxAlgebra(expression, name = NA, dimnames = NA, ..., fixed = FALSE,
          joinKey=as.character(NA), joinModel=as.character(NA),
	verbose=0L, initial=matrix(as.numeric(NA),1,1),
        recompute=c('always','onDemand'))

Arguments

Details

The mxAlgebra function is used to create algebraic expressions that operate on one or more MxMatrix objects. To evaluate an MxAlgebra object, it must be placed in an MxModel object, along with all referenced MxMatrix objects and the mxFitFunctionAlgebra function. The mxFitFunctionAlgebra function must reference by name the MxAlgebra object to be evaluated.

Note: f the result for an MxAlgebra depends upon one or more "definition variables" (see mxMatrix()), then the value returned after the call to mxRun() will be computed using the values of those definition variables in the first (i.e., first before any automated sorting is done) row of the raw dataset.

The following operators and functions are supported in mxAlgebra:

Operators

solve()

Inversion

t()

Transposition

^

Elementwise powering

%^%

Kronecker powering

+

Addition

-

Subtraction

%*%

Matrix Multiplication

*

Elementwise product

/

Elementwise division

%x%

Kronecker product

%&%

Quadratic product: pre- and post-multiply B by A and its transpose t(A), i.e: A %&% B == A %*% B %*% t(A)

Functions

cov2cor

Convert covariance matrix to correlation matrix

chol

Cholesky Decomposition

cbind

Horizontal adhesion

rbind

Vertical adhesion

colSums

Matrix column sums as a column vector

rowSums

Matrix row sums as a column vector

det

Determinant

tr

Trace

sum

Sum

mean

Arithmetic mean

prod

Product

max

Maximum

min

Min

abs

Absolute value

sin

Sine

sinh

Hyperbolic sine

asin

Arcsine

asinh

Inverse hyperbolic sine

cos

Cosine

cosh

Hyperbolic cosine

acos

Arccosine

acosh

Inverse hyperbolic cosine

tan

Tangent

tanh

Hyperbolic tangent

atan

Arctangent

atanh

Inverse hyperbolic tangent

exp

Exponent

log

Natural Logarithm

mxRobustLog

Robust natural logarithm

sqrt

Square root

p2z

Standard-normal quantile

logp2z

Standard-normal quantile from log probabilities

lgamma

Log-gamma function

lgamma1p

Compute log(gamma(x+1)) accurately for small x

eigenval

Eigenvalues of a square matrix. Usage: eigenval(x); eigenvec(x); ieigenval(x); ieigenvec(x)

rvectorize

Vectorize by row

cvectorize

Vectorize by column

vech

Half-vectorization

vechs

Strict half-vectorization

vech2full

Inverse half-vectorization

vechs2full

Inverse strict half-vectorization

vec2diag

Create matrix from a diagonal vector (similar to diag)

diag2vec

Extract diagonal from matrix (similar to diag)

expm

Matrix Exponential

logm

Matrix Logarithm

omxExponential

Matrix Exponential

omxMnor

Multivariate Normal Integration

omxAllInt

All cells Multivariate Normal Integration

omxNot

Perform unary negation on a matrix

omxAnd

Perform binary and on two matrices

omxOr

Perform binary or on two matrices

omxGreaterThan

Perform binary greater on two matrices

omxLessThan

Perform binary less than on two matrices

omxApproxEquals

Perform binary equals to (within a specified epsilon) on two matrices

omxSelectRows

Filter rows from a matrix

omxSelectCols

Filter columns from a matrix

omxSelectRowsAndCols

Filter rows and columns from a matrix

mxEvaluateOnGrid

Evaluate an algebra on an abscissa grid and collect column results

mpinv

Moore-Penrose Inverse

If solve is used on an uninvertible square matrix in R, via mxEval(), it will fail with an error will; if solve is used on an uninvertible square matrix during runtime, it will fail silently.

mxRobustLog is the same as log except that it returns -745 instead of -Inf for an argument of 0. The value -745 is less than log(4.94066e-324), a good approximation of negative infinity because the log of any number represented as a double will be of smaller absolute magnitude.

There are also several multi-argument functions usable in MxAlgebras, which apply themselves elementwise to the matrix provided as their first argument. These functions have slightly different usage from their R counterparts. Their result is always a matrix with the same dimensions as that provided for their first argument. Values must be provided for ALL arguments of these functions, in order. Provide zeroes as logical values of FALSE, and non-zero numerical values as logical values of TRUE. For most of these functions, OpenMx cycles over values of arguments other than the first, by column (i.e., in column-major order), to the length of the first argument. Notable exceptions are the log, log.p, and lower.tail arguments to probability-distribution-related functions, for which only the [1,1] element is used. It is recommended that all arguments after the first be either (1) scalars, or (2) matrices with the same dimensions as the first argument.

Value

Returns a new MxAlgebra object.

References

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

See Also

MxAlgebra for the S4 class created by mxAlgebra. mxFitFunctionAlgebra for an objective function which takes an MxAlgebra or MxMatrix object as the function to be minimized. MxMatrix and mxMatrix for objects which may be entered in the expression argument and the function that creates them. More information about the OpenMx package may be found here.

Examples

A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")

# Simple example: algebra B simply evaluates to the matrix A
B <- mxAlgebra(A, name = "B")

# Compute A + B
C <- mxAlgebra(A + B, name = "C")

# Compute sin(C)
D <- mxAlgebra(sin(C), name = "D")

# Make a model and evaluate the mxAlgebra object 'D'
A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")
model <- mxModel(model="AlgebraExample", A, B, C, D )
fit   <- mxRun(model)
mxEval(D, fit)


# Numbers in mxAlgebras are upgraded to 1x1 matrices
# Example of Kronecker powering (%^%) and multiplication (%*%)
A  <- mxMatrix(type="Full", nrow=3, ncol=3, value=c(1:9), name="A")
m1 <- mxModel(model="kron", A, mxAlgebra(A %^% 2, name="KroneckerPower"))
mxRun(m1)$KroneckerPower

# Running kron
# mxAlgebra 'KroneckerPower'
# $formula:  A %^% 2
# $result:
#      [,1] [,2] [,3]
# [1,]    1   16   49
# [2,]    4   25   64
# [3,]    9   36   81

Create MxAlgebra object from a string

Description

Create MxAlgebra object from a string

Usage

mxAlgebraFromString(algString, name = NA, dimnames = NA, ...)

Arguments

See Also

mxAlgebra

Examples

A <- mxMatrix(values = runif(25), nrow = 5, ncol = 5, name = 'A')
B <- mxMatrix(values = runif(25), nrow = 5, ncol = 5, name = 'B')
model <- mxModel(A, B, name = 'model',
  mxAlgebraFromString("A * (B + A)", name = 'test'))
model <- mxRun(model)
model[['test']]$result
A$values * (B$values + A$values)

DEPRECATED: Create MxAlgebraObjective Object

Description

WARNING: Objective functions have been deprecated as of OpenMx 2.0.

Please use MxFitFunctionAlgebra() instead. As a temporary workaround, MxAlgebraObjective returns a list containing a NULL MxExpectation object and an MxFitFunctionAlgebra object.

All occurrences of

mxAlgebraObjective(algebra, numObs = NA, numStats = NA)

Should be changed to

mxFitFunctionAlgebra(algebra, numObs = NA, numStats = NA)

Arguments

Details

NOTE: THIS DESCRIPTION IS DEPRECATED. Please change to using mxFitFunctionAlgebra as shown in the example below.

Fit functions are functions for which free parameter values are chosen such that the value of the objective function is minimized. While the other fit functions in OpenMx require an expectation function for the model, the mxAlgebraObjective function uses the referenced MxAlgebra or MxMatrix object as the function to be minimized.

If a model's primary objective function is a mxAlgebraObjective objective function, then the referenced algebra in the objective function must return a 1 x 1 matrix (when using OpenMx's default optimizer). There is no restriction on the dimensions of an objective function that is not the primary, or ‘topmost’, objective function.

To evaluate an algebra objective function, place the following objects in a MxModel object: a MxAlgebraObjective, MxAlgebra and MxMatrix entities referenced by the MxAlgebraObjective, and optional MxBounds and MxConstraint entities. This model may then be evaluated using the mxRun function. The results of the optimization may be obtained using the mxEval function on the name of the MxAlgebra, after the model has been run.

Value

Returns a list containing a NULL MxExpectation object and an MxFitFunctionAlgebra object. MxFitFunctionAlgebra objects should be included with models with referenced MxAlgebra and MxMatrix objects.

References

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

See Also

mxAlgebra to create an algebra suitable as a reference function to be minimized. More information about the OpenMx package may be found here.

Examples

# Create and fit a very simple model that adds two numbers using mxFitFunctionAlgebra

library(OpenMx)

# Create a matrix 'A' with no free parameters
A <- mxMatrix('Full', nrow = 1, ncol = 1, values = 1, name = 'A')

# Create an algebra 'B', which defines the expression A + A
B <- mxAlgebra(A + A, name = 'B')

# Define the objective function for algebra 'B'
objective <- mxFitFunctionAlgebra('B')

# Place the algebra, its associated matrix and 
# its objective function in a model
tmpModel <- mxModel(model="Addition", A, B, objective)

# Evalulate the algebra
tmpModelOut <- mxRun(tmpModel)

# View the results
tmpModelOut$output$minimum

Automatically set starting values for an MxModel

Description

Automatically set starting values for an MxModel

Usage

mxAutoStart(model, type = c("ULS", "DWLS"))

Arguments

Details

This function automatically picks very good starting values for many models (RAM, LISREL, Normal), including multiple group versions of these. It works for models with algebras. Models of continuous, ordinal, and joint ordinal-continuous variables are also acceptable. It works for models with covariance or raw data. However, it does not currently work for models with definition variables, state space models, item factor analysis models, or multilevel models.

The method used to obtain new starting values is quite simple. The user's model is changed to an unweighted least squares (ULS) model. The ULS model is estimated and its final point estimates are returned as the new starting values. Optionally, diagonally weighted least squares (DWLS) can be used instead with the type argument.

Please note that ULS is sensitive to the scales of your variables. For example, if you have variables with means of 20 and variances of 0.001, then ULS will "weight" the means 20,000 times more than the variances and might result in zero variance estimates. Likewise if one variable has a variance of 20 and another has a variance of 0.001, the same problem may arise. To avoid this, make sure your variables are scaled accordingly. You could also use type='DWLS' to have the function use diagonally weighted least squares to obtain starting values. Of course, using diagonally weighted least squares will take much much longer and will usually not provide better starting values than unweighted least squares.

Also note that if model contains a GREML expectation, argument type is ignored, and the function always uses a form of ULS.

Value

an MxModel with new free parameter values

Examples

# Use the frontpage model with negative variances to show better
# starting values
library(OpenMx)
data(demoOneFactor)

latents  = c("G") # the latent factor
manifests = names(demoOneFactor) # manifest variables to be modeled

m1 <- mxModel("One Factor", type = "RAM",
	manifestVars = manifests, latentVars = latents,
	mxPath(from = latents, to = manifests),
	mxPath(from = manifests, arrows = 2, values=-.2),
	mxPath(from = latents, arrows = 2, free = FALSE, values = 1.0),
	mxPath(from = "one", to = manifests),
	mxData(demoOneFactor, type = "raw")
)

# Starting values imply negative variances!
mxGetExpected(m1, 'covariance')

# Use mxAutoStart to get much better starting values
m1s <- mxAutoStart(m1)
mxGetExpected(m1s, 'covariance')

mxAvailableOptimizers

Description

List the Optimizers available in this version, e.g. "SLSQP" "CSOLNP"

Usage

mxAvailableOptimizers()

Details

note for advanced users: Special-purpose optimizers like Newton-Raphson or EM are not included in this list.

Value

- list of valid Optimizer names

See Also

- mxOption(model, "Default optimizer")

Examples

mxAvailableOptimizers()

Repeatedly estimate model using resampling with replacement

Description

Bootstrapping is used to quantify the variability of parameter estimates. A new sample is drawn from the model data (uniformly sampling the original data with replacement). The model is re-fitted to this new sample. This process is repeated many times. This yields a series of estimates from these replications which can be used to assess the variability of the parameters.

note: mxBootstrap only bootstraps free model parameters:

To bootstrap algebras, see mxBootstrapEval

To report bootstrapped standardized paths in RAM models, mxBootstrap the model, and then run through mxBootstrapStdizeRAMpaths

Usage

mxBootstrap(model, replications=200, ...,
                        data=NULL, plan=NULL, verbose=0L,
                        parallel=TRUE, only=as.integer(NA),
			OK=mxOption(model, "Status OK"), checkHess=FALSE, unsafe=FALSE)

Arguments

Details

By default, all datasets in the given model are resampled independently. If resampling is desired from only some of the datasets then the models containing them can be listed in the ‘data’ parameter.

The frequency column in the mxData object is used represent a resampled dataset. When resampling, the original row proportions, as given by the original frequency column, are respected.

When the model has a default compute plan and ‘checkHess’ is kept at FALSE then the Hessian will not be approximated or checked. On the other hand, ‘checkHess’ is TRUE then the Hessian will be approximated by finite differences. This procedure is of some value because it can be informative to check whether the Hessian is positive definite (see mxComputeHessianQuality). However, approximating the Hessian is often costly in terms of CPU time. For bootstrapping, the parameter estimates derived from the resampled data are typically of primary interest.

On occasion, replications will fail. Sometimes it can be helpful to exactly reproduce a failed replication to attempt to pinpoint the cause of failure. The ‘only’ option facilitates this kind of investigation. In normal operation, mxBootstrap uses the regular R random number generator to generate a seed for each replication. This seed is used to seed an internal pseudorandom number generator (currently the Mersenne Twister algorithm). These per-replication seeds are stored as part of the bootstrap output. When ‘only’ is specified, the associated stored seed is used to seed the internal random number generator so that identical weights can be regenerated.

mxBootstrap does not currently offer special support for nested, multilevel, or other dependent data structures. mxBootstrap assumes rows of data are independent. Multilevel models and state space models violate the independence assumption employed by mxBootstrap. By default the unsafe argument prevents multilevel and state space models from using mxBootstrap; however, setting unsafe=TRUE allows multilevel and state space models to use bootstrapping under the – perhaps foolish – assumption that the user is sufficiently knowledgeable to interpret the results.

Value

The given model is returned with the compute plan modified to consist of mxComputeBootstrap. Results of the bootstrap replications are stored inside the compute plan. mxSummary can be used to obtain per-parameter quantiles and standard errors.

See Also

mxBootstrapEval, mxComputeBootstrap, mxSummary, mxBootstrapStdizeRAMpaths, as.statusCode

Examples

library(OpenMx)

data(multiData1)

manifests <- c("x1", "x2", "y")

biRegModelRaw <- mxModel(
  "Regression of y on x1 and x2",
  type="RAM",
  manifestVars=manifests,
  mxPath(from=c("x1","x2"), to="y", 
         arrows=1, 
         free=TRUE, values=.2, labels=c("b1", "b2")),
  mxPath(from=manifests, 
         arrows=2, 
         free=TRUE, values=.8, 
         labels=c("VarX1", "VarX2", "VarE")),
  mxPath(from="x1", to="x2",
         arrows=2, 
         free=TRUE, values=.2, 
         labels=c("CovX1X2")),
  mxPath(from="one", to=manifests, 
         arrows=1, free=TRUE, values=.1, 
         labels=c("MeanX1", "MeanX2", "MeanY")),
  mxData(observed=multiData1, type="raw"))

biRegModelRawOut <- mxRun(biRegModelRaw)

boot <- mxBootstrap(biRegModelRawOut, 10)   # start with 10
summary(boot)

# Looks good, now do the rest
boot <- mxBootstrap(boot)
summary(boot)

# examine replication 3
boot3 <- mxBootstrap(boot, only=3)

print(coef(boot3))
print(boot$compute$output$raw[3,names(coef(boot3))])

Evaluate Values in a bootstrapped MxModel

Description

This function can be used to evaluate an arbitrary R expression that includes named entities from a MxModel object, or labels from a MxMatrix object.

Usage

mxBootstrapEval(expression, model, defvar.row = 1, ...,
 bq=c(.25,.75), method=c('bcbci','quantile'))

mxBootstrapEvalByName(name, model, defvar.row = 1, ...,
 bq=c(.25,.75), method=c('bcbci','quantile'))

omxBootstrapEval(expression, model, defvar.row = 1L, ...)

omxBootstrapEvalCov(expression, model, defvar.row = 1L, ...)

omxBootstrapEvalByName(name, model, defvar.row=1L, ...)

Arguments

Details

The argument ‘expression’ is an arbitrary R expression. Any named entities that are used within the R expression are translated into their current value from the model. Any labels from the matrices within the model are translated into their current value from the model. Finally the expression is evaluated and the result is returned. To enable debugging, the ‘show’ argument has been provided. The most common mistake when using this function is to include named entities in the model that are identical to R function names. For example, if a model contains a named entity named ‘c’, then the following mxEval call will return an error: mxEval(c(A, B, C), model).

The mxEvalByName function is a wrapper around mxEval that takes a character instead of an R expression.

nb: ‘bcbci’ stands for ‘bias-corrected bootstrap confidence interval’

The default behavior is to use the ‘bcbci’ method, due to its superior theoretical properties.

Value

omxBootstrapEval and omxBootstrapEvalByName return the raw matrix of cvectorize'd results. omxBootstrapEvalCov returns the covariance matrix of the cvectorize'd results. mxBootstrapEval and mxBootstrapEvalByName return the cvectorize'd results summarized by method at quantiles bq.

References

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

See Also

mxAlgebra to create algebraic expressions inside your model and mxModel for the model object mxEval looks inside when evaluating. mxBootstrap to create bootstrap data.

Examples

library(OpenMx)
# make a unit-weighted 10-row data set of values 1 thru 10
myData = mxData(data.frame(weight=1.0, value=1:10), "raw", weight = "weight")
sum(1:10)

# Model sums data$value (sum(1:10)= 55), subtracts "A", squares the result, 
# and tries to minimize this (achieved by setting A=55)
testModel = mxModel(model = "testModel1", myData,
	mxMatrix(name  = "A", "Full", nrow = 1, ncol = 1, values = 1, free=TRUE),
	# nb: filteredDataRow is an auto-generated matrix of
	# non-missing data from the present row.
	# This is placed into the "rowResults" matrix (also auto-generated)
	mxAlgebra(name = "rowAlg", data.weight * filteredDataRow),
	# Algebra to turn the rowResults into a single number
	mxAlgebra(name = "reduceAlg", (sum(rowResults) - A)^2),
	mxFitFunctionRow(
		rowAlgebra    = "rowAlg",
		reduceAlgebra = "reduceAlg",
		dimnames      = "value"
	)
	# no need for an MxExpectation object when using mxFitFunctionRow
)

testModel = mxRun(testModel) # A is estimated at 55, with SE= 1
testBoot = mxBootstrap(testModel)
summary(testBoot) # A is estimated at 55, with SE= 0

# Let's compute A^2 (55^2 = 3025)
mxBootstrapEval(A^2, testBoot)
#      SE 25.0% 75.0%
# [1,]  0  3025  3025

Bootstrap distribution of standardized RAM path coefficients

Description

Uses the distribution of a bootstrapped RAM model's raw parameters to create a bootstrapped estimate of its standardized path coefficients.

note: Model must have already been run through mxBootstrap.

Usage

mxBootstrapStdizeRAMpaths(model, bq= c(.25, .75), 
	method= c('bcbci','quantile'), returnRaw= FALSE)

Arguments

Details

mxBootstrapStdizeRAMpaths applies mxStandardizeRAMpaths to each bootstrap replication, thus creating a distribution of standardized estimates for each nonzero path coefficient.

The default bq (bootstrap quantiles) of c(.25, .75) correspond to a 50% CI. This default is chosen as many more bootstraps are required to accurately estimate more extreme quantiles. For a 95% CI, use bq=c(.025,.0975).

nb: ‘bcbci’ stands for ‘bias-corrected bootstrap confidence interval’ To learn more about bcbci and quantile methods, see Efron (1982) and Efron and Tibshirani (1994).

note 1: It is possible (though unlikely) that the number of nonzero paths (elements of the A and S RAM matrices) may vary among bootstrap replications. This precludes a simple summary of the standardized paths' bootstrapping results. In this rare case, if returnRaw=TRUE, a raw list of bootstrapping results is returned, with a warning. Otherwise an error is thrown.

note 2: mxBootstrapStdizeRAMpaths ignores sub-models. To standardize bootstrapped sub-models, run it on the sub-models directly.

Value

If returnRaw=FALSE (default), it returns a dataframe containing, among other things, the standardized path coefficients as estimated from the real data, their bootstrap SEs, and the lower and upper limits of a bootstrap confidence interval. If returnRaw=TRUE, typically, a matrix containing the raw bootstrap results is returned; this matrix has one column per non-zero path coefficient, and one row for each successfully converged bootstrap replication or, if the number of paths varies between bootstraps, a raw list of results is returned.

References

Efron B. (1982). The Jackknife, the Bootstrap, and Other Resampling Plans. Philadelphia: Society for Industrial and Applied Mathematics.

Efron B, Tibshirani RJ. (1994). An Introduction to the Bootstrap. Boca Raton: Chapman & Hall/CRC.

See Also

mxBootstrap(), mxStandardizeRAMpaths(), mxBootstrapEval, mxSummary

Examples

require(OpenMx)
data(myFADataRaw)
manifests = c("x1","x2","x3","x4","x5","x6")

# Build and run 1-factor raw-data CFA
m1 = mxModel("CFA", type="RAM", manifestVars=manifests, latentVars="F1",
	# Factor loadings
	mxPath("F1", to = manifests, values=1),

	# Means and variances of F1 and manifests
	mxPath(from="F1", arrows=2, free=FALSE, values=1), # fix var  F1 @1
	mxPath("one", to= "F1", free= FALSE, values = 0),  # fix mean F1 @0

	# Freely-estimate means and residual variances of manifests
	mxPath(from = manifests, arrows=2, free=TRUE, values=1),
	mxPath("one", to= manifests, values = 1),

	mxData(myFADataRaw, type="raw")
)
m1 = mxRun(m1)
set.seed(170505) # Desirable for reproducibility

# ==========================
# = 1. Bootstrap the model =
# ==========================

m1_booted = mxBootstrap(m1)

# =================================================
# = 2. Estimate and accumulate a distribution of  =
# =    standardized values from each bootstrap.   =
# =================================================

tmp = mxBootstrapStdizeRAMpaths(m1_booted)
#          name label matrix row col Std.Value    Boot.SE     25.0%     75.0%
# 1  CFA.A[1,7]    NA      A  x1  F1 0.8049842 0.01583737 0.7899938 0.8124311
# 2  CFA.A[2,7]    NA      A  x2  F1 0.7935255 0.01373320 0.7865666 0.8045558
# 3  CFA.A[3,7]    NA      A  x3  F1 0.7772050 0.01629684 0.7698374 0.7907878
# 4  CFA.A[4,7]    NA      A  x4  F1 0.8248493 0.01315534 0.8150299 0.8351416
# 5  CFA.A[5,7]    NA      A  x5  F1 0.7995083 0.01479210 0.7869158 0.8057788
# 6  CFA.A[6,7]    NA      A  x6  F1 0.8126734 0.01527586 0.8012809 0.8218805
# 7  CFA.S[1,1]    NA      S  x1  x1 0.3520004 0.02546392 0.3399556 0.3759097
# 8  CFA.S[2,2]    NA      S  x2  x2 0.3703173 0.02171159 0.3526899 0.3813130
# 9  CFA.S[3,3]    NA      S  x3  x3 0.3959524 0.02529583 0.3746547 0.4073505
# 10 CFA.S[4,4]    NA      S  x4  x4 0.3196237 0.02163979 0.3025384 0.3357263
# 11 CFA.S[5,5]    NA      S  x5  x5 0.3607865 0.02364008 0.3507206 0.3807635
# 12 CFA.S[6,6]    NA      S  x6  x6 0.3395619 0.02476480 0.3245124 0.3579489
# 13 CFA.S[7,7]    NA      S  F1  F1 1.0000000 0.00000000 1.0000000 1.0000000
# 14 CFA.M[1,1]    NA      M   1  x1 2.9950397 0.08745209 2.9368758 3.0430917
# 15 CFA.M[1,2]    NA      M   1  x2 2.9775235 0.07719970 2.9109289 3.0197492
# 16 CFA.M[1,3]    NA      M   1  x3 3.0133665 0.08645522 2.9598062 3.0779683
# 17 CFA.M[1,4]    NA      M   1  x4 3.0505604 0.08210810 2.9952130 3.1103674
# 18 CFA.M[1,5]    NA      M   1  x5 2.9776983 0.07973619 2.9362410 3.0311999
# 19 CFA.M[1,6]    NA      M   1  x6 2.9830050 0.07632118 2.9360469 3.0416504

Create MxBounds Object

Description

This function creates a new MxBounds object.

Usage

mxBounds(parameters, min = NA, max = NA)

Arguments

Details

Creates a set of boundaries or limits for a parameter or set of parameters. Parameters may be any free parameter or parameters from an MxMatrix object. Parameters may be referenced either by name or by referring to their position in the 'spec' matrix of an MxMatrix object.

Minima and maxima may be specified as scalar numeric values.

Value

Returns a new MxBounds object. If used as an argument in an MxModel object, the parameters referenced in the 'parameters' argument must also be included prior to optimization.

References

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

See Also

MxBounds for the S4 class created by mxBounds. MxMatrix and mxMatrix for free parameter specification. More information about the OpenMx package may be found here.

Examples

#Create lower and upper bounds for parameters 'A' and 'B'
bounds <- mxBounds(c('A', 'B'), 3, 5)

#Create a lower bound of zero for a set of variance parameters
varianceBounds <- mxBounds(c('Var1', 'Var2', 'Var3'), 0)

Create mxCI Object

Description

This function creates a new MxCI object, which allows estimation of likelihood-based confidence intervals in a model (note: to estimate SEs around arbitrary objects, see mxSE)

Usage

mxCI(reference, interval = 0.95, type=c("both", "lower", "upper"), ..., boundAdj=TRUE)

Arguments

Details

The mxCI function creates MxCI objects, which can be used as arguments in MxModel objects. When models containing MxCI objects are optimized using mxRun with the ‘intervals’ argument set to TRUE, likelihood-based confidence intervals are returned. The likelihood-based confidence intervals calculated by MxCI objects are symmetric with respect to the change in likelihood in either direction, and are not necessarily symmetric around the parameter estimate. Estimation of confidence intervals requires both that an MxCI object be included in the model and that the ‘intervals’ argument of the mxRun function is set to TRUE. When estimated, confidence intervals can be accessed in the model output at $output$confidenceIntervals or by using summary on a fitted MxModel object.

In all cases, a two-sided hypothesis test is assumed. Therefore, the upper bound will exclude 2.5% (for interval=0.95) even though only one bound is requested. To obtain a one-sided CI for a one-sided hypothesis test, interval=0.90 will obtain a 95% confidence interval.

When a confidence interval is requested for a free parameter (not an algebra) constrained by a lower bound or an upper bound (but not both) and boundAdj=TRUE then the Wu & Neale (2012) correction is used. This improves the accuracy of the confidence interval when the parameter is estimated close to the bound. For example, this correction will be activated when a variance with a lower bound of 10^{-6} and no upper bound that is estimated close to the bound. The sample size, or more precisely effective sample size for that particular parameter, will determine how close the variance needs to be to the bound at 10^{-6} to activate the correction.

The likelihood-based confidence intervals returned using MxCI are obtained by increasing or decreasing the value of each parameter until the -2 log likelihood of the model increases by an amount corresponding to the requested interval. The confidence limit specified by the ‘interval’ argument is transformed into a corresponding difference in the model -2 log likelihood based on the likelihood ratio test. Thus, a requested confidence interval for a parameter will first determine the corresponding quantile from the chi-squared distribution with one degree of freedom (a value of 3.841459 when a 95 percent confidence interval is requested). That quantile will be populated into either the ‘lowerdelta’ slot, the ‘upperdelta’ slot, or both in the output MxCI object.

Estimation of likelihood-based confidence intervals begins after optimization has been completed, with each parameter moved in the direction(s) specified in the ‘type’ argument until the specified increase in -2 log likelihood is reached. All other free parameters are left free for this stage of optimization. This process repeats until all confidence intervals have been calculated. The calculation of likelihood-based confidence intervals can be computationally intensive, and may add a significant amount of time to model estimation when many confidence intervals are requested.

Multiple parameters, MxMatrices and MxAlgebras may be listed in the ‘reference’ argument. Individual elements of MxMatrices and MxAlgebras may be listed as well, using the syntax “matrix[row,col]” (see Extract for more information). Only scalar numeric values for the ‘interval’ argument are supported. Users requesting different confidence ranges for different parameters must use separate mxCI statements. MxModel objects can hold multiple MxCI objects, but only one confidence interval may be requested per named-entity.

Confidence interval estimation may result in model non-convergence at the confidence limit. Separate optimizer messages may be passed for each confidence limit. This has no impact on the parameter estimates themselves, but may indicate a problem with the referenced confidence limit. Model non-convergence for a particular confidence limit may indicate parameter interdependence or the influence of a parameter boundary.

These error messages and their meanings are listed in the help for mxSummary

The validity of a confidence limit can be checked by running a model with the appropriate parameter fixed at the confidence limit in question. If the confidence limit is valid, the -2 log likelihoods of these two models should differ by the specified chi-squared criterion (as set using the ‘lowerdelta’ or ‘upperdelta’ slots in the MxCI object (you can choose which of these to set via the type parameter of mxCI).

Value

Returns a new MxCI object. If used as an argument in an MxModel object, the parameters, MxMatrices and MxAlgebras listed in the 'reference' argument must also be included prior to optimization.

References

The OpenMx User's guide can be found at https://openmx.ssri.psu.edu/documentation/. Additional support for mxCI() can be found on the OpenMx wiki at http://openmx.ssri.psu.edu/wiki.

Neale, M. C. & Miller M. B. (1997). The use of likelihood based confidence intervals in genetic models. Behavior Genetics, 27(2), 113-120.

Pek, J. & Wu, H. (2015). Profile likelihood-based confidence intervals and regions for structural equation models. Psychometrika, 80(4), 1123-1145.

Wu, H. & Neale, M. C. (2012). Adjusted confidence intervals for a bounded parameter. Behavior genetics, 42(6), 886-898.

See Also

mxSE for computing SEs around arbitrary objects. mxComputeConfidenceInterval is the internal compute plan that implements the algorithm. MxMatrix and mxMatrix for free parameter specification. MxCI for the S4 class created by mxCI. More information about the OpenMx package may be found here.

Examples

library(OpenMx)

# generate data
covariance <- matrix(c(1.0, 0.5, 0.5, 1.0), 
    nrow=2, 
    dimnames=list(c("a", "b"), c("a", "b")))
    
data <- mxData(covariance, "cov", numObs=100)

# create an expected covariance matrix
expect <- mxMatrix("Symm", 2, 2,
    free=TRUE,
    values=c(1, .5, 1),
    labels=c("var1", "cov12", "var2"),
    name="expectedCov")

# request 95 percent confidence intervals   
ci <- mxCI(c("var1", "cov12", "var2"))

# specify the model
model <- mxModel(model="Confidence Interval Example",
    data, expect, ci,
    mxExpectationNormal("expectedCov", dimnames=c("a", "b")),
    mxFitFunctionML())

# run the model 
results <- mxRun(model, intervals=TRUE)

# view confidence intervals
print(summary(results)$CI)

# view all results
summary(results)

# remove a specific mxCI from a model
model <- mxModel(model, remove=TRUE, model$intervals[['cov12']])
model$intervals

# remove all mxCI from a model
model <- mxModel(model, remove=TRUE, model$intervals)
model$intervals

Check that a model is locally identified

Description

Use the dimension of the null space of the Jacobian to determine whether or not a model is identified local to its current parameter values. The output is a list of the the identification status, the Jacobian, and which parameters are not identified.

Usage

mxCheckIdentification(model, details=TRUE, nrows=2, exhaustive=FALSE, silent=FALSE)

Arguments

Details

The mxCheckIdentification function is used to check that a model is identified. That is, the function will tell you if the model has a unique solution in parameter space. The function is most useful when applied to either (a) a model that has been run and had some NA standard errors, or (b) a model that has not been run but has reasonable starting values. In the former situation, mxCheckIdentification is used as a diagnostic after a problem was indicated. In the latter situation, mxCheckIdentification is used as a sanity check.

The method uses the Jacobian of the model expected means and the unique elements of the expected covariance matrix with respect to the free parameters. It is the first derivative of the mapping between the free parameters and the sufficient statistics for the Normal distribution. The method does not depend on data, but does depend on the current values of the free parameters. Thus, it only provides local identification, not global identification. You might get different answers about model identification depending on the free parameter values. Because the method does not depend on data, the model still could be empirically unidentified due to missing data.

The Jacobian is evaluated numerically and generally takes a few seconds, but much less than a minute.

Model identification should be accurate for models with linear or nonlinear equality and inequality constraints. When there are constraints, mxCheckIdentification uses the Jacobian of the summary statistics with respect to the free parameters and the Jacobian of the summary statistics with respect to the constraints. The combined extended Jacobian must have rank equal to the number of free parameters for the model to be identified. So, a model can be identified with constraints that is not identified without constraints.

Model identification should also be accurate for multiple group models and models with definition variables. In the case of multiple groups, the Jacobian is computed for each group and they are concatenated: summary statistics for each group go down the rows of the Jacobian; the single set of free parameters go across the columns of the Jacobian. In the case of definition variables, a new set of summary statistics is computed for each unique set of definition variable values; thus creating a kind of pseudo-multiple group model for each set of unique definition variable values.

For models using definition variables, the additional arguments 'nrows' and 'exhaustive' provide instruction for how to search for identification. In principle, full model identification for models with definition variables requires evaluating the Jacobian of the mapping between the free parameters and the summary statistics for every unique combination of definition variable values. This evaluation can take a long time. However, in practice, the vast majority of models are identified after evaluating one or two definition variable rows. The current defaults attempt to capitalize on this practical situation. By default 'mxCheckIdentification' will evaluate up to 2 unique definition variable rows, but will stop once the model is identified. To keep evaluating unique definition variable values until the model is identified or you run out of rows, set nrows=Inf. To evaluate all unique definition variable values, set nrows=Inf and exhaustive=TRUE.

When TRUE, the 'details' argument provides the names of the non-identified parameters. Otherwise, only the status and Jacobian are returned.

Value

A named list with components

status

logical. TRUE if the model is locally identified; otherwise FALSE.

jacobian

matrix. The numerically evaluated Jacobian.

non_identified_parameters

vector. The free parameter names that are not identified

References

Bekker, P.A., Merckens, A., Wansbeek, T.J. (1994). Identification, Equivalent Models and Computer Algebra. Academic Press: Orlando, FL.

Bollen, K. A. & Bauldry, S. (2010). Model Identification and Computer Algebra. Sociological Methods & Research, 39, p. 127-156.

See Also

mxModel

Examples

require(OpenMx)

data(demoOneFactor)
manifests <- names(demoOneFactor)
latents <- "G1"
model2 <- mxModel(model="One Factor", type="RAM",
      manifestVars = manifests,
      latentVars = latents,
      mxPath(from = latents[1], to=manifests[1:5]),
      mxPath(from = manifests, arrows = 2, lbound=1e-6),
      mxPath(from = latents, arrows = 2, free = FALSE, values = 1.0),
      mxData(cov(demoOneFactor), type = "cov", numObs=500)
)
fit2 <- mxRun(model2)

id2 <- mxCheckIdentification(fit2)
id2$status
# The model is locally identified

# Build a model from the solution of the previous one
#  but now the factor variance is also free
model2n <- mxModel(fit2, name="Non Identified Two Factor",
      mxPath(from=latents[1], arrows=2, free=TRUE, values=1)
)

mid2 <- mxCheckIdentification(model2n)
mid2$non_identified_parameters
# The factor loadings and factor variance
#  are not identified.

Likelihood ratio test

Description

Compare the fit of one or more models to that of a reference (base) model or set of reference models.

Usage

mxCompare(base, comparison, ..., all = FALSE,
  boot=FALSE, replications=400, previousRun=NULL, checkHess=FALSE)
mxCompareMatrix(models,
			    diag=c('minus2LL','ep','df','AIC'),
			    stat=c('p', 'diffLL','diffdf'), ...,
  boot=FALSE, replications=400, previousRun=NULL,
 checkHess=FALSE, wholeTable=FALSE)

Arguments

Details

mxCompare is used to compare the fit of one or more mxModels to one or more comparison models. mxCompareMatrix compares all the models provided against each other.

Model comparisons are made by subtracting the fit statistics for the comparison model from the fit statistics for the base model. Raw fit statistics of each ‘base’ model are also listed in the output table.

The fit statistics compared depend on the kinds of models compared. Models fit with maximum likelihood are compared based on their minus two log likelihood values. Under certain regularity conditions, the difference in minus two log likelihood values from nested models is chi-squared distributed and forms a likelihood ratio test statistic. Models fit with weighted least squares are compared based on their Satorra-Bentler (2001) scaled difference chi-squared test statistics. Under full weighted least squares, the Satorra-Bentler chi-squared value is equal to the difference in the model chi-squared values; however, for unweighted and diagonally weighted least squares, the two are no longer equal. Satorra and Bentler (2001) showed that that their test statistic behaved well under a variety of conditions, including small sample sizes. By contrast the much simpler difference in the chi-squared statistics only behaved well under large sample sizes (e.g., greater than or equal to 300 rows of data).

Specific to weighted least squares, researchers sometimes use mean-adjusted chi-squared statistics and mean-and-variance scaled chi-squared statistics. Some programs call these WLSM and WLSMV statistics. In some cases, it is fine to evaluate the total fit of a model using adjusted and scaled chi-squared statistics. However, never, ever, ever, ..., ever take differences in mean-adjusted chi-squared statistics, and use them for nested model comparisons. Similarly, never, ever, ever, ..., ever, ever take differences in mean-and-variance scaled chi-squared statistics, and use them for nested model comparisons. The differences in these adjusted and scaled chi-squared statistics are not chi-squared distributed and do not form a valid basis for model comparison. So, just don't do it.

Although not always checked by mxCompare, you should never compare models with different data sets or that use different variables from the same data set. mxCompare might not stop you from doing this, so be thoughtful when comparing models. Make sure your models are nested and use the same data. Weighted least squares models are one case of comparing different data sets that requires particular care. When comparing WLS models, make sure you are using the same exogenous covariates for all compared models. Because WLS is a multi-stage estimation approach, exogenous covariates residualize and change the data fitted in WLS. Consequently, WLS models with different exogenous covariates actually have different data. By contrast, maximum likelihood models with different exogenous covariates still use the same data and are valid to compare.

The mxCompare function makes an effort to only make valid comparisons. If a comparison is made where the comparison model has a higher minus 2 log likelihood (-2LL) than the base model, then the difference in their -2LLs will be negative. P-values for likelihood ratio tests will not be reported when either the -2LL or degrees of freedom for the comparison are negative. To ensure that the differences between models are positive and yield p-values for likelihood ratio tests, models listed in the ‘base’ argument must be more saturated (i.e., more estimated parameters and fewer degrees of freedom) than models listed in the ‘comparison’ argument. For mxCompareMatrix only the comparisons that make sense will be included.

When multiple models are included in both the ‘base’ and ‘comparison’ arguments, then comparisons are made between the two lists of models based on the value of the ‘all’ argument. If ‘all’ is set to FALSE (default), then the first model in the ‘base’ list is compared to the first model in the ‘comparison’ list, second with second, and so on. If there are an unequal number of ‘base’ and ‘comparison’ models, then the shorter list of models is repeated to match the length of the longer list. For example, comparing base models ‘B1’ and ‘B2’ with comparison models ‘C1’, ‘C2’ and ‘C3’ will yield three comparisons: ‘B1’ with ‘C1’, ‘B2’ with ‘C2’, and ‘B1’ with ‘C3’. Each of those comparisons are prefaced by a comparison between the base model and a missing comparison model to present the fit of the base model.

If ‘all’ is set to TRUE, all possible comparisons between base and comparison models are made, and one entry is made for each base model. All comparisons involving the first model in ‘base’ are made first, followed by all comparisons with the second ‘base’ model, and so on. When there are multiple models in either the ‘base’ or ‘comparison’ arguments but not both, then the ‘all’ argument does not affect the set of comparisons made.

The following columns appear in the output for maximum likelihood comparisons:

base

Name of the base model.

comparison

Name of the comparison model. Is <NA> for the first

ep

Estimated parameters of the comparison model.

minus2LL

Minus 2*log-likelihood of the comparison model. If the comparison model is <NA>, then the minus 2*log-likelihood of the base model is given.

df

Degrees in freedom of the comparison model. If the comparison model is <NA>, then the degrees of freedom of the base model is given.

AIC

Akaike's Information Criterion for the comparison model. If the comparison model is <NA>, then the AIC of the base model is given.

diffLL

Difference in minus 2*log-likelihoods of the base and comparison models. Will be positive when base model -2LL is higher than comparison model -2LL.

diffdf

Difference in degrees of freedoms of the base and comparison models. Will be positive when base model DF is lower than comparison model DF (base model estimated parameters is higher than comparison model estimated parameters)

p

P-value for likelihood ratio test based on diffLL and diffdf values.

Weighted least squares reports a similar set of columns with four substitutions:

chisq

Replaces the minus2LL column. This is the comparison model's chi-squared statistic from Browne (1984, Equation 2.20a), accounting for some misspecification of the weight matrix.

AIC

Although this has the same name as that in maximum likelihood, it is really a pseudo-AIC using the comparison model chi-squared and the number of estimated parameters. It is the chi-squared value plus two times the number of free parameters.

SBchisq

Replaces the diffLL column. This is the Satorra-Bentler (2001, p. 511) scaled difference chi-squared statisic between the base model and the comparison model. If your models use full weighted least squares, then this will be the same as the difference between the individual model chi-squared statistics. However, for unweighted and diagonally weighted least square, the SB chisq will not be equal to the difference between the component model chi-squared statistics.

p

p-value for the Satorra-Bentler chi-squared statistic.

In addition to the particular columns for maximum likelihood and weighted least squares, there are three general columns that are not printed but are accessible via the $ and [ extractors.

fit

The individual model fit value: m2ll for maximum likelihood models, chisq for WLS models.

fitUnits

The units of the fit function: "-2LL" for ML models, "r'Wr" for WLS models.

diffFit

The difference in fit values between the base and comparison models: diffLL for ML models, SBchisq for WLS models.

mxCompare will give a p-value for any comparison in which both ‘diffLL’ and ‘diffdf’ are non-negative. However, this p-value is based on the assumptions of the likelihood ratio test, specifically that the two models being compared are nested. The likelihood ratio test and associated p-values are not valid when the comparison model is not nested in the referenced base model. For a more accurate p-value, the empirical bootstrap distribution can be computed (‘boot=TRUE’). However, ‘replications’ must be set high enough for an accurate approximation. The Monte Carlo SE of a proportion for B replications is \sqrt(p*(1-p)/B), but this will be zero if p is zero, which is nonsense. Note that a parametric-bootstrap p-value of zero must be interpreted as p < 1/B, which, depending on B and the desired Type I error rate, may not be "statistically significant."

When ‘boot=TRUE’, the model has a default compute plan, and ‘checkHess’ is kept at FALSE then the Hessian will not be approximated or checked. On the other hand, ‘checkHess’ is TRUE then the Hessian will be approximated by finite differences. This procedure is of some value because it can be informative to check whether the Hessian is positive definite (see mxComputeHessianQuality). However, approximating the Hessian is often costly in terms of CPU time. For bootstrapping, the parameter estimates derived from the resampled data are typically of primary interest.

note: The mxCompare function does not directly accept a digits argument, and depends on the value of the 'digits' option. To set the minimum number of significant digits printed, use options('digits' = N) (see example).

Value

Returns a new MxCompare object. If you want something more like a table of results, use as.data.frame() on the returned MxCompare object.

See Also

mxPowerSearch; mxModel; options (use options('mxOptions') to see all the OpenMx-specific options)

Examples

data(demoOneFactor)
manifests <- names(demoOneFactor)
latents <- "G1"
model1 <- mxModel(model="One Factor", type="RAM",
      manifestVars = manifests,
      latentVars = latents,
      mxPath(from = latents, to=manifests),
      mxPath(from = manifests, arrows = 2),
      mxPath(from = latents, arrows = 2, free = FALSE, values = 1.0),
      mxData(cov(demoOneFactor), type = "cov", numObs = 500)
)

fit1 <- mxRun(model1)

latents <- c("G1", "G2")
model2 <- mxModel(model="One factor Rasch equated", type="RAM",
      manifestVars = manifests,
      latentVars = latents,
      mxPath(from = latents[1], to=manifests[1:5], labels='raschEquated'),

      mxPath(from = manifests, arrows = 2),
      mxPath(from = latents, arrows = 2, free = FALSE, values = 1.0),
      mxData(cov(demoOneFactor), type = "cov", numObs=500)
)
fit2 <- mxRun(model2)

mxCompare(fit1, fit2) # Rasch equated is significantly worse

# Vary precision (rounding) of the table 
oldPrecision = as.numeric(options('digits')) 
options('digits' = 1)
mxCompare(fit1, fit2)
options('digits' = oldPrecision)

Repeatedly estimate model using resampling with replacement

Description

This is a low-level compute plan object to perform resampling with replacement.

Usage

mxComputeBootstrap(data, plan, replications=200, ...,
                        verbose=0L, parallel=TRUE, freeSet=NA_character_,
			OK=c("OK", "OK/green"), only=NA_integer_)

Arguments

Details

The ‘only’ option facilitates investigation of a single replication attempt.

Value

Output is stored in the compute object's output slot. Specifically, model$compute$output$raw contains a data frame with parameters in columns and replications in rows. In addition to parameters, the seed, fit, and statusCode of the replication is also included.

When ‘only’ is set to a particular replications, the weight vectors (one per dataset) are also returned in the compute object's output slot. model$compute$output$weight is a character vector (by dataset name) of numeric vectors (the weights). These weights can be used to recreate a model identical to the model used in the given replication.

See Also

mxBootstrap, as.statusCode

Log parameters and state to disk or memory

Description

Captures the current state of the backend. When path is set, the state is written to disk in a single row. When toReturn is set, the state is recorded in memory and returned after mxRun.

Usage

mxComputeCheckpoint(
  what = NULL,
  ...,
  path = NULL,
  append = FALSE,
  header = TRUE,
  toReturn = FALSE,
  parameters = TRUE,
  loopIndices = TRUE,
  fit = TRUE,
  counters = TRUE,
  status = TRUE,
  standardErrors = FALSE,
  gradient = FALSE,
  vcov = FALSE,
  vcovFilter = c(),
  sampleSize = FALSE,
  vcovWLS = FALSE,
  useVcovFilter = FALSE
)

Arguments

See Also

mxComputeLoadData, mxComputeLoadMatrix, mxComputeLoadContext, mxComputeLoop

Other model state: mxRestore(), mxSave()

Examples

library(OpenMx)

m1 <- mxModel(
  "poly22", # Eqn 22 from Tsallis & Stariolo (1996)
  mxMatrix(type='Full', values=runif(4, min=-1e6, max=1e6),
           ncol=1, nrow=4, free=TRUE, name='x'),
  mxAlgebra(sum((x*x-8)^2) + 5*sum(x) + 57.3276, name="fit"),
  mxFitFunctionAlgebra('fit'))

plan <- mxComputeLoop(list(
  mxComputeSetOriginalStarts(),
    mxComputeSimAnnealing(method="tsallis1996",
                          control=list(tempEnd=1)),
    mxComputeCheckpoint(path = "result.log")),
  i=1:4)

m1 <- mxRun(mxModel(m1, plan)) # see the file 'result.log'

Find likelihood-based confidence intervals

Description

There are various equivalent ways to pose the optimization problems required to estimate confidence intervals. Most accurate solutions are achieved when the problem is posed using non-linear constraints. However, the available optimizers (CSOLNP, SLSQP, and NPSOL) often have difficulty with non-linear constraints.

Usage

mxComputeConfidenceInterval(
  plan,
  ...,
  freeSet = NA_character_,
  verbose = 0L,
  engine = NULL,
  fitfunction = "fitfunction",
  tolerance = NA_real_,
  constraintType = "none"
)

Arguments

References

Neale, M. C. & Miller M. B. (1997). The use of likelihood based confidence intervals in genetic models. Behavior Genetics, 27(2), 113-120.

Pek, J. & Wu, H. (2015). Profile likelihood-based confidence intervals and regions for structural equation models. Psychometrika, 80(4), 1123-1145.

Wu, H. & Neale, M. C. (2012). Adjusted confidence intervals for a bounded parameter. Behavior genetics, 42(6), 886-898.

Default compute plan

Description

This is an empty placeholder for the default compute plan. To create an actual plan, use omxDefaultComputePlan.

Usage

mxComputeDefault(freeSet = NA_character_)

Arguments

Fit a model using DLR's (1977) Expectation-Maximization (EM) algorithm

Description

The EM algorithm constitutes the following steps: Start with an initial parameter vector. Predict the missing data to form a completed data model. Optimize the completed data model to obtain a new parameter vector. Repeat these steps until convergence criteria are met.

Usage

mxComputeEM(
  expectation = NULL,
  predict = NA_character_,
  mstep,
  observedFit = "fitfunction",
  ...,
  maxIter = 500L,
  tolerance = 1e-09,
  verbose = 0L,
  freeSet = NA_character_,
  accel = "varadhan2008",
  information = NA_character_,
  infoArgs = list(),
  estep = NULL
)

Arguments

Details

The arguments to this function have evolved. The old style mxComputeEM(e,p,mstep=m) is equivalent to the new style mxComputeEM(estep=mxComputeOnce(e,p), mstep=m). This change allows the API to more closely match the literature on the E-M method. You might use mxAlgebra(..., recompute='onDemand') to contain the results of the E-step and then cause this algebra to be recomputed using mxComputeOnce.

This compute plan does not work with any and all expectations. It requires a special kind of expectation that can predict its missing data to create a completed data model.

The EM algorithm does not produce a parameter covariance matrix for standard errors. The Oakes (1999) direct method and S-EM, an implementation of Meng & Rubin (1991), are included.

Ramsay (1975) was recommended in Bock, Gibbons, & Muraki (1988).

References

Bock, R. D., Gibbons, R., & Muraki, E. (1988). Full-information item factor analysis. Applied Psychological Measurement, 6(4), 431-444.

Dempster, A. P., Laird, N. M., & Rubin, D. B. (1977). Maximum likelihood from incomplete data via the EM algorithm. Journal of the Royal Statistical Society. Series B (Methodological), 1-38.

Meng, X.-L. & Rubin, D. B. (1991). Using EM to obtain asymptotic variance-covariance matrices: The SEM algorithm. Journal of the American Statistical Association, 86 (416), 899-909.

Oakes, D. (1999). Direct calculation of the information matrix via the EM algorithm. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 61(2), 479-482.

Ramsay, J. O. (1975). Solving implicit equations in psychometric data analysis. Psychometrika, 40 (3), 337-360.

Varadhan, R. & Roland, C. (2008). Simple and globally convergent methods for accelerating the convergence of any EM algorithm. Scandinavian Journal of Statistics, 35, 335-353.

See Also

MxAlgebra, mxComputeOnce

Examples

library(OpenMx)
set.seed(190127)

N <- 200
x <- matrix(c(rnorm(N/2,0,1),
              rnorm(N/2,3,1)),ncol=1,dimnames=list(NULL,"x"))
data4mx <- mxData(observed=x,type="raw")

class1 <- mxModel("Class1",
	mxMatrix(type="Full",nrow=1,ncol=1,free=TRUE,values=0,name="Mu"),
	mxMatrix(type="Full",nrow=1,ncol=1,free=TRUE,values=4,name="Sigma"),
	mxExpectationNormal(covariance="Sigma",means="Mu",dimnames="x"),
	mxFitFunctionML(vector=TRUE))

class2 <- mxRename(class1, "Class2")

mm <- mxModel(
	"Mixture", data4mx, class1, class2,
	mxAlgebra((1-Posteriors) * Class1.fitfunction, name="PL1"),
	mxAlgebra(Posteriors * Class2.fitfunction, name="PL2"),
	mxAlgebra(PL1 + PL2, name="PL"),
	mxAlgebra(PL2 / PL,  recompute='onDemand',
	          initial=matrix(runif(N,.4,.6), nrow=N, ncol = 1), name="Posteriors"),
	mxAlgebra(-2*sum(log(PL)), name="FF"),
	mxFitFunctionAlgebra(algebra="FF"),
	mxComputeEM(
	  estep=mxComputeOnce("Mixture.Posteriors"),
	  mstep=mxComputeGradientDescent(fitfunction="Mixture.fitfunction")))

mm <- mxOption(mm, "Max minutes", 1/20)  # remove this line to find optimum
mmfit <- mxRun(mm)
summary(mmfit)

Generate data

Description

Generate data specified by the model expectations.

Usage

mxComputeGenerateData(expectation = "expectation")

Arguments

Optimize parameters using a gradient descent optimizer

Description

This optimizer does not require analytic derivatives of the fit function. The fully open-source CRAN version of OpenMx offers 2 choices, CSOLNP and SLSQP (from the NLOPT collection). The OpenMx Team's version of OpenMx offers the choice of three optimizers: CSOLNP, SLSQP, and NPSOL.

Usage

mxComputeGradientDescent(
  freeSet = NA_character_,
  ...,
  engine = NULL,
  fitfunction = "fitfunction",
  verbose = 0L,
  tolerance = NA_real_,
  useGradient = deprecated(),
  warmStart = NULL,
  nudgeZeroStarts = mxOption(NULL, "Nudge zero starts"),
  maxMajorIter = NULL,
  gradientAlgo = deprecated(),
  gradientIterations = deprecated(),
  gradientStepSize = deprecated()
)

Arguments

Details

All three optimizers can use analytic gradients, and only NPSOL uses warmStart. To customize more options, see mxOption.

References

Luenberger, D. G. & Ye, Y. (2008). Linear and nonlinear programming. Springer.

Examples

data(demoOneFactor)
factorModel <- mxModel(name ="One Factor",
  mxMatrix(type="Full", nrow=5, ncol=1, free=FALSE, values=0.2, name="A"),
    mxMatrix(type="Symm", nrow=1, ncol=1, free=FALSE, values=1, name="L"),
    mxMatrix(type="Diag", nrow=5, ncol=5, free=TRUE, values=1, name="U"),
    mxAlgebra(expression=A %*% L %*% t(A) + U, name="R"),
  mxExpectationNormal(covariance="R", dimnames=names(demoOneFactor)),
  mxFitFunctionML(),
    mxData(observed=cov(demoOneFactor), type="cov", numObs=500),
     mxComputeSequence(steps=list(
     mxComputeGradientDescent(),
     mxComputeNumericDeriv(),
     mxComputeStandardError(),
     mxComputeHessianQuality()
    )))
factorModelFit <- mxRun(factorModel)
factorModelFit$output$conditionNumber # 29.5

Compute the quality of the Hessian

Description

Tests whether the Hessian is positive definite (model$output$infoDefinite) and, if so, computes the approximate condition number (model$output$conditionNumber). See Luenberger & Ye (2008) Second Order Test (p. 190) and Condition Number (p. 239).

Usage

mxComputeHessianQuality(freeSet = NA_character_, ..., verbose = 0L)

Arguments

Details

The condition number is approximated by \mathrm{norm}(H) * \mathrm{norm}(H^{-1}) where H is the Hessian. The norm is either the 1- or infinity-norm (both obtain the same result due to symmetry).

References

Luenberger, D. G. & Ye, Y. (2008). Linear and nonlinear programming. Springer.

Repeatedly invoke a series of compute objects until change is less than tolerance

Description

One step (typically the last) must compute the fit or maxAbsChange.

Usage

mxComputeIterate(
  steps,
  ...,
  maxIter = 500L,
  tolerance = 1e-09,
  verbose = 0L,
  freeSet = NA_character_,
  maxDuration = as.numeric(NA)
)

Arguments

Numerically estimate the Jacobian with respect to free parameters

Description

When algebra names are given, all algebras must belong to the same model.

When expectations are given, the Jacobian is taken with respect to the manifest model. The manifest model excludes any latent variables or processes. For RAM and LISREL models, the manifest model contains only the manifest variables with free means, covariance, and thresholds. Ordinal manifest variables are standardized.

Usage

mxComputeJacobian(freeSet=NA_character_, ..., of = "expectation",
 defvar.row=as.integer(NA), data='data')

Arguments

See Also

omxManifestModelByParameterJacobian, mxGetExpected

Load contextual data to supplement checkpoint

Description

Usage

mxComputeLoadContext(
  method = c("csv"),
  path = c(),
  column,
  ...,
  sep = " ",
  verbose = 0L,
  header = TRUE,
  col.names = NULL
)

Arguments

Details

Currently, this only supports comma separated value format and no row names. If header=TRUE and col.names are provided, the col.names take precedence. If header=FALSE and no col.names are provided then the column names consist of the file name and column offset.

An originalDataIsIndexOne option is not offered. You'll need to add an extra line at the start on your file if you wish to make use of originalDataIsIndexOne in mxComputeLoad*.

See Also

mxComputeCheckpoint, mxComputeLoadData, mxComputeLoadMatrix

Load columns into an MxData object

Description

Usage

mxComputeLoadData(
  dest,
  column,
  method = c("csv", "data.frame"),
  ...,
  path = c(),
  originalDataIsIndexOne = FALSE,
  byrow = TRUE,
  row.names = c(),
  col.names = c(),
  skip.rows = 0,
  skip.cols = 0,
  verbose = 0L,
  cacheSize = 100L,
  checkpointMetadata = TRUE,
  na.strings = c("NA"),
  observed = NULL,
  rowFilter = c()
)

Arguments

Details

The purpose of this compute step is to help quickly perform many similar analyses. For example, if we are given a sample of people with a few million SNPs (single-nucleotide polymorphism) per person then we could fit a separate model for each SNP by iterating over the SNP data.

The column names given in the column parameter must already exist in the model's MxData object. Pre-existing data is assumed to be a placeholder and is not used unless originalDataIsIndexOne is set to TRUE.

For method='csv', the highest performance arrangement is byrow=TRUE because entire columns are stored in single chunks (rows) on the disk and can be easily loaded. For byrow=FALSE, the data requires transposition. To load a single column of observed data, it is necessary to read through the whole file. This can be slow for large files. To amortize the cost of transposition, cacheSize columns are loaded on every pass through the file.

After mxRun returns, the dest mxData object will contain the most recently loaded data. Hence, any single analysis of a series can be reproduced by issuing mxComputeLoadData with the single index associated with a particular dataset, replacing the compute plan with something like omxDefaultComputePlan, and then passing the model back through mxRun. This can be a helpful approach when investigating unexpected results.

See Also

mxComputeLoadMatrix, mxComputeCheckpoint, mxRun, omxDefaultComputePlan

Load data from CSV files directly into the backend

Description

THIS INTERFACE IS EXPERIMENTAL AND SUBJECT TO CHANGE.

For method='csv', the file must be formatted in a specific way. The number of columns must match the number of entries available in the mxMatrix. Matrix types (e.g., symmetric or diagonal) are respected (see mxMatrix). For example, a Full 2x2 matrix will require 4 entries, but a diagonal matrix of the same size will only require 2 entries. CSV data must be stored space separated and without row or column names. The destination mxMatrix can have free parameters, but cannot have square bracket populated entries.

If originalDataIsIndexOne is TRUE then this compute step does nothing when the loop index is 1. The purpose of originalDataIsIndexOne is to permit usage of the dataset that was initially included with the model.

Usage

mxComputeLoadMatrix(dest, method=c('csv','data.frame'), ...,
 path=NULL, originalDataIsIndexOne=FALSE,
 row.names=FALSE, col.names=FALSE, observed=NULL)

Arguments

See Also

mxComputeLoadData, mxComputeCheckpoint

Examples

library(OpenMx)

dir <-tempdir()  # safe place to create files

Cov <- rWishart(4, 20, toeplitz(c(2,1)/20))
write.table(t(apply(Cov, 3, vech)),
            file=file.path(dir, "cov.csv"),
            col.names=FALSE, row.names=FALSE)
Mean <- matrix(rnorm(8),4,2)
write.table(Mean, file=file.path(dir, "mean.csv"),
            col.names=FALSE, row.names=FALSE)

m1 <- mxModel(
  "test1",
  mxMatrix("Full", 1,2, values=0,       name="mean"),
  mxMatrix("Symm", 2,2, values=diag(2), name="cov"),
  mxMatrix("Full", 1,2, values=-1,      name="lbound"),
  mxMatrix("Full", 1,2, values=1,       name="ubound"),
  mxAlgebra(omxMnor(cov,mean,lbound,ubound), name="area"),
  mxFitFunctionAlgebra("area"),
  mxComputeLoop(list(
    mxComputeLoadMatrix(c('mean', 'cov'),
                        path=file.path(dir, c('mean.csv', 'cov.csv'))),
    mxComputeOnce('fitfunction', 'fit'),
    mxComputeCheckpoint(path=file.path(dir, "loadMatrix.csv"))
  ), i=1:4))

m1 <- mxRun(m1)

Repeatedly invoke a series of compute objects

Description

When i is given then these values are iterated over instead of the sequence 1 to the number of iterations.

Usage

mxComputeLoop(
  steps,
  ...,
  i = NULL,
  maxIter = as.integer(NA),
  freeSet = NA_character_,
  maxDuration = as.numeric(NA),
  verbose = 0L,
  startFrom = 1L
)

Arguments

Optimize parameters using a variation of the Nelder-Mead algorithm.

Description

OpenMx includes a flexible, options-rich implementation of the Nelder-Mead algorithm.

Usage

mxComputeNelderMead(
	freeSet=NA_character_, fitfunction="fitfunction", verbose=0L, 
	nudgeZeroStarts=mxOption(NULL,"Nudge zero starts"), 
	maxIter=NULL,	...,
	alpha=1, betao=0.5, betai=0.5, gamma=2, sigma=0.5, bignum=1e35, 
	iniSimplexType=c("regular","right","smartRight","random"),
	iniSimplexEdge=1, iniSimplexMat=NULL, greedyMinimize=FALSE, 
	altContraction=FALSE, degenLimit=0, stagnCtrl=c(-1L,-1L),
	validationRestart=TRUE,
	xTolProx=1e-8, fTolProx=1e-8,
	doPseudoHessian=TRUE,
	ineqConstraintMthd=c("soft","eqMthd"), 
	eqConstraintMthd=c("GDsearch","soft","backtrack","l1p"),
	backtrackCtrl=c(0.5,5),
	centerIniSimplex=FALSE)

Arguments

Details

The state of a Nelder-Mead optimization problem is represented by a simplex (polytope) of n+1 vertices in the space of the free parameters, where n is the number of free parameters minus the number of degrees-of-freedom gained from equality MxConstraints. An iteration of the algorithm first sorts the n+1 vertices by their corresponding fitfunction values (i.e., the values of the fitfunction when evaluated at each vertex), in ascending order (i.e., from "best" fit to "worst" fit). Then, the "subcentroid," which is the centroid of the "best" n vertices, is calculated. Then, the algorithm attempts to improve upon the worst fit by transforming the simplex; see Singer & Nelder (2009) for details.

Argument iniSimplexType dictates how the initial simplex will be constructed from the start values if argument iniSimplexMat is NULL, and how the simplex will be re-initialized in the case of a restart. In all four cases, the vector of start values constitutes the "starting vertex" of the initial simplex. If iniSimplexType="regular", the initial simplex is merely a regular simplex with edge length equal to iniSimplexEdge. A "right" simplex is constructed by incrementing each free parameter by iniSimplexEdge from its starting value; thus, all the edges that intersect at the starting vertex do so at right angles. A "smartRight" simplex is constructed similarly, except that each free parameter is both incremented and decremented by iniSimplexEdge, and of those two points the one with the smaller fitfunction value is retained as a vertex. A "random" simplex is constructed by randomly perturbing the start values, in a manner similar to the default for mxTryHard(), to generate the coordinates of the other vertices. The user is advised that bounds on the free parameters may keep the initial simplex from having the requested regularity or edge-length, and that iniSimplexType is at best a suggestion in the presence of equality MxConstraints.

Note that if argument iniSimplexMat has nonzero length, the actual start values of the MxModel's free parameters are not used as a vertex of the initial simplex (unless one of the rows of iniSimplexMat happens to contain those start values).

If the simplex is restarted, a new simplex is constructed per argument iniSimplexType, with edge length equal to the distance between the current best and second-best vertices, and with the current best vertex used as the "first" vertex.

If greedyMinimize=FALSE, "greedy expansion" (Singer & Singer, 2004) is used: if the expansion point and reflection point both have smaller fitfunction values than the best vertex, the expansion point is accepted. If greedyMinimize=TRUE, "greedy minimization" (Singer & Singer, 2004) is used: if the expansion point and the reflection point both have smaller fitfunction values than the best vertex, the better of the two new points is accepted.

If argument altContraction=TRUE, the "modified contraction step" of Gill et al. (1982, Chapter 4) is used, and the candidate point is contracted toward the best vertex instead of toward the subcentroid.

If positive, the first element of argument stagnCtrl sets a threshold for the number of successive iterations in which the best vertex of the simplex does not change, after which the algorithm is said to be "stagnant" (in a sense similar to that of Kelley, 1999). To attempt to remedy the stagnation, the simplex is restarted. If positive, the second element of argument stagnCtrl sets threshold for the number of restarts conducted, beyond which stagnation no longer triggers a restart. The rationale for the second element is that the best vertex may not change for many iterations when the optimizer is close to convergence, under which circumstances restarting would be counterproductive, and in any event would require additional fitfunction evaluations.

If argument validationRestart=TRUE, then when the optimizer has successfully converged, it will restart the simplex and attempt to improve upon the tentative solution it already found. This validation restart (Gill et al., 1982, Chapter 4) always re-initializes the simplex as a regular simplex, centered on the best vertex of the tentative solution, with edge-length equal to the distance between the best and worst vertices of the tentative solution. Optimization proceeds until convergence to a solution with a better fit value, or 2n iterations have elapsed.

The Nelder-Mead optimizer is considered to have successfully converged if (1) the largest l-infinity norm of the vector-differences between the best vertex and the other vertices is less than argument xTolProx, or (2) if the largest absolute difference in fit value between the best vertex and the other vertices is less than fTolProx.

If argument doPseudoHessian=TRUE, there are no equality MxConstraints, and the "l1p" method (see below) is not in use for inequality MxConstraints, then OpenMx will attempt to calculate the "pseudo-Hessian" or "curvature" matrix as described in the appendix to Nelder & Mead (1965). If successful, this matrix will be stored in the 'output' slot of the post-run MxComputeNelderMead object. Although crude, its inverse can be used as an estimate of the repeated-sampling covariance matrix of the free parameters when the usual finite-differences Hessian is unreliable.

OpenMx's implementation of Nelder-Mead can handle nonlinear inequality MxConstraints reasonably well. Its default method for doing so, with argument ineqConstraintMthd="soft", imposes a "soft" feasibility constraint by assigning a fitfunction value of bignum to points that violate the constraints by more than mxOption 'Feasibility tolerance'. Alternately, with argument ineqConstraintMthd="eqMthd", inequality MxConstraints can be handled by the same method provided to argument eqConstraintMthd, whether or not equality MxConstraints are present.

OpenMx's implementation of Nelder-Mead respects equality MxConstraints, but does not handle them especially well. Its effectiveness at handling equalities may be improved by providing a matrix to argument iniSimplexMat that ensures all of the initial vertices are feasible. Users are warned that this Nelder-Mead implementation will not work correctly with MxModels containing redundant equality MxConstraints, and presently has no way of detecting whether any are present. If argument eqConstraintMthd="GDsearch" (the default), then whenever Nelder-Mead evaluates the fitfunction at an infeasible point, it initiates a subsidiary optimization that uses SLSQP to find the nearest (in squared Euclidean distance) feasible point, and replaces that feasible point for the infeasible one. The user should note that the function evaluations that occur during this subsidiary optimization are counted toward the total number of fitfunction evaluations during the call to mxRun(). The effectiveness of the 'GDsearch' method is often improved by setting mxOption 'Feasibility tolerance' to a stricter (smaller) value than the on-load default. The method specified by eqConstraintMthd="soft" is described in the preceding paragraph. If argument eqConstraintMthd="backtrack", then the optimizer attempts to backtrack from an infeasible point to a feasible point in a manner similar to that of Ghiasi et al. (2008), except that it used with all new points, and not just those encountered via reflection, expansion and contraction. In this case, the displacement from the prior point to the candidate point is reduced by the proportion provided as the first element of argument backtrackCtrl, and thus a new candidate point is considered. This process is repeated until feasibility of the candidate point is restored, or the number of attempts exceeds the second element of argument backtrackCtrl. If argument eqConstraintMthd="l1p", Nelder-Mead is used as part of an l_1-penalty algorithm. When using "l1p", the simplex gradient (Kelley, 1999) and "pseudo-Hessian" are never calculated.

Value

Returns an object of class 'MxComputeNelderMead'.

References

Ghiasi, H., Pasini, D., & Lessard, L. (2008). Constrained globalized Nelder-Mead method for simultaneous structural and manufacturing optimization of a composite bracket. Journal of Composite Materials, 42(7), p. 717-736. doi: 10.1177/0021998307088592

Gill, P. E., Murray, W., & Wright, M. H. (1982). Practical Optimization. Bingley, UK: Emerald Group Publishing Ltd.

Kelley, C. T. (1999). Detection and remediation of stagnation in the Nelder-Mead algorithm using a sufficient decrease condition. SIAM Journal of Optimization 10(1), p. 43-55.

Nelder, J. A., & Mead, R. (1965) . A simplex method for function minimization. The Computer Journal, 7, p. 308-313.

Singer, S., & Nelder, J. (2009). Nelder-Mead algorithm. Scholarpedia, 4(7):2928., revision #91557. http://www.scholarpedia.org/article/Nelder-Mead_algorithm .

Singer, S., & Singer, S. (2004). Efficient implementation of the Nelder-Mead search algorithm. Applied Numerical Analysis & Computational Mathematics Journal, 1(2), p. 524-534. doi: 10.1002/anac.200410015

Examples

foo <- mxComputeNelderMead()
str(foo)

Optimize parameters using the Newton-Raphson algorithm

Description

This optimizer requires analytic 1st and 2nd derivatives of the fit function. Box constraints are supported. Parameters can approach box constraints but will not leave the feasible region (even by some small epsilon>0). Non-finite fit values are interpreted as soft feasibility constraints. That is, when a non-finite fit is encountered, line search is continued after the step size is multiplied by 10%. Comprehensive diagnostics are available by increasing the verbose level.

Usage

mxComputeNewtonRaphson(
  freeSet = NA_character_,
  ...,
  fitfunction = "fitfunction",
  maxIter = 100L,
  tolerance = 1e-12,
  verbose = 0L
)

Arguments

References

Luenberger, D. G. & Ye, Y. (2008). Linear and nonlinear programming. Springer.

Compute nothing

Description

Note that this compute plan actually does nothing whereas mxComputeOnce("expectation", "nothing") may remove the prediction of an expectation.

Usage

mxComputeNothing()

Numerically estimate Hessian using Richardson extrapolation

Description

For N free parameters, Richardson extrapolation requires (iterations * (N^2 + N)) function evaluations. The implementation is closely based on the numDeriv R package.

Usage

mxComputeNumericDeriv(
  freeSet = NA_character_,
  ...,
  fitfunction = "fitfunction",
  parallel = TRUE,
  stepSize = imxAutoOptionValue("Gradient step size"),
  iterations = 4L,
  verbose = 0L,
  knownHessian = NULL,
  checkGradient = TRUE,
  hessian = TRUE,
  analytic = TRUE
)

Arguments

Details

In addition to an estimate of the Hessian, forward, central, and backward estimates of the gradient are made available in this compute plan's output slot.

When checkGradient=TRUE, the central difference estimate of the gradient is used to determine whether the first order convergence criterion is met. In addition, the forward and backward difference estimates of the gradient are compared for symmetry. When sufficient asymmetry is detected, the standard error is flagged. In the case, profile likelihood confidence intervals should be used for inference instead of standard errors (see mxComputeConfidenceInterval).

If provided, the square matrix knownHessian should have dimnames set to the names of some subset of the free parameters. Entries of the matrix set to NA will be estimated numerically while entries containing finite values will be copied to the Hessian result.

Examples

library(OpenMx)
data(demoOneFactor)
factorModel <- mxModel(name ="One Factor",
	mxMatrix(type = "Full", nrow = 5, ncol = 1, free = FALSE, values = .2, name = "A"),
	mxMatrix(type = "Symm", nrow = 1, ncol = 1, free = FALSE, values = 1 , name = "L"),
	mxMatrix(type = "Diag", nrow = 5, ncol = 5, free = TRUE , values = 1 , name = "U"),
	mxAlgebra(A %*% L %*% t(A) + U, name = "R"),
	mxExpectationNormal(covariance = "R", dimnames = names(demoOneFactor)),
	mxFitFunctionML(),
	mxData(cov(demoOneFactor), type = "cov", numObs = 500),
	mxComputeSequence(
		list(mxComputeNumericDeriv(), mxComputeReportDeriv())
	)
)
factorModelFit <- mxRun(factorModel)
factorModelFit$output$hessian

Compute something once

Description

Some models are optimized for a sparse Hessian. Therefore, it can be much more efficient to compute the inverse Hessian in comparison to computing the Hessian and then inverting it.

Usage

mxComputeOnce(
  from,
  what = NULL,
  how = NULL,
  ...,
  freeSet = NA_character_,
  verbose = 0L,
  .is.bestfit = FALSE
)

Arguments