Movatterモバイル変換

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 ismxModel, which makes a model. Models are containers formxData,matrices,mxPathsalgebras,mxBounds,confidence intervals, andmxConstraints.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 ormxFitFunctionAlgebra).

Note, for mxModels oftype="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) usingmxRun. This returns the fitted model.

You can summarize the results of the model usingsummary(yourModel)

Additional overview of model making and getting started

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

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

Expectation functions includemxExpectationNormal,mxExpectationRAM,mxExpectationLISREL, andmxExpectationStateSpace;

Fit functions includemxFitFunctionML,mxFitFunctionAlgebra,mxFitFunctionRow andmxFitFunctionR.

Datasets built into OpenMx

OpenMx comes with over a dozen useful datasets built-in. Discover them usingdata(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, RyneEstabrook, 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. Kirkpatrickrkirkpatrick2@vcu.edu

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 Goodrichgoodrich.ben@gmail.com [contributor]

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

• Jannik H. Orzekjannik.orzek@mailbox.org [contributor]

• Don van den Berghd.vandenbergh@uva.nl [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 athttps://openmx.ssri.psu.edu/documentation

See Also

Useful links:

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

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

• Report bugs athttps://openmx.ssri.psu.edu/forums/

Examples

library(OpenMx)data(demoOneFactor)# ===============================# = Make and run a 1-factor CFA =# ===============================latents  = c("G") # the latent factormanifests = 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

Thesem 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, andMBESS), 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 forpaper andflagssub for the lozenges testflags.

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 anamed entity.New instances of this class can be created using the functionmxAlgebra.

Details

The MxAlgebra class has the following slots:

The ‘name’ slot is the name of the MxAlgebra object. Use of MxAlgebra objects in themxConstraint 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 themxAlgebra 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 forClasses and the examples in themxAlgebra document for more information.

References

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

See Also

mxAlgebra,mxMatrix,MxMatrix

MxAlgebraFormula

Description

This is an internal class for the formulas used inmxAlgebra calls.

MxBaseExpectation

Description

The virtual base class for all expectations. Expectations containenough information to generate simulated data. This is an internalclass 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 thebase class for named entities. Fit functions, expectations, and computescontain 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 canbe created using the functionmxBounds.

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 anMxMatrix object. Parameters may be referenced either by name or by referring to their position in the 'spec' matrix of anMxMatrix object. To affect an estimation or optimization, an MxBounds object must be included in anMxModel object with all referencedMxAlgebra andMxMatrix objects.

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

References

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

See Also

mxBounds for the function that creates MxBounds objects.MxMatrix andmxMatrix for free parameter specification. More information about the OpenMx package may be foundhere.

MxCI Class

Description

MxCI is an S4 class. An MxCI object is anamed entity.New instances of this class can be created using the functionmxCI.MxCI objects may be used as arguments in themxModel function.

Details

The MxCI class has the following slots:

The reference slot contains a character vector of named free parameters,MxMatrices andMxAlgebras on which confidence intervals are desired. Individual elements ofMxMatrices andMxAlgebras may be listed as well, using the syntax “matrix[row,col]” (seeExtract 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 anMxModel object. Estimation of confidence intervals requires model optimization using themxRun 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 athttps://openmx.ssri.psu.edu/documentation/.

See Also

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

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.UsemxCompare instead.

MxCompute

Description

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

Class"MxConstraint"

Description

MxConstraint is an S4 class. An MxConstraint objectis anamed entity. New instances of this class canbe created using the functionmxConstraint().

Details

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

Slots

name:

Character string; the name of the object.

formula:

Object of class"MxAlgebraFormula". TheMxAlgebra-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 theMxAlgebra representing the Jacobian for the constraint function.

linear:

Logical. For internal use.

strict:

Logical. Whether to require that all Jacobian entries referencefree parameters.

verbose:

integer. For values greater than zero, enable runtimediagnostics.

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 athttps://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 anamed entity.New instances of this class can be created using the functionmxData.MxData is an S4 class union. An MxData object is eitherNULL 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 themxFitFunctionML 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 themxFitFunctionML 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 themxFitFunctionML, 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 themxFitFunctionML, 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 themxData function when the MxData argument is created.

MxData objects may not be included inMxAlgebra objects or use themxFitFunctionAlgebra function. If these capabilities are desired, data should be appropriately input or transformed using themxMatrix andmxAlgebra functions.

While column names are stored in the ‘observed’ slot of MxData objects, these names are not recognized as variable names inMxPath objects. Variable names must be specified using the 'manifestVars' argument of themxModel function prior to use inMxPath 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 athttps://openmx.ssri.psu.edu/documentation/.

See Also

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

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, seemxExpectationGREML().

Objects from the Class

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

Slots

V:

Object of class"MxCharOrNumber". Identifies theMxAlgebra orMxMatrix 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". Itsobserved 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 theMxAlgebra orMxMatrix 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 athttps://openmx.ssri.psu.edu/documentation/.

See Also

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

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 formmxFitFunctionGREML(dV).

Slots

dV:

Object of class"MxCharOrNumber". Identifies theMxAlgebra orMxMatrix 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 slotdV. Provides the mapping from elements ofaugGrad and of rows and columns ofaugHess 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 theMxAlgebra orMxMatrix object used to "augment" the fitfunction value at each function evaluation during optimization.

augGrad:

Object of class"MxCharOrNumber". Identifies theMxAlgebra orMxMatrix object(s) to serve as the first derivatives ofaug with respect to free parameters.

augHess:

Object of class"MxCharOrNumber". Identifies theMxAlgebra orMxMatrix object(s) to serve as the second derivatives ofaug 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 theMxAlgebra orMxMatrix 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 slotdyhat.

dNames:

Vector of character strings. IfdV and/ordyhat have nonzero length, then populated at runtime by the set of non-redundant free-parameter names appearing indVnames and/ordyhatnames.

.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 athttps://openmx.ssri.psu.edu/documentation/.

See Also

SeemxFitFunctionGREML() for creating MxFitFunctionGREML objects. SeemxExpectationGREML() for creating MxExpectationGREML objects, and for more information generally concerning GREML analyses, including a complete example. More information about the OpenMx package may be foundhere.

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 (seemxMatrix() for details). An MxMatrix object is anamed entity. New instances of this class can be created using the functionmxMatrix(). MxMatrix objects may be used as arguments in other functions from the OpenMx package, includingmxAlgebra(),mxConstraint(), andmxModel().

Objects from the Class

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

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 inR's workspace. Use of MxMatrix objects in anmxAlgebra ormxConstraint 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 anmxRun() 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 anmxRun() 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 anMxModel object and evaluated using themxRun() 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 howmxRun() handles the MxMatrix object when it is inside theMxModel being run.

.condenseSlots:

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

display:

Character string; used internally by OpenMx when parsingMxAlgebras.

dependencies:

Integer; used internally by OpenMx when parsingMxAlgebras.

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 athttps://openmx.ssri.psu.edu/documentation.

See Also

mxMatrix() for creating MxMatrix objects. Note that functionsimxCreateMatrix(),imxDeparse(),imxSquareMatrix(),imxSymmetricMatrix(), andimxVerifyMatrix() are separately documented methods for this class. More information about the OpenMx package may be foundhere.

Examples

showClass("MxMatrix")

MxModel Class

Description

MxModel is an S4 class. An MxModel object is anamed entity.

Details

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

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

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

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

The ‘latentVars’ slot contains a list of latent variable names,which may be referenced byMxPath objects. Thisslot defaults to 'NA', and is only used when themxPath functionis used. In the context of a RAM model, this slot accepts a charactervector of variable names. However, the LISREL model is partitioned intoexogenous and endogenous parts. Both exogenous and endogenous variablescan be specified using a list like,list(endo='a', exo='b').If a character vector is passed to a LISREL model then thosevariables will be assumed endogenous.

The ‘manifestVars’ slot contains a list of latent variable names,which may be referenced byMxPath objects. Thisslot defaults to 'NA', and is only used when themxPath functionis used. In the context of a RAM model, this slot accepts a charactervector of variable names. However, the LISREL model is partitioned intoexogenous and endogenous parts. Both exogenous and endogenous variablescan be specified using a list like,list(endo='a', exo='b').If a character vector is passed to a LISREL model then thosevariables will be assumed endogenous.

The ‘data’ slot contains anMxData object. This slot must be filled prior to execution when a fitfunction referencing data is used. Only oneMxData object may be included per model, but submodels may have their own data in their own ‘data’ slots. If anMxData object is added to an MxModel which already contains anMxData 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 usingmxRun, 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 themxOption function.

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

Named entities inMxModel 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 forClasses and the examples inmxModel for more information.

Objects from the Class

Objects can be created by calls of the formmxModel().

Slots

name:

Character string. The name of the model object.

matrices:

List of the model'sMxMatrix objects.

algebras:

List of the model'sMxAlgebra objects.

constraints:

List of the model'sMxConstraint objects.

intervals:

List of the model'sMxIntervalobjects, requested viamxCI().

penalties:

List of the model'sMxPenaltyobjects.

latentVars:

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

manifestVars:

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

data:

Object of classMxData.

submodels:

List of MxModel objects.

expectation:

Object of classMxExpectation; dictates the model's specification.

fitfunction:

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

compute:

Object of classMxCompute–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 bymxOption().

output:

List of model output produced during a call tomxRun().

.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 constituentnamed 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 constituentnamed entities.

[[<-

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

names

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

print

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

show

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

Note thatimxInitModel(),imxModelBuilder(),imxTypeName(), andimxVerifyModel() are separately documented methods for class "MxModel".

References

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

See Also

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

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 fromhttps://openmx.ssri.psu.edu/node/144

References

Boker, S., Neale, M., & Rausch, J. (2004). Latent differential equation modeling with multivariate multi-occasion indicators. InRecent 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 bya more colloquial, less precise desciption.

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

• 1,‘OK/green’: Optimization succeeded, but the sequenceof iterates has not yet converged (Mx status GREEN). This condition is only detected byNPSOL. The solution is likely okay. You might want to re-run the modelfrom 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 wasreached (Mx status BLUE). You might want to rerun:m1 = mxRun(m1) or increase theiteration limit (seemxOption).The optimizer took all the steps it could and did not finish. You canincrease the number of steps or get better starting values.

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

• 6,‘nonzero gradient’:The model does not satisfy the first-order optimality conditions tothe required accuracy, and no improved point for the merit functioncould 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, seemxTryHard.

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

• 9,‘internal error’: An input parameter was invalid. Themost likely cause is a bug in the code. Please report occurrences tothe 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 toplausible values. SeemxAutoStart andmxTryHard.

Usage

as.statusCode(code)

Arguments

See Also

mxBootstrapsummary.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 athttps://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 athttps://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 functiondiag, except that the input argument is alwaystreated 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, callvec2diag.

See Also

vec2diag

Examples

diag2vec(matrix(1:9, nrow=3))#      [,1]# [1,]    1# [2,]    5# [3,]    9diag2vec(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 andieigenval 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. (SeeMod for more info.)eigenvec andieigenvec 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 byeigenvec andieigenvec 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 asexample2 but in wide format instead of tall.

Source

Classic Mx Manual.

References

The OpenMx User's guide can be found athttps://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 asexample1 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 athttps://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 athttps://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 fromfactorScaleExample1 in the scaling of the variables.

Source

Simulated

References

The OpenMx User's guide can be found athttps://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 alwaysdepend on it. Hence, subclasses that implement this method mustignore 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 andfitfunctions are not recomputed if their inputs have not changed.Dependency information is computed prior to handing the model offto 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 thatfree parameter and the transitive closure of all algebras and fitfunctions that depend on that free parameter. Similarly, eachdefinition variable keeps track of all the objects that store thatfree parameter and the transitive closure of all the algebras andfit functions that depend on that free parameter. At eachiteration of the optimization, when the free parameter values areupdated, all of the dependencies of that free parameter are markedas dirty (seeomxFitFunction.repopulateFun). After analgebra or fit function is computed,omxMarkClean() iscalled to to indicate that the algebra or fit function is updated.Similarly, when definition variables are populated in FIML, all ofthe dependencies of the definition variables are marked as dirty.Particularly for FIML, the fact that non-definition-variabledependencies 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"tovalid values formxOptions ‘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 knowwhat they are doing.

Usage

imxCheckMatrices(model)

Arguments

imxCheckVariables

Description

This is an internal function exported for those people who knowwhat 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 knowwhat they are doing.

Usage

imxConDecMatrixSlots(object)

Arguments

imxConstraintRelations

Description

A string vector of valid constraint binary relations.

Usage

imxConstraintRelations

Format

An object of classcharacter of length 3.

imxConvertIdentifier

Description

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

Usage

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

Arguments

imxConvertLabel

Description

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

Usage

imxConvertLabel(label, modelname, dataname, namespace)

Arguments

imxConvertSubstitution

Description

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

Usage

imxConvertSubstitution(substitution, modelname, namespace)

Arguments

Create a matrix

Description

This is an internal function exported for those people who knowwhat 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 classcharacter of length 4.

imxDefaultGetSlotDisplayNames

Description

Returns a list of display-friendly object slot namesThis is an internal function exported for those people who knowwhat 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 knowwhat 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 knowwhat they are doing.

Usage

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

Arguments

imxExtractMethod

Description

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

Usage

imxExtractMethod(model, index)

Arguments

imxExtractNames

Description

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

Usage

imxExtractNames(lst)

Arguments

imxExtractReferences

Description

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

Usage

imxExtractReferences(lst)

Arguments

imxExtractSlot

Description

Checks for and extracts a slot from the objectThis is an internal function exported for those people who knowwhat 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 knowwhat they are doing.

Usage

imxGenSwift(tc, sites, sfile)

Arguments

imxGenerateLabels

Description

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

Usage

imxGenerateLabels(model)

Arguments

imxGenerateNamespace

Description

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

Usage

imxGenerateNamespace(model)

Arguments

imxGenericModelBuilder

Description

This is an internal function exported for those people who knowwhat 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 knowwhat 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 coresto avoid consuming all the resources on CRAN's test machines during release cycles.

This makes itnot suitable for getting the number of available threads.

To get the number of cores available locally you wantomxDetectCoresor perhaps thedetectCores function in the parallel package.

Usage

imxGetNumThreads()

imxGetSlotDisplayNames

Description

Returns a list of display-friendly object slot namesThis is an internal function exported for those people who knowwhat 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 knowwhat they are doing. This function checks if a model (or any of itssubmodels) either (1) has labels on MxPaths that reference one or moreMxAlgebras, 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 knowwhat they are doing. This function checks if a model (or itssubmodels) has at least one MxConstraint.

Usage

imxHasConstraint(model)

Arguments

imxHasDefinitionVariable

Description

This is an internal function exported for those people who knowwhat they are doing. This function checks if a model (or itssubmodels) 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 andlinked with OpenMx. Otherwise FALSE.

imxHasOpenMP

Description

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

Usage

imxHasOpenMP()

imxHasPenalty

Description

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

Usage

imxHasPenalty(model)

Arguments

imxHasThresholds

Description

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

Usage

imxHasThresholds(model, submodels = TRUE)

Arguments

imxHasWLS

Description

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

Usage

imxHasWLS(model)

Arguments

imxIdentifier

Description

This is an internal function exported for those people who knowwhat 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 knowwhat they are doing.

Usage

imxInitModel(model)

Arguments

imxIsDefinitionVariable

Description

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

Usage

imxIsDefinitionVariable(name)

Arguments

imxIsMultilevel

Description

This is an internal function exported for those people who knowwhat 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. Itreturns 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 knowwhat they are doing.

Usage

imxIsPath(value)

Arguments

imxIsStateSpace

Description

This is an internal function exported for those people who knowwhat 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. Itreturns 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 knowwhat they are doing.

Usage

imxLocateFunction(function_name)

Arguments

imxLocateIndex

Description

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

Usage

imxLocateIndex(model, name, referant)

Arguments

imxLocateLabel

Description

This is an internal function exported for those people who knowwhat 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 diagnosticinformation to standard error. This function should not be calledfrom R. We make it available only for testing.

Usage

imxLog(str)

Arguments

imxLookupSymbolTable

Description

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

Usage

imxLookupSymbolTable(name)

Arguments

imxModelBuilder

Description

This is an internal function exported for those people who knowwhat 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 separatemethods. For example, modelAddVariables and modelRemoveVariablescould be their own methods. This would reduce some cut&pasteduplication.

imxModelTypes

Description

A list of supported model types

Usage

imxModelTypes

Format

An object of classlist of length 3.

imxMpiWrap

Description

This is an internal function exported for those people who knowwhat 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 forall 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 thediagonal of the S matrix, and not as a latent with a loading onlyon 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 knowwhat they are doing.

Usage

imxPenaltyTypes

Format

An object of classcharacter of length 3.

Details

Types of regularization penalties.

imxPreprocessModel

Description

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

Usage

imxPreprocessModel(model)

Arguments

imxReplaceMethod

Description

This is an internal function exported for those people who knowwhat 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 objectThis is an internal function exported for those people who knowwhat 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 anewline.

Usage

imxReportProgress(info, eraseLen)

Arguments

Examples

library(OpenMx)previousLen <<- 0easyReportProcess <- 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 classcharacter of length 7.

imxReverseIdentifier

Description

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

Usage

imxReverseIdentifier(model, name)

Arguments

imxRobustSE

Description

This is an internal function exported for those people who knowwhat 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 Hessianof the likelihood function. This is what is typically used for standarderrors 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).

Whendetails=FALSE, only the standard errors are returned.

Whendetails=TRUE,a list with five named elements is returned. ElementSE is the vector of standard errors that is also returned whendetails=FALSE.Elementcov is the full robust covariance matrix of the parameter estimates; the square root of the diagonal ofcov gives the standard errors. Elementbread is the aforementioned "bread"–the naive (non-robust) covariance matrix of the parameter estimates. Elementmeat is the aforementioned "meat," proportionalto the covariance matrix of the row gradients. ElementTIC 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 handlemultilevel data.

imxRowGradients

Description

This is an internal function exported for those people who knowwhat 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 knowwhat they are doing.

Usage

imxSameType(a, b)

Arguments

imxSeparatorChar

Description

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

Usage

imxSeparatorChar

Format

An object of classcharacter of length 1.

imxSfClient

Description

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

Usage

imxSfClient()

Details

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

imxSimpleRAMPredicate

Description

This is an internal function exported for those people who knowwhat 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 knowwhat they are doing.

Usage

imxSquareMatrix(.Object)

Arguments

imxStanMathMajor

Description

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

Usage

imxStanMathMajor()

imxSymmetricMatrix

Description

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

Usage

imxSymmetricMatrix(.Object)

Arguments

imxTypeName

Description

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

Usage

imxTypeName(model)

Arguments

imxUntitledName

Description

This is an internal function exported for those people who knowwhat 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 knowwhat 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 knowwhat they are doing.

Usage

imxUntitledNumberReset()

Details

Resets theimxUntitledNumber counter

imxUpdateModelValues

Description

Deprecated. This function does not handle parameters with equalityconstraints. Do not use.

Usage

imxUpdateModelValues(model, flatModel, values)

Arguments

imxVariableTypes

Description

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

Usage

imxVariableTypes

Format

An object of classcharacter of length 2.

Details

The acceptable variable types

imxVerifyMatrix

Description

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

Usage

imxVerifyMatrix(.Object)

Arguments

imxVerifyModel

Description

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

Usage

imxVerifyModel(model)

Arguments

imxVerifyName

Description

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

Usage

imxVerifyName(name, stackNumber)

Arguments

imxVerifyReference

Description

This is an internal function exported for those people who knowwhat 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. IfJ 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 ofJ,W is the inverse of the full weight matrix, ande 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

withe' indicating the transpose ofe. 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. IfJ 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, andU= V J (J' V J)^{-1}, then the asymptotic covariance matrix of the free parameters is

Acov(\theta) = U' W U

withU' indicating the transpose ofU.

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 athttps://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 athttps://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 tolatentMultipleRegExample1.

Source

Simulated.

References

The OpenMx User's guide can be found athttps://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 athttps://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 athttps://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 newMxAlgebra. The common use is to compute a value in a model: for instance astandardized value of a parameter, or a parameter which is a function of other values. It is also used inmodels with anmxFitFunctionAlgebra objective function.

note: Unless needed in the model objective, algebras are only computed twice: once at thebeginning 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 moreMxMatrix objects. To evaluate anMxAlgebra object,it must be placed in anMxModel object, along with all referencedMxMatrixobjects and themxFitFunctionAlgebra function.ThemxFitFunctionAlgebra function must reference by name theMxAlgebra object to be evaluated.

Note: f the result for anMxAlgebra depends upon one or more "definition variables" (seemxMatrix()),then the value returned after the call tomxRun() will be computed using the values of those definitionvariables 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 todiag)

diag2vec

Extract diagonal from matrix (similar todiag)

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

Evaluatean algebra on an abscissa grid and collect column results

mpinv

Moore-Penrose Inverse

Ifsolve is used on an uninvertible square matrix in R, viamxEval(), it will fail with an error will; ifsolve is used on an uninvertible square matrix duringruntime, it will fail silently.

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

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 theirR 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 ofFALSE, and non-zero numerical values as logical values ofTRUE. 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 thelog,log.p, andlower.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 newMxAlgebra object.

References

The OpenMx User's guide can be found athttps://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 andmxMatrix for objects which may be entered in theexpression argument and the function that creates them. More information about the OpenMx package may be foundhere.

Examples

A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")# Simple example: algebra B simply evaluates to the matrix AB <- mxAlgebra(A, name = "B")# Compute A + BC <- 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']]$resultA$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 usingmxFitFunctionAlgebra 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, themxAlgebraObjective function uses the referencedMxAlgebra orMxMatrix object as the function to be minimized.

If a model's primary objective function is amxAlgebraObjective 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 aMxModel object: aMxAlgebraObjective,MxAlgebra andMxMatrix entities referenced by theMxAlgebraObjective, and optionalMxBounds andMxConstraint entities. This model may then be evaluated using themxRun function. The results of the optimization may be obtained using themxEval function on the name of theMxAlgebra, 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 referencedMxAlgebra andMxMatrix objects.

References

The OpenMx User's guide can be found athttps://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 foundhere.

Examples

# Create and fit a very simple model that adds two numbers using mxFitFunctionAlgebralibrary(OpenMx)# Create a matrix 'A' with no free parametersA <- mxMatrix('Full', nrow = 1, ncol = 1, values = 1, name = 'A')# Create an algebra 'B', which defines the expression A + AB <- 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 modeltmpModel <- mxModel(model="Addition", A, B, objective)# Evalulate the algebratmpModelOut <- mxRun(tmpModel)# View the resultstmpModelOut$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; it only works well for GREML models under certain circumstances (see further below).

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 thetype 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 usetype='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 ifmodel contains aGREML expectation, argumenttype is ignored, and the function always uses a form of ULS. The function can be very helpful for finding good starting values for GREML MxModels that use an "implicit" (i.e., "specified in terms of covariates viamxExpectationGREML() argumentXvars") model for the phenotypic mean. In contrast, the function is not generally recommended for GREML MxModels that use an "explicit" (i.e., "specified in terms of an MxMatrix or MxAlgebra via argumentyhat") model for the phenotypic mean, and indeed, it can be downright counterproductive in such cases.

Value

an MxModel with new free parameter values

Examples

# Use the frontpage model with negative variances to show better# starting valueslibrary(OpenMx)data(demoOneFactor)latents  = c("G") # the latent factormanifests = names(demoOneFactor) # manifest variables to be modeledm1 <- 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 valuesm1s <- 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 theoriginal data with replacement). The model is re-fitted to this newsample. This process is repeated many times. This yields a series of estimatesfrom these replications which can be used to assess the variability of the parameters.

note:mxBootstrap only bootstraps free model parameters:

To bootstrap algebras, seemxBootstrapEval

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

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 resampledindependently. If resampling is desired from only some ofthe datasets then the models containing them can be listed in the‘data’ parameter.

Thefrequency column in themxData object is usedrepresent a resampled dataset. When resampling, the original rowproportions, as given by the originalfrequency column, arerespected.

When the model has a default compute plan and ‘checkHess’ iskept at FALSE then the Hessian will not be approximated or checked.On the other hand, ‘checkHess’ is TRUE then the Hessian will beapproximated by finite differences. This procedure is of some valuebecause it can be informative to check whether the Hessian is positivedefinite (seemxComputeHessianQuality). However,approximating the Hessian is often costly in terms of CPU time. Forbootstrapping, the parameter estimates derived from the resampled dataare typically of primary interest.

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

mxBootstrap does not currently offer special support for nested,multilevel, or other dependent data structures.mxBootstrapassumes rows of data are independent. Multilevel models and state spacemodels violate the independence assumption employed bymxBootstrap.By default theunsafe argument prevents multilevel and state spacemodels from usingmxBootstrap; however, settingunsafe=TRUEallows multilevel and state space models to use bootstrapping under the –perhaps foolish – assumption that the user is sufficiently knowledgeable tointerpret the results.

Value

The given model is returned withthe compute plan modified to consist ofmxComputeBootstrap. Results of the bootstrap replications arestored inside the compute plan.mxSummary can be used toobtain 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 10summary(boot)# Looks good, now do the restboot <- mxBootstrap(boot)summary(boot)# examine replication 3boot3 <- 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 aMxModel object, or labels from aMxMatrix 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).

ThemxEvalByName function is a wrapper aroundmxEval 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 andomxBootstrapEvalByName return the raw matrix ofcvectorize'd results.omxBootstrapEvalCov returns thecovariance matrix of thecvectorize'd results.mxBootstrapEval andmxBootstrapEvalByName returnthecvectorize'd results summarized bymethod at quantilesbq.

References

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

See Also

mxAlgebra to create algebraic expressions inside your model andmxModel for the model object mxEval looks inside whenevaluating.mxBootstrap to create bootstrap data.

Examples

library(OpenMx)# make a unit-weighted 10-row data set of values 1 thru 10myData = 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 numbermxAlgebra(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= 1testBoot = 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 throughmxBootstrap.

Usage

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

Arguments

Details

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

The defaultbq (bootstrap quantiles) of c(.25, .75) correspond to a 50% CI. This default is chosen as many morebootstraps are required to accurately estimate more extreme quantiles. For a 95% CI, usebq=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 theA andS RAM matrices) may vary among bootstrap replications. This precludes a simple summary of the standardized paths' bootstrapping results. In this rare case, ifreturnRaw=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

