ivmediate: Causal Mediation Analysis with Treatment Noncompliance
In mediation: Causal Mediation Analysis

Description Usage Arguments Details Value Author(s) References See Also Examples

'ivmediate' is used to estimate local average causal mediation effects, local average natural direct effects and local average treatment effects for compliers using the method of Yamamoto (2013).

ivmediate(model.t, model.m, model.y, ci = TRUE, sims = 1000,
  boot = TRUE, enc = "enc.name", treat = "treat.name",
  mediator = "med.name", conf.level = 0.95, long = TRUE,
  dropobs = FALSE, multicore = FALSE,
  mc.cores = getOption("mc.cores", 2L))

`model.t`	a fitted model object for actual treatment. Can be of class 'lm' or 'glm'.
`model.m`	a fitted model object for mediator. Can be of class 'lm', or 'glm'.
`model.y`	a fitted model object for outcome. Can be of class 'lm', or 'glm'.
`ci`	a logical value. if 'TRUE' both point estimates and confidence intervals are calculated; if 'FALSE' only point estimates are produced. Default is 'TRUE'.
`sims`	number of Monte Carlo draws for nonparametric bootstrap or quasi-Bayesian approximation.
`boot`	a logical value. if 'FALSE' a quasi-Bayesian approximation is used for confidence intervals; if 'TRUE' nonparametric bootstrap will be used. Default is 'TRUE'.
`enc`	a character string indicating the name of the encouragement variable used in the models. Must be a binary variable.
`treat`	a character string indicating the name of the actual treatment variable used in the models. Must be a binary variable.
`mediator`	a character string indicating the name of the mediator variable used in the models.
`conf.level`	a numeric vector indicating the levels of the returned two-sided confidence intervals. Default is to return the 2.5 and 97.5 percentiles of the simulated quantities.
`long`	a logical value. If 'TRUE', the output will contain the entire sets of simulation draws of the estimated effects. Default is 'TRUE'.
`dropobs`	a logical value indicating the behavior when the model frames of 'model.t', 'model.m' and 'model.y' are composed of different observations. If 'TRUE', models will be re-fitted using common data rows. If 'FALSE', error is returned. Default is 'FALSE'.
`multicore`	a logical value indicating whether to parallelize simulations into multiple cores. Default is 'FALSE'. Note that this option is currently unavailable on Windows.
`mc.cores`	number of cores to be used in the parallelization of bootstrap or Monte Carlo simulations. Default is the value in the 'mc.cores' option (see `mclapply`).

This is the workhorse function for estimating local causal mediation effects for compliers using the approach of Yamamoto (2013).

Although the method is quite general and accommodate various types of mediator and outcome variables, the current function can only handle binary variables (modeled via glm with family=binomial) and continuous variables (modeled via lm). In addition, when the mediator is continuous and its model contains any predictor other than the encouragement and actual treatment, computation of confidence intervals is extremely slow because it requires numerical integration via integrate for each observation in each simulation iteration. Users are advised to use a powerful computer (preferably equipped with multiple CPU cores and a non-Windows operating system) for such calculation, especially if the data contain many rows and/or the desired number of simulations is large.

ivmediate returns an object of class 'ivmediate', a list that contains the components listed below. Some of these elements are not available depending on the values of the 'ci' and 'long' options.

The function summary (i.e., summary.ivmediate) can be used to obtain a table of the results. The function plot (i.e., plot.ivmediate) can be used to produce a plot of the estimated effects along with their confidence intervals.

`dc0, dc1`	point estimates for the local average causal mediation effects under the control and treatment conditions.
`dc0.ci, dc1.ci`	confidence intervals for the local average causal mediation effects. The confidence levels are set at the value specified in 'conf.level'.
`dc0.issue, dc1.issue`	number of observations for which the numerical integration via `integrate` encountered computational problems when calculating dc0 and dc1, respectively.
`dc0.inf, dc1.inf`	number of observations for which the numerical integration produced non-finite values when calculating dc0 and dc1, respectively. (Such values are excluded from the calculation of average effects.)
`dc0.sims, dc1.sims`	vectors of length 'sims' containing simulation draws of local average causal mediation effects.
`zc0, zc1`	point estimates for the local average natural direct effects under the control and treatment conditions.
`zc0.ci, zc1.ci`	confidence intervals for the local average natural direct effects.
`zc0.issue, zc1.issue`	number of observations for which the numerical integration encountered computational problems when calculating zc0 and zc1, respectively.
`zc0.inf, zc1.inf`	number of observations for which the numerical integration produced non-finite values for zc0 and zc1.
`zc0.sims, zc1.sims`	vectors of length 'sims' containing simulation draws of local average natural direct effects.
`tauc`	point estimate for the local average treatment effect.
`tauc.ci`	confidence interval for the local average treatment effect.
`tauc.sims`	a vector of length 'sims' containing simulation draws of the local average treatment effect.
`boot`	logical, the 'boot' argument used.
`enc`	a character string indicating the name of the 'enc' variable used.
`treat`	a character string indicating the name of the 'treat' variable used.
`mediator`	a character string indicating the name of the 'mediator' variable used.
`conf.level`	the confidence levels used.
`nobs`	number of observations in the model frame for 'model.t', 'model.m' and 'model.y'. May differ from the numbers in the original models input to 'ivmediate' if 'dropobs' was 'TRUE'.
`sims`	number of simulation draws used.

Teppei Yamamoto, Massachusetts Institute of Technology, teppei@mit.edu.

Tingley, D., Yamamoto, T., Hirose, K., Imai, K. and Keele, L. (2014). "mediation: R package for Causal Mediation Analysis", Journal of Statistical Software, Vol. 59, No. 5, pp. 1-38.

Yamamoto, T. (2013). Identification and Estimation of Causal Mediation Effects with Treatment Noncompliance. Unpublished manuscript.

plot.ivmediate, summary.ivmediate

# Examples with JOBS II Field Experiment

# ** For illustration purposes a small number of simulations are used **

require(parallel)
require(MASS)

data(jobs)

a <- lm(comply ~ treat + sex + age + marital + nonwhite + educ + income, 
        data = jobs)
b <- glm(job_dich ~ comply + treat + sex + age + marital + nonwhite + educ + income, 
        data = jobs, family = binomial)
c <- lm(depress2 ~ job_dich * (comply + treat) + sex + age + marital + nonwhite + educ + income, 
        data = jobs)

out <- ivmediate(a, b, c, sims = 50, boot = FALSE, 
                 enc = "treat", treat = "comply", mediator = "job_dich")
                 
summary(out)
plot(out)

# Using non-parametric bootstrap
out.boot <- ivmediate(a, b, c, sims = 50, boot = TRUE, 
                 enc = "treat", treat = "comply", mediator = "job_dich")
                 
summary(out.boot)
plot(out.boot)