mxFitFunctionWLS {OpenMx}

Create MxFitFunctionWLS Object

Description

This function creates a new MxFitFunctionWLS object.

Usage

mxFitFunctionWLS(type=c('WLS','DWLS','ULS'),
			     allContinuousMethod=c("cumulants", "marginals"),
			     fullWeight=TRUE)

Arguments

type

A character string 'WLS' (default), 'DWLS', or 'ULS' for weighted, diagonally weighted, or unweighted least squares, respectively

allContinuousMethod

A character string 'cumulants' (default) or 'marginals'. See Details.

fullWeight

Logical determining if the full weight matrix is returned (default). Needed for standard error and quasi-chi-squared calculation.

Details

As with other fit functions, mxFitFunctionWLS optimizes free parameter values such that the value of a cost function is minimized. For mxFitFunctionWLS, this cost function is the weighted least squares difference between the data and the model-implied expectations for the data based on the free parameters and the expectation function (e.g., mxExpectationNormal or mxExpectationRAM) selected for the model.

Bias and sensitivity to model misspecification Both ordinal and continuous data are supported, as well as combinations of these data types. All three methods ('WLS', 'ULS' and 'DWLS') are unbiased when the model is correct. Full 'WLS' is highly sensitive to model misspecification – it can heavily weight the fourth-order moments of the distribution, so small deviations between the observed fourth-order moments and those implied by the model can lead to poor estimates.

Behavior with all-continuous data When only continuous variables are present, the argument allContinuousMethod dictates how to process the data.

The default, cumulants is a good choice for non-normal data. This uses the asymptotically distribution free (ADF) method of Browne (1984) and computes the fourth order cumulants for the weight matrix: thus, the name. It is generally fast and ADF up to elliptical distributions. Data computed using cumulants should also be more accurate than via marginals (because the whole covariance is a single analytic expression, with no estimation involved).

note: The cumulants method does not handle missing data. It also does not return weights or summary statistics for the means.

The alternative option, 'marginals', uses methods similar to those used in processing ordinal and joint ordinal-continuous data. By contrast with cumulants, marginals returns weights and summary statistics for the means.

When data are not all continuous, allContinuousMethod is ignored, and means are modelled.

Usage Notes:

Model results can be reported using the summary function, or accessed directly in the 'output' slot of the model (i.e., model$output). Components of the output may also be accessed and used in the same way, i.e., via the $ and [] Extract functions.

Summary statistics are returned in the MxData object in an observedStats list. If observedStats are already present and in the appropriate shape then they are reused. It is also possible to provide your own arbitrary user supplied observed statistics using this same approach.

Value

Returns a new MxFitFunctionWLS object. One and only one fit function object should be included in each model, along with an associated mxExpectationNormal or mxExpectationRAM object.

References

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

Browne, M. W. (1984). Asymptotically distribution-free methods for the analysis of covariance structures. British Journal of Mathematical and Statistical Psychology, 37, 62-83.

See Also

Other fit functions: mxFitFunctionMultigroup, mxFitFunctionML, mxFitFunctionAlgebra, mxFitFunctionGREML, mxFitFunctionR, mxFitFunctionRow

More information about the OpenMx package may be found here.

Examples

# Create and fit a WLS model using RAM, and then using matrices.

library(OpenMx)

# Simulate some data where y = .5x + error

x = rnorm(1000, mean = 0, sd = 1)
y = 0.5*x + rnorm(1000, mean = 0, sd = 1)
tmpFrame = data.frame(x, y)
varNames = names(tmpFrame)

# =======================
# = A RAM model example =
# =======================

m1 = mxModel("my_first_WLS", type = "RAM",
	manifestVars = c("x", "y"),
	mxPath(c("x", "y"), arrows = 2, values = 1, labels = c("xVar", "yVar")),
	mxPath("x", to = "y", labels = "x_to_y"),
	mxFitFunctionWLS(),
	mxData(tmpFrame, 'raw')
)

m1 = mxRun(m1)
summary(m1)$parameters

# Here are the cov, acov and Weight matrices:
print(m1$data$observedStats)

# Use a different weight matrix
m2 = m1
os <- m1$data$observedStats
os$asymCov <- solve(rWishart(n=1, df= nrow(tmpFrame), Sigma= diag(3))[,,1])
os$useWeight <- solve(os$asymCov * nrow(tmpFrame))
m2$data$observedStats <- os

# Set verbose to check if our new weights are used
m2$data$verbose <- 1L

# Run model
m2 <- mxRun(m2)

# SE indeed changed due to new weights
print(m2$output$standardErrors - m1$output$standardErrors)

# ==========================
# = A matrix-based example =
# ==========================

# Define matrices for Symmetric (S) and Asymmetric (A) paths and an Identity matrix.

S <- mxMatrix(type = "Full", nrow = 2, ncol = 2, values=c(1,0,0,1),
              free=c(TRUE,FALSE,FALSE,TRUE), labels=c("Vx", NA, NA, "Vy"), name = "S")
A <- mxMatrix(type = "Full", nrow = 2, ncol = 2, values=c(0,1,0,0),
              free=c(FALSE,TRUE,FALSE,FALSE), labels=c(NA, "b", NA, NA), name = "A")
I <- mxMatrix(type="Iden", nrow=2, ncol=2, name="I")

# Build the model

tmpModel <- mxModel(model="exampleModel",
	# Add the S, A, and I matrices constructed above
	S, A, I,

	# Define the expectation
	mxAlgebra(name="expCov", solve(I-A) %*% S %*% t(solve(I-A))),

	# Choose a normal expectation and WLS as the fit function
	mxExpectationNormal(covariance= "expCov", dimnames= varNames),
	mxFitFunctionWLS(),

   # Add the data
	mxData(tmpFrame, 'raw')
)

# Fit the model and print a summary
tmpModel <- mxRun(tmpModel)
summary(tmpModel)