IfreturnRaw=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. IfreturnRaw=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 CFAm1 = mxModel("CFA", type="RAM", manifestVars=manifests, latentVars="F1",# Factor loadingsmxPath("F1", to = manifests, values=1),# Means and variances of F1 and manifestsmxPath(from="F1", arrows=2, free=FALSE, values=1), # fix var  F1 @1mxPath("one", to= "F1", free= FALSE, values = 0),  # fix mean F1 @0# Freely-estimate means and residual variances of manifestsmxPath(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 newMxBounds 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 anMxMatrix object. Parameters may be referenced either by name or by referring to their position in the 'spec' matrix of anMxMatrix object.

Minima and maxima may be specified as scalar numeric values.

Value

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

References

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

See Also

MxBounds for the S4 class created by mxBounds.MxMatrix andmxMatrix for free parameter specification. More information about the OpenMx package may be foundhere.

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 parametersvarianceBounds <- mxBounds(c('Var1', 'Var2', 'Var3'), 0)

Create mxCI Object

Description

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

Usage

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

Arguments

Details

The mxCI function createsMxCI objects, which can be used as arguments inMxModel objects. When models containingMxCI objects are optimized usingmxRun with the ‘intervals’ argument set to TRUE, likelihood-based confidence intervals are returned. The likelihood-based confidence intervals calculated byMxCI 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 anMxCI object be included in the model and that the ‘intervals’ argument of themxRun function is set to TRUE. When estimated, confidence intervals can be accessed in the model output at$output$confidenceIntervals or by usingsummary on a fittedMxModel object.

In all cases, a two-sided hypothesis test is assumed.Therefore, the upper bound willexclude 2.5% (for interval=0.95) even though only one bound isrequested. 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 analgebra) constrained by a lower bound or an upper bound (but not both)andboundAdj=TRUE then the Wu & Neale (2012) correction is used.This improves the accuracy of the confidence interval when the parameteris estimated close to the bound. For example, this correction will beactivated when a variance with a lower bound of10^{-6} and noupper bound that is estimated close to the bound. The sample size, ormore precisely effective sample size for that particular parameter, willdetermine how close the variance needs to be to the bound at10^{-6} to activate the correction.

