---
title: "Using escalation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using escalation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The `escalation` package by Kristian Brock.
Documentation is hosted at https://brockk.github.io/escalation/

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


## Introduction

To provide dose selection decisions, the `escalation` package daisy-chains together objects that support a common interface, each deriving from type `selector`.
This vignette demonstrates the entire interface supported by `selector` objects.
For the purpose of illustration, we use a BOIN selector but the same functions will work on every type of dose selector in `escalation`.

```{r setup}
library(escalation)
```

```{r}
model <- get_boin(num_doses = 5, target = 0.3)
fit <- model %>% fit('1NN 2NN 3NT 2NT')
```

## Supported Interface

Target toxicity rate:
```{r}
tox_target(fit)
```

The number of patients treated:
```{r}
num_patients(fit)
```

Cohort IDs for the treated patients:
```{r}
cohort(fit)
```
The code infers from the spaces in the outcome string that a dose-decision was made after the second, fourth, and sixth patients.

Integers representing the dose-levels given:
```{r}
doses_given(fit)
```

Bits representing whether toxicity event was observed:
```{r}
tox(fit)
```

The total number of toxicities seen at all doses combined:
```{r}
num_tox(fit)
```

A data-frame containing the above information:
```{r}
model_frame(fit)
```

The number of doses under investigation:
```{r}
num_doses(fit)
```

The indices of the dose-levels under investigation:
```{r}
dose_indices(fit)
```

plus textual representations of the dose-levels under investigation:
```{r}
dose_strings(fit)
```
In this monotherapy setting, these textual representations offer little more than the integer dose-indices.
However, in subsequent articles we will see the value of the dose_strings as a succinct way to represent doses in treatment combination dose-finding trials.

The dose-level recommended for the next patient:
```{r}
recommended_dose(fit)
```
After seeing some toxicity at doses 2 and 3, the design sensibly sticks at dose 2 for the time being.

A logical value for whether accrual should continue:
```{r}
continue(fit)
```
We infer from this that no stopping condition has yet been triggered.

The number of patients treated at each dose:
```{r}
n_at_dose(fit)
```

The number of patients treated at the recommended dose:
```{r}
n_at_recommended_dose(fit)
```

The proportion of patients treated at each dose:
```{r}
prob_administer(fit)
```

The total number of toxicities seen at each dose:
```{r}
tox_at_dose(fit)
```

The empirical toxicity rate, i.e. the number of toxicities divided by the number of patients:
```{r}
empiric_tox_rate(fit)
```

The model-derived expected toxicity rate at each dose: 
```{r}
mean_prob_tox(fit)
```
The BOIN design makes no estimate for doses it has not yet administered.

The model-derived median toxicity rate at each dose: 
```{r}
median_prob_tox(fit)
```
BOIN does not actually calculate posterior median estimates.
Sometimes it will be necessary to return missing values if functionality is not supported by a model.
Median estimates could be added to the BOIN class in due course.

The model-derived quantile of the toxicity rate at each dose: 
```{r}
prob_tox_quantile(fit, 0.9)
```
BOIN does not calculate this either.
It could also be added.

The posterior probability that the toxicity rate exceeds some threshold value, here 50%:
```{r}
prob_tox_exceeds(fit, 0.5)
```
Once again, no estimate is made for non-administered doses.
We see that the model estimates a trivial chance that the toxicity rate at the lowest dose exceeds 50%.

Learn if this model supports sampling from the posterior:
```{r}
supports_sampling(fit)
```

The BOIN model does not support sampling.
If it did, we could run `prob_tox_samples(fit)`.

We can also call some standard generic functions:

```{r}
print(fit)
```

```{r}
summary(fit)
```

and cast it to a tidyverse `tibble`:

```{r}
library(tibble)

as_tibble(fit)
```