---
title: "Overview of trialr"
author: "Kristian Brock"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
bibliography: library.bib
vignette: >
  %\VignetteIndexEntry{Overview of trialr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`trialr` is a collection of Bayesian clinical trial designs implemented in Stan and R.

Many Bayesian experimental designs for clinical trials have been published.
However, one of the factors that has constrained their adoption is availability of software.
We present here some of the most notable, implemented and demonstrated in a consistent style, leveraging the powerful Stan environment.

Often authors of trial designs make available code with their publication.
There are also some fantastic packages that aid the use of certain designs.
However, challenges to use still persist.
The disparate methods are naturally presented in a style that appeals to the particular author.
Features implemented in one package for one design may be missing in another.
Sometimes the technology chosen may only be available on one particular operating system, or the chosen technology may have fallen into disuse.

`trialr` seeks to address these problems.
Models are specified in [Stan](http://mc-stan.org/), a state-of-the-art environment for Bayesian analysis.
It uses Hamiltonian Monte Carlo to take samples from the posterior distribution.
This method is more efficient than Gibbs sampling, for instance, and reliable inference can generally be performed on a few thousand posterior samples.
R, Stan and `trialr` are each available on Mac, Linux, and Windows, so all of the examples presented here should work on each operating system.
Furthermore, Stan offers a very simple method to split the sampling across _n_ cores, taking advantage of modern multicore processors.

The designs implemented in `trialr` are introduced briefly below, and developed more fully in vignettes.
We focus on practical usage, including:

- fitting models to observed data using your prior;
- processing posterior samples to produce useful inferences;
- and visualising inferences using modern `ggplot` graphics.

# Examples
In all examples, we will need to load `trialr`

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

## CRM
The Continual Reassessment Method (CRM) was first published by O'Quigley _et al._ (1990).
It assumes a smooth mathematical form for the dose-toxicity curve to conduct a dose-finding trial seeking a maximum tolerable dose.
There are many variations to suit different clinical scenarios and the design has enjoyed relatively common use (although nowhere near as common as the ubiquitous and inferior 3+3 design).

We will demonstrate the method using a notional trial example.
In a scenario of five potential doses, let us assume that we seek the dose with probability of toxicity closest to 25% where our prior guesses of the rates of toxicity can be represented:

```{r}
target <- 0.25
skeleton <- c(0.05, 0.15, 0.25, 0.4, 0.6)
```

Let us assume that we have already treated 2 patients each at doses 2, 3 and 4, having only seen toxicity at dose-level 4.
What dose should we give to the next patient or cohort?
We can fit the data to the popular _empiric_ model:

```{r, results = "hide", warning=FALSE, message=FALSE}
mod1 <- stan_crm(outcome_str = '2NN 3NN 4TT', skeleton = skeleton, 
                 target = target, model = 'empiric', beta_sd = sqrt(1.34), 
                 seed = 123)
```

The fitted model contains lots of useful of information:
```{r}
mod1
```

We see that dose-level 2 is the dose that the model recommends to be given to the next cohort.
```{r}
mod1$recommended_dose
```

All manner of interested visualisation is facilitated by the MCMC samples.
The following plot simply shows the posterior expected probability of toxicity at each dose.
```{r, fig.width=7, fig.height=7}
library(ggplot2)
plot_df = data.frame(DoseLevel = 1:length(skeleton),
                     ProbTox = mod1$prob_tox)
ggplot(plot_df, aes(x = DoseLevel, y = ProbTox)) +
  geom_point() + geom_line() + ylim(0, 1) + 
  geom_hline(yintercept = target, col = 'orange', linetype = 'dashed') +
  labs(title = 'Posterior dose-toxicity curve under empiric CRM model')
```
Confirmation that dose-level 2 is predicted to be closest to the target toxicity rate, although dose 3 is also close.

Several variants of the CRM [are implemented in 'trialr'](https://brockk.github.io/trialr/articles/CRM.html).
Further visualisation techniques are demonstrated in the [Visualisation in CRM](https://brockk.github.io/trialr/articles/CRM-visualisation.html) vignette.



## EffTox
EffTox by Thall & Cook (2004) is a dose-finding design that uses binary efficacy and toxicity outcomes to select a dose with a high utility score. 
We present it briefly here but there is a much more thorough examination in the [EffTox vignette](https://brockk.github.io/trialr/articles/EffTox.html).

For demonstration, we fit the model parameterisation introduced by Thall _et al._ (2014) to the following notional outcomes:

| Patient | Dose-level | Toxicity | Efficacy |
|:-------:|:----------:|:--------:|:--------:|
|    1    |      1     |     0    |     0    |
|    2    |      1     |     0    |     0    |
|    3    |      1     |     0    |     1    |
|    4    |      2     |     0    |     1    |
|    5    |      2     |     0    |     1    |
|    6    |      2     |     1    |     1    |

```{r, results = "hide"}
outcomes <- '1NNE 2EEB'
mod2 <- stan_efftox_demo(outcomes, seed = 123)
```

```{r}
mod2
```

In this instance, after evaluation of our six patients, the dose advocated for the next group is dose-level 3.
This is contained in the fitted object:

```{r}
mod2$recommended_dose
```

This is not surprising because dose 3 has the highest utility score:

```{r}
mod2$utility
```

Sometimes, doses other than the maximal-utility dose will be recommended because of the dose-admissibility rules. 
See the papers or the [EffTox vignette](https://brockk.github.io/trialr/articles/EffTox.html) for more details. 

Functions are provided to create useful plots. 
For instance, it is illuminating to plot the posterior means of the probabilities of efficacy and toxicity at each of the doses on the trade-off contours.
The five doses are shown in red. Doses closer to the lower-right corner have higher utility. 

```{r, fig.width=7, fig.height=7}
efftox_contour_plot(mod2)
title('EffTox utility contours')
```

This example continues in the [EffTox vignette](https://brockk.github.io/trialr/articles/EffTox.html).

There are many publications related to EffTox but the two most important are @Thall2004 and @Thall2014.



## Hierachical analysis of response in related cohorts
Sticking with Peter Thall's huge contribution to Bayesian clinical trials, @Thall2003 described a method for analysing treatment effects of a single intervention in several sub-types of a single disease.
The method uses a simple hierarchical model with binary response variable and population-level and group-level intercepts.

They demonstrate the method for partially-pooling response rates to a single drug in various subtypes of sarcoma.
We pass to Stan the sizes of the subgroups and the number of responses seen in each group.
We also provide prior hyperparameters.
Reproducing their example:

```{r, results = "hide"}
mod3 <- stan_hierarchical_response_thall(
  group_responses = c(0, 0, 1, 3, 5, 0, 1, 2, 0, 0), 
  group_sizes = c(0, 2 ,1, 7, 5, 0, 2, 3, 1, 0), 
  mu_mean = -1.3863,
  mu_sd = sqrt(1 / 0.1),
  tau_alpha = 2,
  tau_beta = 20)
```

```{r}
mod3
```

We may visualise these inferences on the partially-pooled response rates in the subgroups:
```{r, fig.width=7, fig.height=7, warning=FALSE, message=FALSE}
rstan::plot(mod3, pars = 'prob_response') + 
  geom_vline(xintercept = 0.3, col = 'orange', linetype = 'dashed') +
  labs(title = 'Partially-pooled analysis of response rate in 10 sarcoma subtypes')
```
By default, plot methods are passed onwards to `rstan`.

The hierarchical model for binary responses is developed in [its own vignette](https://brockk.github.io/trialr/articles/HierarchicalBayesianResponse.html).

## BEBOP in PePS2
@Thall2008 introduced an extension of EffTox that allows dose-finding by efficacy and toxicity outcomes and adjusts for covariate information.
Brock, et al. simplified the method by removing the dose-finding components to leave a design that studies associated co-primary and toxicity outcomes in an arbitrary number of cohorts determined by the basline covariates.
They originally refered to the simplifed design as BEBOP, for _Bayesian Evaluation of Bivariate binary Outcomes with Predictive variables_.
This name was later changed to P2TNE for _Phase 2 Thall, Nguyen & Estey_ to reflect its pedigree.

The design was implemented in a phase II trial of pembrolizumab in non-small-cell lung cancer called PePS2.
A distinct feature of the trial is the availability of predictive baseline covariates, the most notwworthy of which is the PD-L1 tumour proportion score, shown by @Garon2015 to be a predictive biomarker.

This example is demonstrated in the [BEBOP vignette](https://brockk.github.io/trialr/articles/BEBOP.html).



# References