The likelihood-based confidence intervals returned usingMxCI 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 outputMxCI 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 andMxAlgebras may be listed in the ‘reference’ argument. Individual elements ofMxMatrices andMxAlgebras may be listed as well, using the syntax “matrix[row,col]” (seeExtract for more information). Only scalar numeric values for the ‘interval’ argument are supported. Users requesting different confidence ranges for different parameters must use separatemxCI statements.MxModel objects can hold multipleMxCI 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 formxSummary

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 theMxCI object (you can choose which of these to set via the type parameter of mxCI).

Value

Returns a newMxCI object. If used as an argument in anMxModel object, the parameters,MxMatrices andMxAlgebras listed in the 'reference' argument must also be included prior to optimization.

References

The OpenMx User's guide can be found athttps://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 basedconfidence intervals in genetic models.Behavior Genetics,27(2), 113-120.

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

Wu, H. & Neale, M. C. (2012). Adjusted confidence intervals for abounded 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 andmxMatrix for free parameter specification.MxCI for the S4 class created by mxCI.More information about the OpenMx package may be foundhere.

Examples

library(OpenMx)# generate datacovariance <- 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 matrixexpect <- 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 modelmodel <- 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 intervalsprint(summary(results)$CI)# view all resultssummary(results)# remove a specific mxCI from a modelmodel <- mxModel(model, remove=TRUE, model$intervals[['cov12']])model$intervals# remove all mxCI from a modelmodel <- 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. May give inaccurate results withGREML expectations (see "Details" below).

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 ornonlinear equality and inequality constraints. When there areconstraints, mxCheckIdentification uses the Jacobian of the summarystatistics with respect to the free parameters and the Jacobian of thesummary statistics with respect to the constraints. The combinedextended Jacobian must have rank equal to the number of free parametersfor the model to be identified. So, a model can be identified withconstraints that is not identified without constraints.

