Merge 1945ae1 into 8e66656

R/mediation_analysis_designer.R

@@ -1,10 +1,6 @@
 #' Create a design for mediation analysis
 #'
-#' Description here
-#' 
-#' Key limitations: Limitations here.
-#' 
-#' Note: Note here.
+#' A mediation analysis design where we are interested in the effect of treatment (Z) on mediator (M) and the effect of mediator (M) on outcome (Y) as well as direct effect of treatment (Z) on outcome (Y).
 #'
 #' @param N Size of sample
 #' @param a Effect of treatment (Z) on mediatior (M)
@@ -41,6 +37,8 @@ mediation_analysis_designer <- function(N = 100,
     pos_Y <-
       declare_potential_outcomes(Y ~ d * Z + b * M + e2)
     assignment <- declare_assignment(prob = 0.5)
+    reveal_mediator <- declare_reveal(M, Z)
+    reveal_outcome <- declare_reveal(Y, Z) 
     mand_a <- declare_estimand(a = a)
     mand_b <- declare_estimand(b = b)
     mand_d <- declare_estimand(d = d)
@@ -59,17 +57,17 @@ mediation_analysis_designer <- function(N = 100,
       label = "Outcome regression"
     )
     mediation_analysis_design <-
-        population +
-        pos_M +
-        assignment +
-        declare_reveal(M, Z) +
-        pos_Y +
-        mand_a +
-        mand_b +
-        mand_d +
-        declare_reveal(Y, Z) +
-        mediator_regression +
-        outcome_regression
+      population +
+      pos_M +
+      assignment +
+      reveal_mediator +
+      pos_Y +
+      mand_a +
+      mand_b +
+      mand_d +
+      reveal_outcome +
+      mediator_regression +
+      outcome_regression
   }}}
   attr(mediation_analysis_design, "code") <- 
     construct_design_code(mediation_analysis_designer, match.call.defaults())

vignettes/bib.bib

@@ -1533,4 +1533,16 @@ @incollection{bennett2010process
   Pages = {207--20},
   Publisher = {Lanham, MD: Rowman \& Littlefield},
   Title = {Process tracing and causal inference},
-  Year = {2010}}
+  Year = {2010}}
+
+
+@article{imai2011,
+  Author = {Imai, Kosuke and Keele, Luke and Tingley, Dustin and Yamamoto, Teppei},
+  Date-Added = {2018-06-26 18:26:24 +0000},
+  Date-Modified = {2018-06-26 18:26:24 +0000},
+  Journal = {American Political Science Review},
+  Number = {4},
+  Pages = {765--789},
+  Title = {Unpacking the Black Box of Causality: Learning about Causal Mechanisms from Experimental and Observational Studies},
+  Volume = {105},
+  Year = {2011}}

vignettes/mediation_analysis.Rmd

