OpenMx (version 2.3.1)

mxCI: Create mxCI Object

Description

This function creates a new MxCI object, which are used to estimate likelihood-based confidence intervals.

Usage

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

Arguments

reference

A character vector of free parameters, mxMatrices, mxMatrix elements and mxAlgebras on which confidence intervals are to be estimated, listed by name.

interval

A scalar numeric value indicating the confidence interval to be estimated. Must be between 0 and 1. Defaults to 0.95.

type

A character string indicating whether the upper, lower or both confidence limits are returned. Defaults to "both".

Value

• Returns a new MxCI object. If used as an argument in an MxModel object, the parameters, MxMatrices and MxAlgebras listed in the 'reference' argument must also be included prior to optimization.

Details

The mxCI function creates MxCI objects, which can be used as arguments in MxModel objects. When models containing MxCI objects are optimized using mxRun with the intervals argument set to TRUE, likelihood-based confidence intervals are returned. The likelihood-based confidence intervals calculated by MxCI 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 an MxCI object be included in the model and that the intervals argument of the mxRun function is set to TRUE. When estimated, confidence intervals can be accessed in the model output at $output$confidenceIntervals or by using summary on a fitted MxModel object.

A typical use case is when a parameter estimate is obtained that is at or near a lower bound. In this case, there is no point in computing the lower part of the CI. Only the upper bound is needed. In all cases, a two-sided hypothesis test is assumed. Therefore, the upper bound will exclude 2.5% (for interval=0.95) even though only one bound is requested. To obtain a one-sided CI for a one-sided hypothesis test, interval=0.90 will obtain a 95% confidence interval.

The likelihood-based confidence intervals returned using MxCI 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 output MxCI 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 and MxAlgebras may be listed in the reference argument. Individual elements of MxMatrices and MxAlgebras may be listed as well, using the syntax matrix[row,col] (see Extract for more information). Only scalar numeric values for the interval argument are supported. Users requesting different confidence ranges for different parameters must use separate mxCI statements. MxModel objects can hold multiple MxCI 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 for mxSummary

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

References

The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation. Additional support for mxCI() can be found on the OpenMx wiki at http://openmx.psyc.virginia.edu/wiki.

See Also

MxCI for the S4 class created by mxCI. mxComputeConfidenceInterval is the internal compute plan that implements the algorithm. MxMatrix and mxMatrix for free parameter specification. More information about the OpenMx package may be found here.

Examples

library(OpenMx)

# generate data
covariance <- 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 matrix
expect <- 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 model
model <- mxModel(model="Confidence Interval Example",
    data, expect, ci,
    mxMLObjective("expectedCov", dimnames=c("a", "b")))

# run the model 
results <- mxRun(model, intervals=TRUE)

# view confidence intervals
print(summary(results)$CI)

# view all results
summary(results)