---
title: "idem: Inference in Randomized Controlled Trials with Death and Missingness"
author: "Chenguang Wang"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{idem: Inference in Randomized Controlled Trials with Death and Missingness}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, eval=T, echo=FALSE}
require(idem);
set.seed(1000);
```

# Introduction

In randomized studies involving severely ill patients, functional outcomes are
often unobserved due to missed clinic visits, premature withdrawal or death. It
is well known that if these unobserved functional outcomes are not handled
properly, biased treatment comparisons can be produced.

*R* package **idem** implement a procedure for comparing treatments that is
based on the composite endpoint of both the functional outcome and survival. The
procedure considers missing data imputation with a sensitivity analysis strategy
to handle the unobserved functional outcomes not due to death.

# Data accepted by **idem**

In dataset accepted by **idem**, each row should represent a subject with
treatment assignment, baseline coveraites, baseline outcome, post-randomization
outcomes and survival time.

The **idem** package provides dataset *abc* from *ABC* trial as an example data
set.

```{r, eval=T, echo=TRUE}
head(abc);
```

# Basic steps 

There are four major steps in conducting imputation and inference using
**idem**. First, a class *IDEMDATA* object should be generated by the function
*imData*. Second, the imputation models will be fit to the data observed from
the completers by the function *imFitModel*. Third, imputation can be conducted
by the function *imImpAll*. Lastly, treatment effect estimation and hypothesis testing
can be performed by function *imInfer*.

# Data generalization and visualization

In this step, the original dataset with specification parameters will be
combined and checked. These parameters include variable names in the dataset,
endpoint specification, duration of the study, etc.. If there is
mis-specification, error messages will be generated. Otherwise, a class
*IDEMDATA* object will be generated with certain data visulation functions
implemented as its S3 methods.

```{r, echo=TRUE, fig.width=6, fig.height=5}
rst.data <- imData(abc, trt="TRT", outcome=c("Y1","Y2"), y0=NULL,
                   endfml="Y3", bounds=c(10,20), duration=365,
                   err.terminate = FALSE);
print(rst.data);

rst.data <- imData(abc, trt="TRT", surv="SURV", outcome=c("Y1","Y2"),
                   y0=NULL, endfml="Y2",
                   trt.label = c("UC+SBT", "SAT+SBT"),
                   cov=c("AGE"), duration=365, bounds=c(0,100));
```

The class *IDEMDATA* provides S3 plot and summary methods with multiple options
for the visualization of the data.

## Spaghetti plot for survivors

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.data, opt = "survivor");
```

## Missing pattern frequency table
```{r, echo=TRUE}
summary(rst.data, opt = "misstable");
```

## Missing pattern heatmap

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.data, opt = "missing", cols = c("blue", "gray"));
```

## Kaplan-Meier curves

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.data, opt = "KM");
```


# Missing data imputation

## Model fitting

To fit the imputation model to data observed from the completers, i.e. the
subjects who were alive at the end of the study without missing data, the class
*IDEMDATA* object needs to be passed to the function *imFitModel* as parameters.
The result has class name **IDEMFIT**, which will be passed to imputation
functions.

```{r, echo=TRUE, fig.width=6, fig.height=5}
rst.fit <- imFitModel(rst.data);
```

The goodness of fit diagnostics plots can be generated by the S3 plot method
implemented for class *IDEMFIT*:
```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.fit, mfrow=c(2,4));
```

## Check convergence

The MCMC sampling is primarily done by **rstan**. It is suggested that the
convergence of the MCMC chains should be checked. This can be done by the
**imImpSingle** function which imputes missing data for an individual subject
under the benchmark assumption.

```{r, echo=TRUE, fig.width=6, fig.height=5}
rst.mixing <- imImpSingle(abc[1,], rst.fit, chains = 4, iter = 2000, warmup = 1000);
plot(rst.mixing);
```

## Imputation

The following code shows how to use **imImpAll** to get the imputed complete
datasets under benchmark assmption **delta=0** and for sensitivity analysis. We
use **300** iterations to reduce the computation time.

```{r, echo=TRUE, results="hide"}
rst.imp <- imImpAll(rst.fit, deltas=c(-0.25,0,0.25),
                    normal=TRUE, chains = 4, iter = 300, warmup = 100);

rst.imp
```

## Plot denisity of the imputed data

The result from *imIMPALL* is class *IDEMFIT*. Density plots the imputed
outcomes and the imputed functional endpoint can be generated by the S3 plot
method associated with class *IDEMFIT*.

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.imp, opt = "imputed", deltas = c(-0.25,0,0.25), xlim=c(0,100), endp=FALSE);
```


```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.imp, opt = "imputed", deltas = c(-0.25,0,0.25), xlim=c(0,100), endp=TRUE);
```

# Composite endpoint analysis

## Plot the cumulative distribution of the compositve endpoint

Treatment-specific cumulative
distribution functions of the composite endpoint, where the values of the
composite endpoint are labeled according to the survival time and functional
endpoint among survivors, can be plotted by the S3 plot method of class *IDEMFIT*.

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.imp, delta=0);
```

## Inference

The function *imInfer* implements bootstrap analysis for hypothesis testing,
point estimation and confidence intervals of the treatment effects.

For illustration, we run **2** bootstrap samples by the following code:

```{r, echo=TRUE}
rst.test <- imInfer(rst.imp, n.boot = 2);
rst.test
```

A contour plot of p-values in the sensitivity analysis results can be generated
by the S3 method of the result returned by **imInfer**:

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst.test, nlevels = 30, con.v=0.05, zlim=c(0, 0.05));
```

# Graphical user interface (GUI)

The **idem** package provides a web-based GUI for composite endpoint analysis.
The GUI can be accessed by

```{r, echo=TRUE, eval=FALSE}
imShiny();
```