Model identification should also be accurate for multiple group modelsand 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; thesingle set of free parameters go across the columns of the Jacobian. Inthe case of definition variables, a new set of summary statistics iscomputed for each unique set of definition variable values; thuscreating a kind of pseudo-multiple group model for each set of uniquedefinition variable values.

For models using definition variables, the additional arguments 'nrows'and 'exhaustive' provide instruction for how to search foridentification. In principle, full model identification for models withdefinition variables requires evaluating the Jacobian of the mappingbetween the free parameters and the summary statisticsfor everyunique combination of definition variable values. This evaluationcan take a long time. However, in practice, the vast majority of modelsare 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 definitionvariable rows, but will stop once the model is identified. To keepevaluating unique definition variable values until the model isidentified or you run out of rows, setnrows=Inf. To evaluateall unique definition variable values, setnrows=Inf andexhaustive=TRUE.

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

For most models with aGREML expectation, the function will run slowly, and use ofdetail=TRUE is therefore not recommended. Additionally, for GREMLMxModels that use an "implicit" (i.e., "specified in terms of covariates viamxExpectationGREML() argumentXvars") model for the phenotypic mean, there are forms of unidentification that the function cannot (yet) detect, and it therefore may give false-positive reports of local identification.

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 freemodel2n <- 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 moremxModels 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 bymxCompare, 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.

