omxParallelCI: 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"))

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

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.

Examples

Run this code

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)