---
title: "Incomplete Designs in `SteppedPower`"
author:
- name: Philipp Mildenberger
  affiliation: Institute of Medical Biostatistics, Epidemiology and Informatics ([IMBEI, Mainz](https://www.unimedizin-mainz.de/imbei/imbei/welcome-page/))
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    number_sections: true
    fig_caption: true
bibliography: references.bib
vignette: >
  %\VignetteIndexEntry{Incomplete Designs with `SteppedPower`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>",
                     fig.width = 7, fig.height = 2, warning = FALSE)
library(knitr)
library(SteppedPower)
library(Matrix)
library(plotly)
assign("knit_print.plotly", function(x, ...) {
  x <- plotly::partial_bundle(x)
  NextMethod()
}, envir = .GlobalEnv)

# A function for captioning and referencing images
fig <- local({
    i <- 0
    ref <- list()
    list(
        cap=function(refName, text) {
            i <<- i + 1
            ref[[refName]] <<- i
            paste("Figure ", i, ": ", text, sep="")
        },
        ref=function(refName) {
            paste("(Fig.", ref[[refName]],")")
        })
})
```

# Main Types of Incomplete Designs

>For a general introduction to `SteppedPower`, see the [Getting Started with `SteppedPower`](Getting_Started.html) vignette.

In general, a study design is referred to as incomplete if not all clusters are
observed at every time period [@hemming2015stepped]. There are two main types of incomplete designs considered in this package.

```{r, echo=FALSE, fig.cap=fig$cap("Incomp1","An incomplete stepped wedge design with four clusters with a total study duration of six periods. Clusters are only observed from two periods prior to treatment switch to two periods post switch.")}
plot(construct_DesMat(Cl=c(1,1,1,1,0), incomplete = 2))
```

```{r, echo=FALSE, fig.cap=fig$cap("Incomp2","An incomplete stepped wedge design with four clusters with a total study duration of six periods. The first period after the switch to interventional treatment - the transition period - is not observed in each cluster.")}
plot(construct_DesMat(Cl=c(1,1,1,1,0), trtDelay = c(NA)))
```

In the first type, clusters that switch early to the intervention are not observed until the end - accordingly, observation starts later in clusters that switch toward the end of the study `r fig$ref("Incomp1")`. The *"edge periods"* are thus not observed *(Fig. 1)*. The second type excludes the transition period(s) between control and intervention conditions *(Fig. 2)*. 



# Defining Incomplete Designs in `SteppedPower`


An incomplete design with unobserved edge periods can be defined with the `incomplete` argument. A scalar is interpreted as the number of observed periods before and after the treatment switch in each cluster.

An incomplete design with unobserved transition periods is best defined with `trtDelay=c(NA)`. This specifies one unobserved transition period. 

Further options to specify incomplete designs are:  

* The input for the `incomplete` argument can also be a matrix of dimension clusters$\cdot$timepoints or sequences$\cdot$timepoints. A matrix must contain `1`s for cluster cells that are observed and `0` or `NA`s for cluster cells that are not observed.
* Insert `NA`s into an explicitly defined treatment matrix, easiest done with the argument `trtmatrix=`.

`glsPower()` calls the function `construct_DesMat()` to construct 
the design matrix with the relevant arguments. 
All the above options can be used in the main wrapper function, but
the examples below focus on `construct_DesMat()` directly.

> Note `SteppedPower` internally stores information about (un)observed cluster cells separately from the treatment allocation for computational reasons.

# Examples

## 1
If, for example, a stepped wedge study consists of eight clusters 
in four sequences (i.e., five timepoints), 
and only the last two periods before and the first two periods after the switch are observed, one can use the `incomplete` argument

```{r}
Dsn1.1 <- construct_DesMat(Cl=rep(2,4), incomplete=2)
```

A slightly more tedious, but more flexible way is to define a matrix 
where each row corresponds to either a cluster or a wave of clusters 
and each column corresponds to a timepoint. 
If a cluster is not observed at a specific timepoint, 
set the value in the corresponding cell to `0`. 
For the example above, such a matrix would look like this:

```{r}
TM  <- toeplitz(c(1,1,0,0))
incompleteMat1 <- cbind(TM[,1:2],rep(1,4),TM[,3:4])
incompleteMat2 <- incompleteMat1[rep(1:4,each=2),]
```

A matrix where each row represents a wave of clusters

```{r, echo=FALSE}
suppressWarnings(knitr::kable(incompleteMat1))
```

or each row represents a cluster

```{r, echo=FALSE}
suppressWarnings(knitr::kable(incompleteMat2))
```

Now all that's left to do is to plug that into the function and we receive the 
same design matrix

```{r}
Dsn1.2 <- construct_DesMat(Cl=rep(2,4), incomplete=incompleteMat1)
Dsn1.3 <- construct_DesMat(Cl=rep(2,4), incomplete=incompleteMat2)

all.equal(Dsn1.1$trtMat,Dsn1.2$trtMat)
all.equal(Dsn1.1$trtMat,Dsn1.3$trtMat)
```


> The argument `incomplete` with matrix input works also for other design types, but makes primarily most sense in the context of stepped wedge designs


## 2

Now suppose we want to use a SWD to investigate the intervention effects after at least one month,  
i.e., cluster periods directly after the switch to intervention conditions are not observed. 
That leads to an incomplete design that is easiest modelled with `trtDelay=`


```{r}
Dsn2 <- construct_DesMat(Cl=rep(2,4), trtDelay = c(NA) )
Dsn2
```

## 3

The above arguments can also be combined, e.g.
```{r}
Dsn3 <- construct_DesMat(Cl=rep(2,4), incomplete=2, trtDelay=c(NA) )
Dsn3
```