R: Calculate confidence intervals without re-doing the primary...

omxParallelCI {OpenMx} | R Documentation

## Calculate confidence intervals without re-doing the primary optimization.

### Description

OpenMx provides two functions to calculate confidence intervals for already-run MxModel objects that contain an MxInterval object (i.e., an `mxCI()` statement), without recalculating point estimates, fitfunction derivatives, or expectations.

The primary function is `omxRunCI()`. This is a wrapper for `omxParallelCI()` with arguments `run=TRUE` and `independentSubmodels=FALSE`, and is the recommended interface.

`omxParallelCI()` does the work of calculating confidence intervals. The "parallel" in the function's name refers to the not-yet-implemented feature of running independent submodels in parallel.

### Usage

    omxRunCI(model, verbose = 0, optimizer = "SLSQP")

    omxParallelCI(model, run = TRUE, verbose = 0, independentSubmodels = TRUE,
    optimizer = mxOption(NULL, "Default optimizer"))

### Arguments

`model` | An MxModel object that contains an MxInterval object (i.e., an `mxCI()` statement).
`run` | Logical; For `omxParallelCI()`, determines if the model with its new compute plan is `mxRun()` before being returned. Hard-coded `TRUE` for omxRunCI.
`verbose` | Integer; defaults to zero; verbosity level passed to MxCompute* objects.
`independentSubmodels` | Logical; For `omxParallelCI()` defaults to `TRUE`. Hard coded FALSE for `omxRunCI()`. Also see "Details."
`optimizer` | Character string selecting the gradient-descent optimizer to be used to find confidence limits; one of "NPSOL", "CSOLNP", or "SLSQP". The default for `omxParallelCI()` is the current value of mxOption "Default optimizer", and for `omxRunCI()`, is "SLSQP".

### Details

When `independentSubmodels=TRUE`, `omxParallelCI()` creates an independent MxModel object for each quantity specified in the 'reference' slot of `model`'s MxInterval object, and places these independent MxModels inside `model`. Each of these independent submodels calculates the confidence limits of its own quantity when the container model is run. When `independentSubmodels=FALSE`, no submodels are added to `model`. Instead, `model` is provided with a dedicated compute plan consisting only of an MxComputeConfidenceInterval step. Note that using `independentSubmodels=FALSE` will overwrite any compute plan already inside `model`.

### Value

The functions return `model`, augmented with independent submodels (if `independentSubmodels=TRUE`) or with a non-default compute plan (if `independentSubmodels=FALSE`), and possibly having been passed through `mxRun()` (if `run=TRUE`). Naturally, if `run=FALSE`, the user can subsequently run the returned model to obtain confidence intervals. Users are cautioned that the returned model may not be very amenable to being further modified and re-fitted (e.g., having some free parameters fixed via `omxSetParameters()` and passed through `mxRun()` to get new point estimates) unless the added submodels or the non-default compute plan are eliminated. The exception is if `run=TRUE` and `independentSubmodels=TRUE` (which is always the case with `omxRunCI()`), since the non-default compute plan is set to be non-persistent, and will automatically be replaced with a default compute plan the next time the model is passed to `mxRun()`.

### See Also

`mxCI()`, MxInterval, `mxComputeConfidenceInterval()`

### Examples

    require(OpenMx)
    # 1. Build and run a model, don't compute intervals yet
    data(demoOneFactor)
    manifests <- names(demoOneFactor)
    latents <- c("G")
    factorModel <- 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(observed=cov(demoOneFactor), type="cov", numObs=500),
    	# Add confidence intervals for (free) params in A and S matrices.
    	mxCI(c('A', 'S'))
    )
    factorRun <- mxRun(factorModel)

    # 2. Compute the CIs on factorRun, and view summary
    factorCI1 <- omxRunCI(factorRun)
    summary(factorCI1)$CI

    # 3. Use low-level omxParallelCI interface
    factorCI2 <- omxParallelCI(factorRun)

    # 4. Build, but don't run the newly-created model
    factorCI3 <- omxParallelCI(factorRun, run= FALSE)

[Package OpenMx version 2.17.3 Index]