semTools (version 0.5-6)

monteCarloCI: Monte Carlo Confidence Intervals to Test Functions of Parameter Estimates

Description

Robust confidence intervals for functions of parameter estimates, based on empirical sampling distributions of estimated model parameters.

Usage

monteCarloCI(object = NULL, expr, coefs, ACM, nRep = 20000,
  standardized = FALSE, fast = TRUE, level = 0.95, na.rm = TRUE,
  append.samples = FALSE, plot = FALSE,
  ask = getOption("device.ask.default"), ...)

Arguments

object

A object of class '>lavaan in which functions of parameters have already been defined using the := operator in lavaan's model.syntax. When NULL, users must specify expr, coefs, and ACM.

expr

Optional character vector specifying functions of model parameters (e.g., an indirect effect). Ideally, the vector should have names, which is necessary if any user-defined parameters refer to other user-defined parameters defined earlier in the vector (order matters!). All parameters appearing in the vector must be provided in coefs, or defined (as functions of coefs) earlier in expr. If length(expr) > 1L, nRep samples will be drawn simultaneously from a single multivariate distribution; thus, ACM must include all parameters in coefs.

coefs

numeric vector of parameter estimates used in expr. Ignored when object is used.

ACM

Symmetric matrix representing the asymptotic sampling covariance matrix (ACOV) of the parameter estimates in coefs. Ignored when object is used. Information on how to obtain the ACOV in popular SEM software is described in Details.

nRep

integer. The number of samples to draw, to obtain an empirical sampling distribution of model parameters. Many thousand are recommended to minimize Monte Carlo error of the estimated CIs.

standardized

logical indicating whether to obtain CIs for the fully standardized ("std.all") estimates, using their asymptotic sampling covariance matrix. Only valid when object is of class '>lavaan, not '>lavaan.mi.

fast

logical indicating whether to use a fast algorithm that assumes all functions of parameters (in object or expr) use standard operations. Set to FALSE if using (e.g.) c() to concatenate parameters in the definition, which would have unintended consequences when vectorizing functions in expr across sampled parameters.

level

numeric confidence level, between 0--1

na.rm

logical passed to quantile

append.samples

logical indicating whether to return the simulated empirical sampling distribution of parameters (in coefs) and functions (in expr) in a list with the results. This could be useful to calculate more precise highest-density intervals (see examples).

plot

logical indicating whether to plot the empirical sampling distribution of each function in expr

ask

whether to prompt user before printing each plot

…

arguments passed to hist when plot = TRUE.

Value

A lavaan.data.frame (to use lavaan's print method) with point estimates and confidence limits of each requested function of parameters in expr is returned. If append.samples = TRUE, output will be a list with the same $Results along with a second data.frame with the $Samples (in rows) of each parameter (in columns), and an additional column for each requested function of those parameters.

Details

This function implements the Monte Carlo method of obtaining an empirical sampling distriution of estimated model parameters, as described by MacKinnon et al. (2004) for testing indirect effects in mediation models. The easiest way to use the function is to fit a SEM to data with lavaan, using the := operator in the model.syntax to specify user-defined parameters. All information is then available in the resulting '>lavaan object. Alternatively (especially when using external SEM software to fit the model), the expression(s) can be explicitly passed to the function, along with the vector of estimated model parameters and their associated asymptotic sampling covariance matrix (ACOV). For further information on the Monte Carlo method, see MacKinnon et al. (2004) and Preacher & Selig (2012).

The asymptotic covariance matrix can be obtained easily from many popular SEM software packages.

• LISREL: Including the EC option on the OU line will print the ACM to a seperate file. The file contains the lower triangular elements of the ACM in free format and scientific notation

• Mplus Include the command TECH3; in the OUTPUT section. The ACM will be printed in the output.

• lavaan: Use the vcov method on the fitted '>lavaan object to return the ACM.

References

MacKinnon, D. P., Lockwood, C. M., & Williams, J. (2004). Confidence limits for the indirect effect: Distribution of the product and resampling methods. Multivariate Behavioral Research, 39(1) 99--128. 10.1207/s15327906mbr3901_4

Preacher, K. J., & Selig, J. P. (2010, July). Monte Carlo method for assessing multilevel mediation: An interactive tool for creating confidence intervals for indirect effects in 1-1-1 multilevel models [Computer software]. Available from http://quantpsy.org/.

Preacher, K. J., & Selig, J. P. (2012). Advantages of Monte Carlo confidence intervals for indirect effects. Communication Methods and Measures, 6(2), 77--98. 10.1080/19312458.2012.679848

Selig, J. P., & Preacher, K. J. (2008, June). Monte Carlo method for assessing mediation: An interactive tool for creating confidence intervals for indirect effects [Computer software]. Available from http://quantpsy.org/.

Examples

# NOT RUN {
## From the mediation tutorial:
## http://lavaan.ugent.be/tutorial/mediation.html

set.seed(1234)
X <- rnorm(100)
M <- 0.5*X + rnorm(100)
Y <- 0.7*M + rnorm(100)
dat <- data.frame(X = X, Y = Y, M = M)
mod <- ' # direct effect
Y ~ c*X
# mediator
M ~ a*X
Y ~ b*M
# indirect effect (a*b)
ind := a*b
# total effect
total := ind + c
'
fit <- sem(mod, data = dat)
summary(fit, ci = TRUE) # print delta-method CIs

## Automatically extract information from lavaan object
set.seed(1234)
monteCarloCI(fit) # CIs more robust than delta method in smaller samples

## save samples to calculate more precise intervals:
# }
# NOT RUN {
set.seed(1234)
foo <- monteCarloCI(fit, append.samples = TRUE)
library(HDInterval)
hdi(fit$Samples)
# }
# NOT RUN {
## Parameters can also be obtained from an external analysis
myParams <- c("a","b","c")
(coefs <- coef(fit)[myParams]) # names must match those in the "expression"
## Asymptotic covariance matrix from an external analysis
(AsyCovMat <- vcov(fit)[myParams, myParams])
## Compute CI, include a plot
set.seed(1234)
monteCarloCI(expr = c(ind = 'a*b', total = 'ind + c',
                      ## other arbitrary functions are also possible
                      meaningless = 'sqrt(a)^b / log(abs(c))'),
             coefs = coefs, ACM = AsyCovMat,
             plot = TRUE, ask = TRUE) # print a plot for each

# }