ThemxCompare function makes an effort to only make valid comparisons.If a comparison is made where thecomparison model has ahigher minus 2 log likelihood (-2LL) than thebase model, then thedifference in their -2LLs will be negative. P-values for likelihoodratio tests will not be reported when either the -2LL or degrees offreedom for the comparison are negative. To ensure that the differences between models are positive and yield p-values for likelihood ratiotests, models listed in the ‘base’ argument mustbe more saturated (i.e., more estimated parameters and fewer degrees offreedom) than models listed in the ‘comparison’ argument. FormxCompareMatrix 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 theminus2LL 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 thediffLL 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, theSB 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 whichboth ‘diffLL’ and ‘diffdf’ are non-negative. However, thisp-value is based on the assumptions of the likelihood ratio test,specifically that the two models being compared are nested. Thelikelihood ratio test and associated p-values are not valid when thecomparison model is not nested in the referenced base model. For a moreaccurate p-value, the empirical bootstrap distribution can be computed(‘boot=TRUE’). However, ‘replications’ must be set highenough for an accurate approximation. The Monte Carlo SE of a proportionfor B replications is\sqrt(p*(1-p)/B), but this will be zero if pis zero, which is nonsense. Note that a parametric-bootstrap p-value ofzero must be interpreted asp < 1/B, which, depending onBand 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 beapproximated or checked. On the other hand, ‘checkHess’ is TRUEthen the Hessian will be approximated by finite differences. Thisprocedure is of some value because it can be informative to checkwhether the Hessian is positive definite (seemxComputeHessianQuality). However, approximating theHessian is often costly in terms of CPU time. For bootstrapping, theparameter estimates derived from the resampled data are typically ofprimary interest.

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

