---
title: "Imputation of Missing Data at Level 2"
output:
  rmarkdown::html_vignette:
    css: "css/vignette.css"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Imputation of Missing Data at Level 2}
  %\VignetteEncoding{UTF-8}
---

---

```{r setup, include=FALSE, cache=FALSE}
library(knitr)
set.seed(123)
options(width=87)
opts_chunk$set(background="#ffffff", comment="#", collapse=FALSE,
               fig.width=9, fig.height=9, warning=FALSE,
               message=FALSE)
```

This vignette illustrates the use of `mitml` for the treatment of missing data at Level 2.
Specifically, the vignette addresses the following topics:

1. Specification of the two-level imputation model for missing data at both Level 1 and 2
2. Running the imputation procedure

Further information can be found in the other [vignettes](https://github.com/simongrund1/mitml/wiki) and the package [documentation](https://cran.r-project.org/package=mitml/mitml.pdf).

## Example data

For purposes of this vignette, we make use of the `leadership` data set, which contains simulated data from 750 employees in 50 groups including ratings on job satisfaction, leadership style, and work load (Level 1) as well as cohesion (Level 2).

The package and the data set can be loaded as follows.

```{r}
library(mitml)
data(leadership)
```

In the `summary` of the data, it becomes visible that all variables are affected by missing data.

```{r}
summary(leadership)
```

The following data segment illustrates this fact, including cases with missing data at Level 1 (e.g., job satisfaction) and 2 (e.g., cohesion).

```{r, echo=FALSE}
leadership[73:78,]
```

In the following, we will employ a two-level model to address missing data at both levels simultaneously.

## Specifying the imputation model

The specification of the two-level model, involves two components, one pertaining to the variables at each level of the sample (Goldstein, Carpenter, Kenward, & Levin, 2009; for further discussion, see also Enders, Mister, & Keller, 2016; Grund, Lüdtke, & Robitzsch, in press).

Specifically, the imputation model is specified as a list with two components, where the first component denotes the model for the variables at Level 1, and the second component denotes the model for the variables at Level 2.

For example, using the `formula` interface, an imputation model targeting all variables in the data set can be written as follows.

```{r}
fml <- list( JOBSAT + NEGLEAD + WLOAD ~ 1 + (1|GRPID) , # Level 1
             COHES ~ 1 )                                # Level 2
```

The first component of this list includes the three target variables at Level 1 and a fixed (`1`) as well as a random intercept (`1|GRPID`).
The second component includes the target variable at Level 2 with a fixed intercept (`1`).

From a statistical point of view, this specification corresponds to the following model
$$
\begin{aligned}
\mathbf{y}_{1ij} &= \boldsymbol\mu_{1} + \mathbf{u}_{1j} + \mathbf{e}_{ij} \\
\mathbf{y}_{2j} &= \boldsymbol\mu_{2} + \mathbf{u}_{1j} \; ,
\end{aligned}
$$
where $\mathbf{y}_{1ij}$ denotes the target variables at Level 1, $\mathbf{y}_{2j}$ the target variables at Level 2, and the right-hand side of the model contains the fixed effects, random effects, and residual terms as mentioned above.

Note that, even though the two components of the model appear to be separated, they define a single (joint) model for all target variables at both Level 1 and 2.
Specifically, this model employs a two-level covariance structure, which allows for relations between variables at both Level 1 (i.e., correlated residuals at Level 1) and 2 (i.e., correlated random effects residuals at Level 2).

## Generating imputations

Because the data contain missing values at both levels, imputations will be generated with `jomoImpute` (and not `panImpute`).
Except for the specification of the two-level model, the syntax is the same as in applications with missing data only at Level 1.

Here, we will run 5,000 burn-in iterations and generate 20 imputations, each 250 iterations apart.

```{r, results="hide"}
imp <- jomoImpute(leadership, formula = fml, n.burn = 5000, n.iter = 250, m = 20)
```

By looking at the `summary`, we can then review the imputation procedure and verify that the imputation model converged.

```{r}
summary(imp)
```

Due to the greater complexity of the two-level model, the output includes more information than in applications with missing data only at Level 1.
For example, the output features the model specification for variables at both Level 1 and 2.
Furthermore, it provides convergence statistics for the additional regression coefficients for the target variables at Level 2 (i.e., `Beta2`).

Finally, it also becomes visible that the two-level model indeed allows for relations between target variables at Level 1 and 2.
This can be seen from the fact that the potential scale reduction factor ($\hat{R}$) for the covariance matrix at Level 2 (`Psi`) was largest for `Psi[4,3]`, which is the covariance between cohesion and the random intercept of work load.

## Completing the data

The completed data sets can then be extracted with `mitmlComplete`.

```{r}
implist <- mitmlComplete(imp, "all")
```

When inspecting the completed data, it is easy to verify that the imputations for variables at Level 2 are constant within groups as intended, thus preserving the two-level structure of the data.

```{r, echo=FALSE}
implist[[1]][73:78,]
```

###### References

Enders, C. K., Mistler, S. A., & Keller, B. T. (2016). Multilevel multiple imputation: A review and evaluation of joint modeling and chained equations imputation. *Psychological Methods*, *21*, 222–240. doi: 10.1037/met0000063 ([Link](https://doi.org/10.1037/met0000063))

Goldstein, H., Carpenter, J. R., Kenward, M. G., & Levin, K. A. (2009).  Multilevel models with multivariate mixed response types. *Statistical Modelling*, *9*, 173–197. doi: 10.1177/1471082X0800900301 ([Link](https://doi.org/10.1177/1471082X0800900301))

Grund, S., Lüdtke, O., & Robitzsch, A. (2018). Multiple imputation of missing data for multilevel models: Simulations and recommendations. *Organizational Research Methods*, *21*(1), 111–149. doi: 10.1177/1094428117703686 ([Link](https://doi.org/10.1177/1094428117703686))

---

```{r, echo=F}
cat("Author: Simon Grund (simon.grund@uni-hamburg.de)\nDate:  ", as.character(Sys.Date()))
```