@@ -0,0 +1,119 @@
+---
+title: "Mediation Analysis Design"
+output: rmarkdown::html_vignette
+bibliography: bib.bib
+nocite: |
+  @Gerber2012
+  @imai2011
+designer: "mediation_analysis_designer.Rd"
+vignette: >
+  %\VignetteIndexEntry{Mediation Analysis Design}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+library(DesignLibrary)
+library(knitr)
+```
+
+By randomly assigning units to treatment we can determine whether a treatment affects an outcome but not *why* or *how* it might affect it. Identifying causal mechanisms, which is arguably one of the most useful findings in science, requires a treatment with nonzero effects and the specification of one mediator.  
+
+
+For this analysis we assume that the average treatment effect (ATE) of $Z$ on $Y$ is statistically different from zero.  Our main interest lies in decomposing the ATE into *direct* and *indirect effects*.  The indirect effect is channeled from the treatment $Z$ to the outcome $Y$ through a mediator $M$ and the direct effect runs directly from $Z$ to $Y$.
+
+
+Identifyng causal mechanisms is not a simple task. It involves complex potential outcomes (more on this below) and a mediating variable that was not assigned at random  and is not a pre-treatment covariate (it's affected by the treatment!). Researchers often use regression based approaches to identify causal mechanisms but these rely on assumptions that sometimes can't be met.
+
+We define below a mediation analysis design.
+
+### Design Declaration
+
+- **M**odel:  
+We specify a population of size $N$. Individuals from this population have two potential outcomes related to the mediatior.
+
+* $M_i(Z_i=0):$ The value for the mediator $M$ when the unit $i$ is in the control group, and
+* $M_i(Z_i=1):$ the value for the mediator $M$ when the unit $i$ is treated.
+
+Additionally, individuals have four potential outcomes related to $Y$.
+
+Two potential outcomes that can be observed under treatment or control conditions.
+
+  * $Y_i( Z_i=0 , M_i(Z_i=0)):$  the outcome of interest given that the unit  $i$ is in the control group and the mediator that would be observed if the unit $i$ is in the control group, and
+
+* $Y_i( Z_i=1 , M_i(Z_i=1)):$ the outcome of interest given that the unit  $i$ is in the treatment group and the mediator that would be observed when the unit  $i$ is in the control group.
+
+And two complex potential outcomes.
+
+* $Y_i( Z_i=1 , M_i(Z_i=0)):$ the outcome of interest given that unit $i$ is treated and the value of the mediator hat would be observed in the control condition.
+
+* $Y_i( Z_i=0 , M_i(Z_i=1)):$ the outcome of interest given that unit $i$ remains untreated and the value of the mediatorhat would be observed in the treatment condition
+
+
+
+- **I**nquiry: We are interested in the average effects of the treatment on the mediatior $a$, the direct average effects of the treatment on $Y$ and the effects $Z$ that run through $M$.
+
+- **D**ata strategy:  We use assign units to treatment using complete random assigment.
+
+- **A**nswer strategy:  First, we regress $M$ on $Z$. Then we regress $Y$ on $M$ and $Z$. Our estimators are the coefficient of regressors.
+
+In code:
+
+
+```{r, code = get_design_code( mediation_analysis_designer()), eval=TRUE}
+
+```
+
+### Diagnosis
+
+Let us first diagnose this design when the correlation between the error term of the mediator regression and the error term of the outcome regression.
+
+```{r,eval = TRUE}
+diagnosis <- diagnose_design( mediation_analysis_designer(rho = 0.5))
+```
+
+
+```{r,eval = TRUE, echo = FALSE}
+kable(reshape_diagnosis(diagnosis)[, -c(1, 4:6, 13,14)], digits = 2)
+```
+
+Our diagnosis indicates that the regression underestimates the effect of the mediator on $Y$ and overstates the direct effects.
+
+Now, let us see what happens with the bias when the correlation between the error terms is zero.
+
+```{r,eval = TRUE}
+diagnosis <- diagnose_design( mediation_analysis_designer(rho = 0))
+```
+
+```{r,eval = TRUE, echo = FALSE}
+kable(reshape_diagnosis(diagnosis)[, -c(1, 4:6, 13,14)], digits = 2)
+```
+
+We can see that when the error terms of the mediator regression and the outcome regression are not correlated the direct and indirect effects can be estimated without bias. Unfortunately, the assumption of no correlation is not always guaranteed since $M$ is not assigned at random and might be correlated with $Y$.
+
+### Using the Mediation Analysis Designer
+
+In R, you can generate a mediation_analysis design using the template function `mediation_analysis_designer()` in the `DesignLibrary` package by running the following lines, which install and load the package:
+
+```{r, eval=FALSE}
+install.packages("DesignLibrary")
+library(DesignLibrary)
+```
+
+We can then create specific designs by defining values for each argument. For example, we create a design called `my_mediation_analysis_design` with `N`, `a`, `b`, `d` and `rho` set to 500, .2, .4, .2, and .15, respectively, by running the lines below.
+
+```{r, eval=FALSE}
+mediation_analysis_design <- mediation_analysis_designer(
+  N = 500, a = .2, b = .4, d = .2, rho = .15)
+```
+
+You can see more details on the `mediation_analysis_designer()` function and its arguments by running the following line of code:
+
+```{r, eval=FALSE}
+??mediation_analysis_designer
+```
+
+## Further Reading
+
+