Value

Returns a newMxCompare object. If you want something more like a table of results, useas.data.frame() on the returnedMxCompare 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 performresampling 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 singlereplication attempt.

Value

Output is stored in the compute object'soutputslot. Specifically,model$compute$output$raw contains a dataframe with parameters in columns and replications in rows. In additionto parameters, theseed,fit, andstatusCodeof the replication is also included.

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

See Also

mxBootstrap,as.statusCode

Log parameters and state to disk or memory

Description

Captures the current state of the backend. Whenpath is set, thestate is written to disk in a single row. WhentoReturn is set,the state is recorded in memory and returned aftermxRun.

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 optimizationproblems required to estimate confidence intervals. Most accuratesolutions are achieved when the problem is posed using non-linearconstraints. However, the available optimizers (CSOLNP, SLSQP, and NPSOL) often have difficulty with non-linearconstraints.

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 basedconfidence 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 abounded 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, useomxDefaultComputePlan.

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 aninitial parameter vector. Predict the missing data to form acompleted data model. Optimize the completed data model to obtaina new parameter vector. Repeat these steps until convergencecriteria 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 stylemxComputeEM(e,p,mstep=m) is equivalent to the new stylemxComputeEM(estep=mxComputeOnce(e,p), mstep=m). This changeallows the API to more closely match the literature on the E-Mmethod. You might usemxAlgebra(..., recompute='onDemand') tocontain the results of the E-step and then cause this algebra tobe recomputed usingmxComputeOnce.

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

