---
title: "MAZE: Mediation Analysis for ZEro-inflated mediators"
author:
- Meilin Jiang^[University of Florida, meilin.jiang@ufl.edu]
- Zhigang Li^[University of Florida, zhigang.li@ufl.edu]
# date: "`r format(Sys.time(), '%d %B %Y')`"
date: "February 10, 2023"
output: 
  rmarkdown::html_vignette
  # pdf_document: default
  # html_document:
  #   df_print: paged
vignette: >
  %\VignetteIndexEntry{MAZE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## 1. Introduction

The causal mediation analysis is a statistical technique to investigate and identify relationships in a causal mechanism involving one or more intermediate variables (i.e., mediators) between an independent variable and an outcome. In addition to a better understanding of the causal pathways in proposed theoretical mechanisms, mediation analyses can help to confirm and refine treatments when it is not possible or ethical to intervene the independent variable.

However, challenges arise in mediation analyses in datasets with an excessive number of zero data point for mediators, especially in count data or non-negative measurements. The standard mediation analysis approaches may not be valid due to the violation of distributional assumptions. Moreover, the excessive zero mediator values could contain both true and false zeros. A true zero means that the measurement is truly zero, while a false zero means the measurement is positive but might be too small to be detected given the accuracy of devices used. Therefore, there is an unmet need for mediation analysis approaches to account for the zero-inflated structures of these mediators.

To address the difficulties, we proposed a novel mediation analysis approach to estimate and test direct and indirect effects to handle zero-inflated mediators that are non-negative. The zero-inflated log-normal (ZILoN), zero-inflated negative binomial (ZINB), and zero-inflated Poisson (ZIP) mediators were considered as the possible options of distributions for these mediators. 

The R package `MAZE` implements the proposed causal mediation analysis approach for zero-inflated mediators to estimate and test natural indirect effect (NIE), natural direct effect (NDE), and controlled direct effect (CDE). Given the zero-inflated nature, the mediation effect (i.e., NIE) can be decomposed into two components NIE$_1$ and NIE$_2$.

## 2. Model
For simplicity, the subject index is suppressed, and confounders are not included in the equations, but they have been incorporated into `MAZE`.

For an independent variable $X$, a zero-inflated mediator $M$ and a continuous outcome variable $Y$, the following regression equation is used to model the association between $Y$ and $(X,M)$:
\begin{align}
Y_{xm1_{(m>0)}}=\beta_0+\beta_1m+\beta_2 1_{(m>0)}+\beta_3x+\beta_4x1_{(m>0)}+\beta_5xm+\epsilon, \label{ymodel}
\end{align}
where $Y_{xm1_{(m>0)}}$ is the potential outcome of $Y$ when $(X, M, 1_{(M>0)})$ take the value of $(x,m,1_{(m>0)})$, $1_{(\cdot)}$ is an indicator function.
Equation (\ref{ymodel}) is an regression model where $\beta_0,\beta_1,\beta_2,\beta_3,\beta_4,\beta_5$ are regression coefficients and $\epsilon$ is the random error following the normal distribution $N(0,\delta^2)$.
Notice that interactions between $X$ and the two mediators $M$ and $1_{(M>0)}$ can be accommodated by the product terms $\beta_4X1_{(M>0)}$ and $\beta_5XM$ in the model, which is an advantage of potential-outcomes mediation analysis approaches. Users can specify whether to include either one, both, or none of the two possible interactions using the argument `XMint`.

### 2.1 Zero-inflated mediators
#### 2.1.1 Zero-inflated log-normal (ZILoN) mediators
For a ZILoN mediator, its two-part density function can be rewritten as: 
\begin{align}
&  f(m;\theta)=\begin{cases}
    \Delta, & m=0\\
    (1-\Delta)\phi(m;\mu,\sigma), &m>0
  \end{cases}, \label{zilon}
\end{align}
where $\phi(\cdot)$ is the density function of the log-normal distribution indexed by the parameters $\mu$ and $\sigma$ which are the expected value and standard deviation, respectively, of the random variable after natural-log transformation. 

The ZILoN mediator $M$ depends on $X$ through the following equations: 
\begin{align}
&\mu=\alpha_{0}+\alpha_{1}X, \label{transzilon1}\\
&\log{\bigg(\frac{\Delta}{1-\Delta}\bigg)}=\gamma_0+\gamma_1X.  \label{transzilon2}
\end{align}
Equations (\ref{ymodel}), (\ref{transzilon1}) and (\ref{transzilon2}) together form the full mediation model for a ZILoN mediator and a continuous outcome.

#### 2.1.2 Zero-inflated negative binomial (ZINB) mediators
The two-part density function for a ZINB mediator $M$ is given by:
\begin{align}
&  f(m;\theta)=\begin{cases}
    \Delta=\Delta^*+(1-\Delta^*)(\frac{r}{r+\mu})^r, & m=0\\\\
    (1-\Delta) \frac{\Gamma(r+m)}{\Gamma(r)m!}\frac{(\frac{\mu}{r+\mu})^m}{(\frac{r}{r+\mu})^{-r}-1}, & m=1,2,\dots
  \end{cases}, \label{zinb}
\end{align}
where the parameter vector $(\mu,r)^T$ controls the number of zeros generated from the NB distribution, $0<\Delta^*<1$ is the parameter controlling the number of excessive zeros (i.e., not generated from the NB distribution), $r$ is the dispersion parameter, and $\mu$ is the expectation of the negative binomial distribution. The ZINB mediator $M$ depends on $X$ through the following equations: 
\begin{align}
&\log(\mu)=\alpha_{0}+\alpha_{1}X, \label{transzinb1}\\
&\log{\bigg(\frac{\Delta^*}{1-\Delta^*}\bigg)}=\gamma_0+\gamma_1X.  \label{transzinb2}
\end{align}
Equations (\ref{ymodel}), (\ref{transzinb1}) and (\ref{transzinb2}) together form the full mediation model for a ZINB mediator and a continuous outcome. 

#### 2.1.3 Zero-inflated Poisson (ZIP) mediators
The two-part density function for a ZIP mediator can be rewritten as: 
\begin{align}
&  f(m;\theta)=\begin{cases}
    \Delta=\Delta^*+(1-\Delta^*)\exp{(-\lambda)}, & m=0\\
    (1-\Delta)\frac{\lambda^m}{m! (\exp{(\lambda)}-1)}, & m=1,2,\dots
  \end{cases}, \label{zip}
\end{align}
where $\lambda>0$ is the mean of the Poisson distribution. $\lambda$ controls the number of zeros generated by the data generating process underlying the Poisson distribution, while $0<\Delta^*<1$ controls the number of excessive zeros in addition to zeros from the Poisson distribution. The ZIP mediator $M$ depends on $X$ through the following equations: 
\begin{align}
&\log{(\lambda)}=\alpha_0+\alpha_1X , \label{transzip1}\\
&\log{\bigg(\frac{\Delta^*}{1-\Delta^*}\bigg)}=\gamma_0+\gamma_1X. \label{transzip2}
\end{align}
Equations (1), (\ref{transzip1}) and (\ref{transzip2}) together form the full mediation model for a ZIP mediator and a continuous outcome. 

### 2.2 Probability mechanism for observing false zeros
It is common to observe two types of zeros for $M$ in a data set with excessive zeros: true zeros and false zeros. We use $M$ to denote the true value of the mediator and use $M^*$ for the observed value of $M$. When the observed value of the mediator is positive (i.e., $M^*>0$), we assume  $M^*=M$. However, when $M^*=0$, we don't know whether $M$ is truly zero or $M$ is positive but incorrectly observed as zero. We consider the following mechanism for observing a zero: 

\begin{equation}\label{zeroMecha}
  P(M^*=0|M)=\begin{cases}
    \exp(-\eta^2 M), & M\le B\\
    0, &M>B
  \end{cases},
\end{equation}
where the parameter $\eta$ needs to be estimated, and $B>0$ is a known constant. The value of $B$ can be informed on the basis of the insights and judgements of professionals in the specific field from which the data arose.

### 2.3 Mediation effect and direct effect
The natural indirect effect (NIE), natural direct effects (NDE) and controlled direct effect (CDE) are derived for the proposed mediation model. The NIE is also called the mediation effect. The total effect of the independent variable $X$ is equal to the summation of NIE and NDE. Let $M_x$ denote the value of $M$ if $X$ is taking the value of $x$. Let $1_{(M_x>0)}$ denote the value of $1_{(M>0)}$ if $X$ takes the value of $x$. The average NIE, NDE and CDE if $X$ changes from $x_1$ to $x_2$ are given by:
\begin{align}
&\text{NIE}=E\big(Y_{x_2M_{x_2}1_{(M_{x_2}>0)}}-Y_{x_2M_{x_1}1_{(M_{x_1}>0)}}\big), \label{defNIE}\\
&\text{NDE}=E\big(Y_{x_2 M_{x_1}1_{(M_{x_1}>0)}}-Y_{x_1 M_{x_1}1_{(M_{x_1}>0)}}\big), \label{defNDE}\\
&\text{CDE}=E\big(Y_{x_2 m1_{(m>0)}}-Y_{x_1 m1_{(m>0)}}\big),\hspace{0.1cm}\text{for a fixed (i.e., controlled) value of}\hspace{0.1cm} M, \label{defCDE}
\end{align}

Based on the sequential order of the two mediators $M$ and $1_{(M>0)}$, NIE can be further decomposed: 
\begin{align}
\text{NIE}&=E\big(Y_{x_2M_{x_2}1_{(M_{x_2}>0)}}-Y_{x_2M_{x_1}1_{(M_{x_1}>0)}}\big)\nonumber\\
&=E\big(Y_{x_2M_{x_2}1_{(M_{x_2}>0)}} - Y_{x_2M_{x_1}1_{(M_{x_2}>0)}}\big) + E\big(Y_{x_2M_{x_1}1_{(M_{x_2}>0)}}  - Y_{x_2M_{x_1}1_{(M_{x_1}>0)}}\big) \nonumber\\
&:= \text{NIE}_1+\text{NIE}_2, \label{decomposeNIE}
\end{align}
where NIE$_1$ is the mediation effect through $M$ summing the two causal pathways $X\rightarrow M\rightarrow Y$ and $X\rightarrow M\rightarrow 1_{(M>0)}\rightarrow Y$, and $\text{NIE}_2$ is the mediation effect through only $1_{(M>0)}$ on the causal pathway $X\rightarrow 1_{(M>0)}\rightarrow Y$. 

#### 2.3.1 Effects for ZILoN mediators
\begin{align*}
\text{NIE}_1&=(\beta_1+\beta_5x_2)\Bigg[(1-\Delta_{x_2})\exp{\Big(\mu_{x_2}+\frac{\sigma^2}{2}\Big)}-(1-\Delta_{x_1})\exp{\Big(\mu_{x_1}+\frac{\sigma^2}{2}\Big)}\Bigg], \\
\text{NIE}_2&=(\beta_2+\beta_4x_2)(\Delta_{x_1}-\Delta_{x_2}), \\
\text{NDE}&=(x_2-x_1)\Bigg\{\beta_3+(1-\Delta_{x_1})\Big[\beta_4+\beta_5\exp{\Big(\mu_{x_1}+\frac{\sigma^2}{2}\Big)\Big]}\Bigg\}, \\
\text{CDE}&=(x_2-x_1)\big(\beta_3+\beta_41_{(m>0)}+\beta_5m\big).
\end{align*}

#### 2.3.2 Effects for ZINB mediators
\begin{align*}
\text{NIE}_1&=(\beta_1+\beta_5x_2) \Bigg[(1-\Delta^*_{x_2})\mu_{x_2}-(1-\Delta^*_{x_1})\mu_{x_1}\Bigg],\\
\text{NIE}_2&=(\beta_2+\beta_4 x_2) \Bigg\{\big(1-\Delta^*_{x_2}\big)\Big[1-(\frac{r}{r+\mu_{x_2}})^{r}\Big]-\big(1-\Delta^*_{x_1}\big)\Big[1-(\frac{r}{r+\mu_{x_1}})^{r}\Big]\Bigg\},\\
\text{NDE}&=(x_2-x_1)\Bigg\{\beta_3+(1-\Delta^*_{x_1})\bigg[\beta_4\Big(1-(\frac{r}{r+\mu_{x_1}})^{r}\Big)+\beta_5\mu_{x_1}\bigg]\Bigg\},\\
\text{CDE}&=(x_2-x_1)\big(\beta_3+\beta_41_{(m>0)}+\beta_5m\big).
\end{align*}

#### 2.3.3 Effects for ZIP mediators
\begin{align*}
\text{NIE}_1&=(\beta_1+\beta_5x_2) \Big[(1-\Delta^*_{x_2})\lambda_{x_2}-(1-\Delta^*_{x_1})\lambda_{x_1}\Big],\\
\text{NIE}_2&=(\beta_2+\beta_4 x_2) \Bigg\{\big(1-\Delta^*_{x_2}\big)\Big[1-\exp{(-\lambda_{x_2})}\Big]-\big(1-\Delta^*_{x_1}\big)\Big[1-\exp{(-\lambda_{x_1})}\Big]\Bigg\},\\
\text{NDE}&=(x_2-x_1)\Bigg\{\beta_3+(1-\Delta^*_{x_1})\bigg[\beta_4\Big(1-\exp{(-\lambda_{x_1})}\Big)+\beta_5\lambda_{x_1}\bigg]\Bigg\},\\
\text{CDE}&=(x_2-x_1)\big(\beta_3+\beta_41_{(m>0)}+\beta_5m\big).
\end{align*}


## 3. Installing the R package
The R package `MAZE` can be installed from the Github webpage.
```{r,eval=F}
require(devtools)
devtools::install_github("https://github.com/meilinjiang/MAZE", build_vignettes = TRUE)
```

## 4. Main function `MAZE()`
To estimate and test NIE, NIE$_1$, and NIE$_2$, NDE, and CDE, the R function `MAZE` is used to implement the proposed mediation analysis approach for zero-inflated mediators.

### 4.1 Input arguments

The input arguments to the function are

- `data`: a data frame containing variables: an independent variable \eqn{X}, a mediator \eqn{M}, an outcome \eqn{Y}, and confounder variables \eqn{Z} (if any). See example dataset: `data(zinb10)`

- `distM`: a vector with choices of the distribution of mediator to try with. One or more of '`zilonm`', '`zinbm`', and '`zipm`' for zero-inflated log-normal, negative binomial, and Poisson mediators respectively. Default is `c('zilonm', 'zinbm', 'zipm')` where all three distributions are fitted and the final mediation model is selected by model selection criterion `selection`

- `K`: a vector with choices of the number of component \eqn{K} in the zero-inflated mixture mediators to try with. Default is \eqn{K=1} for zero-inflated (non-mixture) mediators

- `selection`: model selection criterion when more than one model (combination of different values in `distM` and `K`) is fitted. Either '`AIC`' or '`BIC`'. Default is '`AIC`'

- `X`: name of the independent variable. Can be continuous or discrete

- `M`: name of the mediator variable. Non-negative values

- `Y`: name of the outcome variable. Continuous values

- `Z`: name(s) of confounder variables (if any)

- `XMint`: a logical vector of length 2 indicating whether to include the two exposure-mediator interaction terms between (i) \eqn{X} and \eqn{1_{(M>0)}} and (ii) \eqn{X} and \eqn{M}. Default is `c(TRUE, FALSE)`, which only includes the first

- `x1`: the first value of independent variable of interest

- `x2`: the second value of independent variable of interest

- `zval`: the value of confounders to be conditional on when estimating effects

- `mval`: the fixed value of mediator to be conditional on when estimating CDE

- `B`: the upper bound value \eqn{B} to be used in the probability mechanism of observing false zeros

- `seed`: an optional seed number to control randomness for reproducibility. The default is 1

- `ncore`: number of cores available for parallel computing

### 4.2 Outputs

A list object containing

- `results_effects`: a data frame for the results of estimated effects (NIE1, NIE2, NIE, NDE, and CDE)

- `results_parameters`: a data frame for the results of model parameters

- `selected_model_name`: a string for the distribution of \eqn{M} and number of components \eqn{K} selected in the final mediation model

- `BIC`: a numeric value for the BIC of the final mediation model

- `AIC`: a numeric value for the AIC of the final mediation model

- `models`: a list with all fitted models

- `analysis2_out`: a list with output from analysis2() function (used for internal check)

## 5. Example
The `MAZE` package contains an example dataset `zinb10` that was generated using the proposed model with a zero-inflated negative binomial mediator ($K=1$). It is a data frame with 100 observations and 3 variables: a continuous independent variable `X`, a continuous outcome `Y`, and a count mediator variable `Mobs`. The mediator variable contains 10% zero values in which half are false zeros. 
```{r,eval=T}
library(MAZE)
# load the example dataset "zinb10"
data(zinb10)
# call MAZE() to perform mediation analysis
maze_out <- MAZE(data = zinb10,
                 distM = c('zilonm', 'zinbm', 'zipm'),  K = 1,
                 selection = 'AIC',
                 X = 'X', M = 'Mobs', Y = 'Y', Z = NULL,
                 XMint = c(TRUE, FALSE),
                 x1 = 0, x2 = 1, zval = NULL, mval = 0,
                 B = 20, seed = 1)
## results of selected mediation model
maze_out$results_effects # indirect and direct effects
maze_out$selected_model_name # distribution of the mediator and number of components K in the selected mediation model
maze_out$results_parameters # model parameters
maze_out$BIC; maze_out$AIC # BIC and AIC of the selected mediation model
```

Session Info
```{r}
sessionInfo()
```


