ci {RMediation}

CI for a nonlinear function of coefficients estimates

Description

This function returns a (1-\alpha)% confidence interval (CI) for a well–defined nonlinear function of the coefficients in single–level and multilevel structural equation models. The ci function uses the Monte Carlo (type="MC") and the asymptotic normal theory (type="asymp") with the multivariate delta standard error (Asymptotic–Delta) method (Sobel, 1982) to compute a CI. In addition, for each of the methods, when a user specifies plot=TRUE and plotCI=TRUE, a plot of the sampling distribution of the quantity of interest in the quant argument and an overlaid plot of the CI will be produced. When type="all" and plot=TRUE, two overlaid plots of the sampling distributions corresponding to each method will be produced; when plotCI=TRUE, then the overlaid plots of the CIs for both methods will be displayed as well.

Usage

ci(
  mu,
  Sigma,
  quant,
  alpha = 0.05,
  type = "MC",
  plot = FALSE,
  plotCI = FALSE,
  n.mc = 1e+06,
  H0 = FALSE,
  mu0 = NULL,
  Sigma0 = NULL,
  ...
)

Arguments

mu

(1) a vector of means (e.g., coefficient estimates) for the normal random variables. A user can assign a name to each mean value, e.g., mu=c(b1=.1,b2=3); otherwise, the coefficient names are assigned automatically as follows: b1,b2,.... Or, (2) a lavaan object.

Sigma

either a covariance matrix or a vector that stacks all the columns of the lower triangle variance–covariance matrix one underneath the other.

quant

quantity of interest, which is a nonlinear/linear function of the model parameters. Argument quant is a formula that must start with the symbol "tilde" (~): e.g., ~b1*b2*b3*b4. The names of coefficients must conform to the names provided in the argument mu or to the default names, i.e., b1,b2,....

alpha

significance level for the CI. The default value is .05.

type

method used to compute a CI. It takes on the values "MC" (default) for Monte Carlo, "asymp" for Asymptotic–Delta, or "all" that produces CIs using both methods.

plot

when TRUE, plot the approximate sampling distribution of the quantity of interest using the specified method(s) in the argument type. The default value is FALSE. When type="all", superimposed density plots generated by both methods are displayed.

plotCI

when TRUE, overlays a CI plot with error bars on the density plot of the sampling distribution of quant. When type="all", the superimposed CI plots generated by both methods are added to the density plots. Note that to obtain a CI plot, one must also specify plot="TRUE". The default value is FALSE.

n.mc

Monte Carlo sample size. The default sample size is 1e+6.

H0

False. If TRUE, it will estimate the sampling distribution of H_{0}:f(\bm b)=0. See the arguments mu0 and Sigma0.

mu0

a vector of means (e.g., coefficient estimates) for the normal random variables that satisfy the null hypothesis H_{0}:f(\bm b)=0. If it is not provided, smallest z value of mu is zet to zero.

Sigma0

either a covariance matrix or a vector that stacks all the columns of the lower triangle variance–covariance matrix one underneath the other. If it is not provided, then Sigma is used instead.

...

additional arguments.

Value

When type is "MC" or "asymp", ci returns a list that contains:

(\eqn{1-\alpha})% CI

a vector of lower and upper confidence limits,

Estimate

a point estimate of the quantity of interest,

SE

standard error of the quantity of interest,

MC Error

When type="MC", error of the Monte Carlo estimate.

When type="all", ci returns a list of two objects, each of which a list that contains the results produced by each method as described above.

Note

A shiny web application for Monte Carlo method of this function is available at https://amplab.shinyapps.io/MEDMC/

Author(s)

Davood Tofighi [e-mail]

References

Tofighi, D. and MacKinnon, D. P. (2011). RMediation: An R package for mediation analysis confidence intervals. Behavior Research Methods, 43, 692–700. doi:10.3758/s13428-011-0076-x

See Also

medci RMediation-package

Examples

ci(mu=c(b1=1,b2=.7,b3=.6, b4= .45), Sigma=c(.05,0,0,0,.05,0,0,.03,0,.03),
quant=~b1*b2*b3*b4, type="all", plot=TRUE, plotCI=TRUE)
#An Example of Conservative Null Sampling Distribution
ci(c(b1=.3,b2=.4,b3=.3), c(.01,0,0,.01,0,.02),
quant=~b1*b2*b3, type="mc", plot=TRUE, plotCI=TRUE, H0=TRUE, mu0=c(b1=.3,b2=.4,b3=0)  )
#An Example of Less Conservative Null Sampling Distribution
ci(c(b1=.3,b2=.4,b3=.3), c(.01,0,0,.01,0,.02),
quant=~b1*b2*b3, type="mc", plot=TRUE, plotCI=TRUE, H0=TRUE, mu0=c(b1=0,b2=.4,b3=0.1)  )