The EM algorithm does not produce a parameter covariance matrixfor standard errors. The Oakes (1999) direct method and S-EM, animplementation 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-informationitem factor analysis.Applied Psychological Measurement,6(4), 431-444.

Dempster, A. P., Laird, N. M., & Rubin, D. B. (1977). Maximum likelihood fromincomplete 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-covariancematrices: The SEM algorithm.Journal of the American Statistical Association,86 (416), 899-909.

Oakes, D. (1999). Direct calculation of the information matrix viathe 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 convergentmethods for accelerating the convergence of any EMalgorithm.Scandinavian Journal of Statistics, 35, 335-353.

See Also

MxAlgebra,mxComputeOnce

Examples

library(OpenMx)set.seed(190127)N <- 200x <- 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 optimummmfit <- 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 fitfunction. The fully open-source CRAN version of OpenMx offers 2 choices,CSOLNP and SLSQP (from the NLOPT collection). The OpenMx Team's version ofOpenMx 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 NPSOLuseswarmStart. To customize more options, seemxOption.

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 conditionnumber (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 theHessian. The norm is either the 1- or infinity-norm (both obtainthe 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 samemodel.

When expectations are given, the Jacobian is taken with respectto the manifest model.The manifest model excludes any latent variables or processes. ForRAM and LISREL models, the manifest model contains only themanifest 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 norow names. Ifheader=TRUE andcol.names areprovided, thecol.names take precedence. Ifheader=FALSE and nocol.names are provided thenthe column names consist of the file name and column offset.

AnoriginalDataIsIndexOne option is not offered. You'll need toadd an extra line at the start on your file if you wish to makeuse oforiginalDataIsIndexOne inmxComputeLoad*.

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 manysimilar analyses. For example, if we are given a sample of peoplewith a few million SNPs (single-nucleotide polymorphism) perperson then we could fit a separate model for each SNP by iteratingover the SNP data.

The column names given in thecolumn parameter must alreadyexist in the model's MxData object. Pre-existing data is assumed to bea placeholder and is not used unlessoriginalDataIsIndexOne is set to TRUE.

Formethod='csv', the highest performance arrangement isbyrow=TRUE because entire columns are stored in singlechunks (rows) on the disk and can be easily loaded. Forbyrow=FALSE, the data requires transposition. To load asingle column of observed data, it is necessary to read throughthe whole file. This can be slow for large files. To amortize thecost of transposition,cacheSize columns are loaded onevery pass through the file.

AftermxRun returns, thedest mxData object willcontain the most recently loaded data. Hence, any single analysisof a series can be reproduced by issuingmxComputeLoadDatawith the single index associated with a particular dataset,replacing the compute plan with something likeomxDefaultComputePlan, and then passing the model backthroughmxRun. This can be a helpful approach wheninvestigating 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 availablein the mxMatrix. Matrix types (e.g., symmetric or diagonal) arerespected (seemxMatrix). For example, aFull 2x2matrix will require 4 entries, but a diagonal matrix of the same sizewill only require 2 entries.CSV data must be stored space separated and without row or columnnames.The destinationmxMatrix can have free parameters, but cannothave square bracket populated entries.

IforiginalDataIsIndexOne is TRUE then thiscompute step does nothing when the loop index is 1.The purpose oforiginalDataIsIndexOne is topermit usage of the dataset that was initiallyincluded 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 filesCov <- 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

Wheni is given then these values are iteratedover instead of the sequence 1 to the number ofiterations.

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) ofn+1 vertices in the space of the free parameters, wheren is the number of free parameters minus the number of degrees-of-freedom gained from equalityMxConstraints. An iteration of the algorithm first sorts then+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; seeSinger & Nelder (2009) for details.

ArgumentiniSimplexType dictates how the initial simplex will be constructed from the start values if argumentiniSimplexMat isNULL, 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. IfiniSimplexType="regular", the initial simplex is merely a regular simplex with edge length equal toiniSimplexEdge. A"right" simplex is constructed by incrementing each free parameter byiniSimplexEdge 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 incrementedand decremented byiniSimplexEdge, 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 formxTryHard(), 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 thatiniSimplexType is at best asuggestion in the presence of equalityMxConstraints.

Note that if argumentiniSimplexMat 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 ofiniSimplexMat happens to contain those start values).

