R: Create MxFitFunctionWLS Object

mxFitFunctionWLS {OpenMx} | R Documentation

## 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 http://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)

[Package OpenMx version 2.19.5 Index]