Wave-Level-PHPM.Rmd

---
title: "Wave-level PHPM designs"
author: "Yi Feng & Gregory R. Hancock"
#date: "`r Sys.Date()`"
output:
      rmarkdown::html_vignette:
        fig_caption: yes
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## <span style="color:seagreen">**Introduction**</span>
In this vignette we will introduce the wave-level PHPM designs. As the name suggests, in wave-level PHPM designs, the missingness is imposed at the wave level. In those designs, participants are assigned to miss one or more waves of future data collection. If a participant is assigned to miss a specific wave of data collection, the researcher will not collect any data from this participant in that wave. 

Wave-level PHPM designs are relatively easy to implement. But there is usually a very limited number of plausible wave-level missing designs, and thus sometimes the search among wave-level PHPM designs may not yield a satisfactory result in terms of statistical power. 


## <span style="color:seagreen">**Search for wave-level PHPM designs**</span>

To search for wave-level PHPM designs using `simPM`, we only need to specify the `methods = "wave"` argument when using the `simPM()` function. 

## <span style="color:seagreen">**Example**</span> 

In this [hypothetical example](Conditional-Linear-Latent-Growth-Model.html), a researcher (Dr. X) is interested in studying the longitudinal growth of adolescents' depressive symptoms. Dr. X has proposed a longitudinal study that is expected to extend over 3 years. Participants are to be assessed with Beck's Depression Inventory (BDI) every six months. Participants also report their social support at the first wave of data collection. The data will be analyzed using a conditional linear LGM, as seen in the following diagram. The main goal of the study is to examine the impact of social support on the growth trajectory of depressive symptoms. Additionally, the researcher is interested in the relation between the intercept and slope after controlling for social support. The model parameters of focal interest include the path coefficients predicting the latent intercept and latent slope from social support, as well as the residual covariance between the latent intercept and slope. 


Although the researcher has initially obtained an external funding to support his longitudinal study, unfortunately, after the first two waves of data collection, the funding agency announces a 30% reduction in the remaining funding. Mr. X wishes to continue the project but he has to deal with the lowered budget constraint. Of course, Mr. Y also wants to keep the scientific rigor and satisfactory statistical power. She thus chooses to use `simPM` to find a design that yields sufficient power but costs no more than the reduced budget. 


```{r,out.width='70%', fig.align='center', fig.cap='A conditional linear LGM', echo=FALSE}
knitr::include_graphics('images/CLPM.png')
```


After supplying the population model and the analysis model, we can use the function `simPM()` to search for an optimal wave-level missing design with the `methods = "wave"` argument. For more details about the specification of other arguments, please refer to [this vignette](Conditional-Linear-Latent-Growth-Model.html).  

```{r,eval=F}
popModel <- '

sprt ~~ 1*sprt
sprt ~ 0*1

i =~ 1*BDI1 + 1*BDI2 + 1*BDI3 + 1*BDI4 + 1*BDI5 + 1*BDI6
s =~ 0*BDI1 + 1*BDI2 + 2*BDI3 + 3*BDI4 + 4*BDI5 + 5*BDI6

BDI1~0*1
BDI2~0*1
BDI3~0*1
BDI4~0*1
BDI5~0*1
BDI6~0*1

BDI1~~0.3*BDI1
BDI2~~0.3*BDI2
BDI3~~0.3*BDI3
BDI4~~0.3*BDI4
BDI5~~0.3*BDI5
BDI6~~0.3*BDI6

i ~ -1.5*sprt
s ~ -0.2*sprt

i ~ 26*1
s ~ -1*1

i ~~ 6*i+ (-0.9)*s
s ~~ 2*s

'
```


```{r, eval=F}
analyzeModel <- '

sprt ~~ sprt
sprt ~ 1

i =~ 1*BDI1 + 1*BDI2 + 1*BDI3 + 1*BDI4 + 1*BDI5 + 1*BDI6
s =~ 0*BDI1 + 1*BDI2 + 2*BDI3 + 3*BDI4 + 4*BDI5 + 5*BDI6

BDI1~0*1
BDI2~0*1
BDI3~0*1
BDI4~0*1
BDI5~0*1
BDI6~0*1

BDI1~~BDI1
BDI2~~BDI2
BDI3~~BDI3
BDI4~~BDI4
BDI5~~BDI5
BDI6~~BDI6

i ~ sprt
s ~ sprt

i ~ 1
s ~ 1

i ~~ i + s
s ~~ s

'

```


```r
wave.lgm <- simPM::simPM(popModel = popModel, 
                      analyzeModel = analyzeModel,
                      VarNAMES = paste0("BDI",1:6),
                      Time = 6,
                      Time.complete = 2,
                      k = 1,
                      pc = 0.2,
                      pd = 0,
                      costmx = c(10,10,15,15),
                      n = 450,
                      nreps = 1000,
                      focal.param = c("i~sprt","s~sprt","i~~s"),
                      complete.wave = NULL,
                      eval.budget = T,
                      rm.budget = 50*450*0.7,
                      seed = 12345,
                      distal.var = "sprt",
                      engine = "l",
                      methods = "wave")

```

By running the code above, `simPM` will map out the possible wave-level PHPM designs and determine whether the cost of each design is within the remaining budget limit. It will run Monte Carlo simulations for the plausible designs that cost less than the remaining amount of funding. Comparisons are made among the plausible designs. The design that yields higher empirical statistical power with regard to the focal parameters will be selected as the optimal wave-level PHPM design.

In this example, there are two plausible wave-level PHPM designs, given we have specified that 20% of the participants will provide complete data over the following waves of data collection. 


From the output, we can see that 90 participants are assigned to provide complete data over the future waves of data collection, while the rest of the participants are assigned to one of the four missing data patterns. More specifically, ninety participants are randomly picked to NOT provide data in wave 3, wave 4, and wave 5 (the first row of the plot); another 90 participants are randomly picked to NOT provide data in wave 3, wave 4, and wave 6 (the second row of the plot).  

This design yields satisfactory statistical power for testing all three focal parameters (`i~sprt`,`s~sprt`,`i~~s`). 


```{r, include = F, message=FALSE, warning=FALSE}
setwd("C:/Users/yifeng94/Desktop/simPM/simPM-git/examples")
load("new_lgm_example.rda")
library(simPM)

```

```{r}
summary(wave.lgm)
```

```{r,fig.width=7,fig.height=4}
plotPM(wave.lgm)
```