---
title: "Guide for package DesignCTPB"
author: "Yitao Lu, Belaid, Xuekui Zhang"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{DesignCTPB}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

As a future trend of health care, personalized medicine tailors medical treatments to individual patients. It requires to identify a subset of patients with the best response to treatment. The subset can be defined by a biomarker (e.g. expression of a gene) and its cutoff value. However, designing clinical trials that utilize the discovered uncertain subsets/biomarkers is not trivial and rarely discussed in the literature. 

And we formulate the problem of clinical trial design into an optimization problem involving high-dimensional integration, and propose a novel computational solution based on Monte-Carlo and smoothing methods.  Our method utilizes the modern techniques of General-Purpose computing on Graphics Processing Units for large-scale parallel computing. Compared to a published method in three-dimensional problems, our approach is more accurate and 133 times faster. This advantage increases when dimensionality increases.  Our method is scalable to higher-dimensional problems since the precision bound of our estimated study power is a finite number not affected by dimensionality.

This package can guide researchers to do clinical trials with nested sub-population effect, which is easily to use. Before using the package, please check your CUDA and CUDAtoolkit are well-installed. Here are the guidance for users.


# How to

```{r library, eval=FALSE, message=FALSE, warning=FALSE}
library(DesignCTPB)
```


## Calculating optimal alpha-split for a given setting of proportion of each subpopulation
```{r alpha_split, message=FALSE, warning=FALSE, eval=FALSE}
alpha.split()# the default setting will give an optimal results of 3-dimensional case
```


## Calculating optimal alpha-split for variate settings of r values (i.e. size of nested subpopulations), and visualize their results, calculate optimal choice of the proportion for each subset

In this guidance, we show the results presented in our paper, which are the simulation examples for the strong and weak biomarker effect conditions. The following chunk shows how to get the results. m is the density value for grid setting or r(the proportion for each sub-population); n_dim denotes the dimension; N1 and N2 are fixed and we suggest do not change them otherwise have to change the corresponding the number of threads and block in python code. N3 could be changed and has to be the multiplier of 5. E is the total number of events in the clinical trial, if not specified, we will apply an estimated information units, please refer to formula(10) in our paper. SIGMA is the matrix of standard deviation of each sub-population, which should coincide with r_set or the default setting of each sub-population(i.e each entry of each row coincides to the corresponding entry in r_set). For simplify, we apply $\sigma_i = \frac{1}{\sqrt{20*r_i}}$ which has been explained in the paper. DELTA is the matrix of harzard reduction corresponding to the r setting too. While for simplify, we use a linear scheme of harzard reduction, which means $\Delta_i = 0.8-0.6*r_i$ in our example below. 

```{r visulization, eval=FALSE, warning=FALSE}
res <- designCTPB(m=24, n_dim=3, sd_full=1/sqrt(20),delta_linear_bd=c(0.2,0.8))
res$plot_alpha # to see the 3-d rotatable plot of optimal alpha versus r2 and r3.
res$plot_power # to see the 3-d rotatable plot of optimal power versus r2 and r3.
res$opt_r_split
res$opt_alpha_split
res$opt_power
```

For the time consuming problem, we load the pre-run data and show the results below.


### Weak biomarker effect

Fitted TPS surface of the optimal power: https://www.math.uvic.ca/~xuekui/HDDesign/Figure1.4
Fitted TPS surface of the optimal $\alpha$ : https://www.math.uvic.ca/~xuekui/HDDesign/Figure1.3

```{r}
data(ctpbw, package = "DesignCTPB")
```

```{r warning=FALSE}
#optimal choice of each population's proportion
ctpbw$opt_r_split
```
```{r}
#the optimal power of the optimal design
ctpbw$opt_power
```
```{r}
#the optimal alpha split of the optimal design
ctpbw$opt_alpha_split
```

For the weak biomarker effect, we find that $r_3 = 0$, which suggests only consider one sub-population instead of two, reducing the optimization into two dimension. Then we have to compute the optimal alpha split in two dimension.
```{r warning=FALSE, eval=FALSE}
alpha.split(r=c(1,0.303),N3=100,sd_full=1/sqrt(20),delta_linear_bd = c(0.2,0.3))
```

For another way, we could re-design the clinical trial in two dimension.

```{r eval=FALSE, warning=FALSE}
r2 <- seq(0.025,1,by=0.025)
res_2dim <- matrix(rep(0,3*length(r2)), ncol=3)
for(ii in 1:length(r2)){
  res_2dim[ii,] <- alpha.split(r=c(1,r2[ii]),N3=100,sd_full=1/sqrt(20),delta_linear_bd = c(0.2,0.3))
}
```
One can use smooth model to fit and find the maximization, but we could also just take the maximizer right away.
```{r eval=FALSE, warning=FALSE}
power_value <- res[,3]
opt_r2 <- r2[which.max(power_value)]
opt_alpha <- res[which.max(power_value),1:2]
opt_r2
opt_alpha
```


### Strong biomarker effect

Fitted TPS surface of the optimal power: https://www.math.uvic.ca/~xuekui/HDDesign/Figure1.6

Fitted TPS surface of the optimal $\alpha$: https://www.math.uvic.ca/~xuekui/HDDesign/Figure1.5

```{r}
data(ctpbs, package = "DesignCTPB")
```


```{r}
#the optimal power of the optimal design
ctpbs$opt_power
```

Hence, for the strong biomarker effect condition, the simulation suggests that 2-cutoff design is optimal, where the smallest sub-population consists of 13.9\% of the full population, the larger one consists of nearly 40\%. Then the design separates the full population into three populations with two nested sub-populations. The Type-I error rate for each population is allocated as below. 

```{r}
#the optimal alpha split of the optimal design
ctpbs$opt_alpha_split
```

And the maximized power for the optimal design is:

```{r warning=FALSE}
#optimal choice of each population's proportion
ctpbs$opt_r_split
```

