---
title: "Quick Start Guide"
author: "Wenchuan Guo and Bob Zhong"
date: '`r Sys.Date()`'
output:
  html_document:
    fig_height: 6
    fig_width: 7
    highlight: tango
    theme: united
  pdf_document: null
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

This guide introduces the basic usage of `tsdf`. For more details, see the documentation for individual functions.

## Installation
Type the following command in R console :
```{r, eval=FALSE}
install.packages("tsdf")
```
or install the latest version from GitHub
```{r, eval=FALSE}
#check if devtools is installed
if(!"devtools" %in% rownames(installed.packages())){
	install.packages(devtools)
}
devtools::install_github("wguo1990/tsdf")
```
Then the R package will be downloaded and installed to the default directories. Run the following command to load the package :
```{r}
library(tsdf)
```
We will briefly go over main functions and their basic usage in the following sections.

## Zhong's 2-/3-stage Phase II designs
To calculate Zhong's two-/three-stage design, users need to provide : left-side type I error(`alpha1`), right-side type I error(`alpha2`), type II error(`beta`), minimal response rate(`pc`) and unacceptable response rate(`pt`, alternative). The minimal response rate can be either single point or an interval. `stage` option specify 2 or 3 stage design. Run the following command to obtain a 2-stage design
```{r}
# type I errors
alpha1 <- 0.15
alpha2 <- 0.10
# type II error
beta <- 0.15
# response rate
pc <- 0.25
# alternative 
pt <- pc + 0.20
# 2-stage design
out <- opt.design(alpha1, alpha2, beta, pc, pt, stage = 2)
```
`out` is an object of class `opt.design`. S3 method `print` is available for  `opt.design` class. To extract information, run 
```{r}
print(out)
```
Alpha-spending method is added to two-/three-stage designs. `opt.design` supports Hwang-Shih-DeCani spending function where `sf.param` specifies the parameter. For two-stage design, the default value is set to be `NULL` which means alpha-spending is not used. For three-stage design, the default is 4. User can change this parameter to set the alpha spent at first 1 or 2 stage. For example, to use a Pocock-like spending function, let `sf.param = 1`, then run
```{r, eval=FALSE}
opt.design(alpha1, alpha2, beta, pc, pt, stage = 2, sf.param = 1)
```

## Decision table for Phase I dose-finding
`dec.table` function is used to generate decision table for a three-stage dose-finding design. `alpha.l` (left side), `alpha.r` (right side), `alpha.u` (right side type I error for "DU", usually less than `alpha.r`) are three type I errors control the boundary of decisions. `pt` is the target toxicity level. `pt` is either a single or an interval value. This is also a group sequential design, so alpha-spending method is added. The `sf.param` option is same as in `opt.design`. The default value is set to be 4. We call `dec.table` function as follows 
```{r}
# sample size 
n <- rep(3, 3)
# type I errors 
alpha.l <- 0.6
alpha.r <- 0.4
alpha.u <- 0.2
# target toxicity 
pt <- 0.3
# call dec.table
out <- dec.table(alpha.l, alpha.r, alpha.u, pt, n)
```
`out` is an object of class `dec.table` that contains all the relevant information including decision table, real type errors and input parameter. However, we do not recommend users to extract the components from this object directly. `plot` and `print` S3 method are available for `dec.table` class. 

We can view the decision table using `print` function :
```{r}
print(out)
```
or visualize the decision table by executing the `plot` function :
```{r}
plot(out)
```

## Dose-finding simulations
There are two functions that allow users to run dose-finding simulations using a user supplied decision table: `dec.sim` and `sl.sim`. To run simulations, users need to provide a decision table either from `dec.table` function or a user-supplied table (see details in next section), true probability of toxicity at each dose level, starting dose (default to lowest dose level) and number of simulated trials (default to 1000). 

`dec.sim` runs one scenario simulation which is usually used for an initial test and `sl.sim` runs a list of scenarios from `.csv` or `.txt` files (See next section Data Format for details). Let's see an example :
```{r}
# true toxicity
truep <- c(0.3, 0.45, 0.5, 0.6)
# generate a decision table
dt <- dec.table(0.6,0.4,0.2,0.3,c(3,3,3))
# run simulation
out1 <- dec.sim(truep, dt$table, start.level = 2, nsim = 1000)
```
The following command loads a sample scenarios list in `tsdf` package :
```{r}
test.file <- system.file("extdata", "testS.csv", package = "tsdf")
```
Run simulations using `sl.sim` :
```{r}
out2 <- sl.sim(dt$table, test.file)
```
`out1` and `out2` are both `dec.sim` class object. `out2` is also a class of `sl.sim` when the scenarios is more than 2. S3 method `summary` and `plot` are availiale for this class. For example, a summary of commonly used statistics is reported if we use the `summary` function :
```{r}
# target toxicity 
pt <- c(0.3, 0.4)
summary(out2, pt)
```
There are four different type of plots for `dec.sim` object where option `s` indicates the number of scenario you want to plot and `pt` is the target toxicity for each scenario, see more details in `plot.dec.sim` R documentation:
```{r}
# input information (true toxicity)
plot(out2, s = 2, pt = c(0.3, 0.4), type="s")
# probability of selecting as MTD at each dose level
plot(out2, s = 2, pt = c(0.3, 0.4), type = "prob")
# average number of patients treated at each dose level
plot(out2, s = 2, pt = c(0.3, 0.4), type = "np")
# number of DLTs experienced at each dose level
plot(out2, s = 2, pt = c(0.3, 0.4), type="dlt")
```

There is a built-in function to put all different plots on same figure, simply run
```{r fig.height = 8}
plot(out2, pt = c(0.3, 0.4), type = "all", cex = 0.7)
```

## Scenarios list/customized table format
The `.csv` or `.txt` files used for `sl.sim` look like :
```{r echo=FALSE, results='asis'}
sl <- system.file("extdata", "testS.csv", package = "tsdf")
knitr::kable(read.table(sl, header = TRUE, sep = ","))
```

This example is saved under `\inst\extdata\testS.csv`, use `system.file` to load it in R. The following variables have to be included: `Start.dose` : the starting dose level; `N.trails` : the number of simulated trials; `Dose*` : true probabilities of toxicity at the dose levels. Note that users don't need put `NA` in the raw data if scenarios don't have equal number of dose levels. In the above example, the `NA` on the first row is blank in the raw `.csv` file. 

Both `dec.sim` and `sl.sim` support user-supplied decision table. It can be either  `matrix`, `data.frame` or `table` in R. There is no checking on the format of the table in `tsdf`, so users need to make sure the input is a legitimate decision table for dose-finding. Also, the column name of the table should be the actual sample size instead of the default output of `read.table` which has column names `X.*` or `V.*`. For example, the following command reads the sample decision table in the package : 
```{r, warning=FALSE}
table.file <- system.file("extdata", "decTable.csv", package = "tsdf")
dec <- read.table(table.file, sep = ",", col.names = c(3,4,8,10), row.names = 1, check.names = FALSE)
colnames(dec)
```

Although there are many ways to import a decision table from `.csv` or `.txt` files, a typical decision table used for `dev.sim` and `sl.sim` functions have to have the following format when it's loaded in R:  
```{r, echo=FALSE}
knitr::kable(dec)
```