If the simplex is restarted, a new simplex is constructed per argumentiniSimplexType, 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.

IfgreedyMinimize=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. IfgreedyMinimize=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 argumentaltContraction=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 argumentstagnCtrl 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 argumentstagnCtrl 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 argumentvalidationRestart=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, or2n iterations have elapsed.

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

If argumentdoPseudoHessian=TRUE, there are no equalityMxConstraints, and the "l1p" method (see below) is not in use for inequalityMxConstraints, 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 inequalityMxConstraints reasonably well. Its default method for doing so, with argumentineqConstraintMthd="soft", imposes a "soft" feasibility constraint by assigning a fitfunction value ofbignum to points that violate the constraints by more thanmxOption 'Feasibility tolerance'. Alternately, with argumentineqConstraintMthd="eqMthd", inequalityMxConstraints can be handled by the same method provided to argumenteqConstraintMthd, whether or not equalityMxConstraints are present.

OpenMx's implementation of Nelder-Mead respects equalityMxConstraints, but does not handle them especially well. Its effectiveness at handling equalities may be improved by providing a matrix to argumentiniSimplexMat that ensuresall 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 argumenteqConstraintMthd="GDsearch" (the default), then whenever Nelder-Mead evaluates the fitfunction at an infeasible point, it initiates a subsidiary optimization that usesSLSQP 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 tomxRun(). The effectiveness of the 'GDsearch' method is often improved by settingmxOption 'Feasibility tolerance' to a stricter (smaller) value than the on-load default. The method specified byeqConstraintMthd="soft" is described in the preceding paragraph. If argumenteqConstraintMthd="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 withall 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 argumentbacktrackCtrl, 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 argumentbacktrackCtrl. If argumenteqConstraintMthd="l1p", Nelder-Mead is used as part of anl_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 thefit function. Box constraints are supported. Parameters canapproach box constraints but will not leave the feasible region(even by some small epsilon>0). Non-finite fit values areinterpreted as soft feasibility constraints. That is, when anon-finite fit is encountered, line search is continued after thestep size is multiplied by 10%. Comprehensive diagnostics areavailable 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 whereasmxComputeOnce("expectation", "nothing") may remove theprediction 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, andbackward estimates of the gradient are made available in thiscompute plan's output slot.

WhencheckGradient=TRUE, the central difference estimate ofthe gradient is used to determine whether the first orderconvergence criterion is met. In addition, the forward andbackward difference estimates of the gradient are compared forsymmetry. When sufficient asymmetry is detected, the standarderror is flagged. In the case, profile likelihood confidenceintervals should be used for inference instead of standard errors(seemxComputeConfidenceInterval).

If provided, the square matrixknownHessian should havedimnames set to the names of some subset of the freeparameters. Entries of the matrix set to NA will be estimatednumerically while entries containing finite values will be copiedto 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 canbe much more efficient to compute the inverse Hessian incomparison to computing the Hessian and then inverting it.

Usage

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

Arguments