Using escalation

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

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.

library(escalation)
#> Loading required package: magrittr
model <- get_boin(num_doses = 5, target = 0.3)
fit <- model %>% fit('1NN 2NN 3NT 2NT')

Supported Interface

Target toxicity rate:

tox_target(fit)
#> [1] 0.3

The number of patients treated:

num_patients(fit)
#> [1] 8

Cohort IDs for the treated patients:

cohort(fit)
#> [1] 1 1 2 2 3 3 4 4

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:

doses_given(fit)
#> [1] 1 1 2 2 3 3 2 2

Bits representing whether toxicity event was observed:

tox(fit)
#> [1] 0 0 0 0 0 1 0 1

The total number of toxicities seen at all doses combined:

num_tox(fit)
#> [1] 2

A data-frame containing the above information:

model_frame(fit)
#> # A tibble: 8 × 5
#>   patient cohort  dose   tox weight
#>     <int>  <int> <int> <int>  <dbl>
#> 1       1      1     1     0      1
#> 2       2      1     1     0      1
#> 3       3      2     2     0      1
#> 4       4      2     2     0      1
#> 5       5      3     3     0      1
#> 6       6      3     3     1      1
#> 7       7      4     2     0      1
#> 8       8      4     2     1      1

The number of doses under investigation:

num_doses(fit)
#> [1] 5

The indices of the dose-levels under investigation:

dose_indices(fit)
#> [1] 1 2 3 4 5

plus textual representations of the dose-levels under investigation:

dose_strings(fit)
#> [1] "1" "2" "3" "4" "5"

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:

recommended_dose(fit)
#> [1] 2

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:

continue(fit)
#> [1] TRUE

We infer from this that no stopping condition has yet been triggered.

The number of patients treated at each dose:

n_at_dose(fit)
#> [1] 2 4 2 0 0

The number of patients treated at the recommended dose:

n_at_recommended_dose(fit)
#> [1] 4

The proportion of patients treated at each dose:

prob_administer(fit)
#>    1    2    3    4    5 
#> 0.25 0.50 0.25 0.00 0.00

The total number of toxicities seen at each dose:

tox_at_dose(fit)
#> [1] 0 1 1 0 0

The empirical toxicity rate, i.e. the number of toxicities divided by the number of patients:

empiric_tox_rate(fit)
#> [1] 0.00 0.25 0.50  NaN  NaN

The model-derived expected toxicity rate at each dose:

mean_prob_tox(fit)
#> [1] 0.02 0.26 0.50   NA   NA

The BOIN design makes no estimate for doses it has not yet administered.

The model-derived median toxicity rate at each dose:

median_prob_tox(fit)
#>    1    2    3    4    5 
#> 0.01 0.21 0.50   NA   NA

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:

prob_tox_quantile(fit, 0.9)
#>    1    2    3    4    5 
#> 0.05 0.54 0.89   NA   NA

BOIN does not calculate this either. It could also be added.

The posterior probability that the toxicity rate exceeds some threshold value, here 50%:

prob_tox_exceeds(fit, 0.5)
#> [1] 0.009391185 0.129051871 0.500000000          NA          NA

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:

supports_sampling(fit)
#> [1] FALSE

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:

print(fit)
#> Patient-level data:
#> # A tibble: 8 × 5
#>   Patient Cohort  Dose   Tox Weight
#>     <int>  <int> <int> <int>  <dbl>
#> 1       1      1     1     0      1
#> 2       2      1     1     0      1
#> 3       3      2     2     0      1
#> 4       4      2     2     0      1
#> 5       5      3     3     0      1
#> 6       6      3     3     1      1
#> 7       7      4     2     0      1
#> 8       8      4     2     1      1
#> 
#> Dose-level data:
#> # A tibble: 6 × 8
#>   dose     tox     n empiric_tox_rate mean_prob_tox median_prob_tox admissible
#>   <ord>  <dbl> <dbl>            <dbl>         <dbl>           <dbl> <lgl>     
#> 1 NoDose     0     0             0             0               0    TRUE      
#> 2 1          0     2             0             0.02            0.01 TRUE      
#> 3 2          1     4             0.25          0.26            0.21 TRUE      
#> 4 3          1     2             0.5           0.5             0.5  TRUE      
#> 5 4          0     0           NaN            NA              NA    TRUE      
#> 6 5          0     0           NaN            NA              NA    TRUE      
#> # ℹ 1 more variable: recommended <lgl>
#> 
#> The model targets a toxicity level of 0.3.
#> The model advocates continuing at dose 2.
summary(fit)
#> # A tibble: 6 × 8
#>   dose     tox     n empiric_tox_rate mean_prob_tox median_prob_tox admissible
#>   <ord>  <dbl> <dbl>            <dbl>         <dbl>           <dbl> <lgl>     
#> 1 NoDose     0     0             0             0               0    TRUE      
#> 2 1          0     2             0             0.02            0.01 TRUE      
#> 3 2          1     4             0.25          0.26            0.21 TRUE      
#> 4 3          1     2             0.5           0.5             0.5  TRUE      
#> 5 4          0     0           NaN            NA              NA    TRUE      
#> 6 5          0     0           NaN            NA              NA    TRUE      
#> # ℹ 1 more variable: recommended <lgl>

and cast it to a tidyverse tibble:

library(tibble)
#> Warning: package 'tibble' was built under R version 4.3.3

as_tibble(fit)
#> # A tibble: 6 × 8
#>   dose     tox     n empiric_tox_rate mean_prob_tox median_prob_tox admissible
#>   <ord>  <dbl> <dbl>            <dbl>         <dbl>           <dbl> <lgl>     
#> 1 NoDose     0     0             0             0               0    TRUE      
#> 2 1          0     2             0             0.02            0.01 TRUE      
#> 3 2          1     4             0.25          0.26            0.21 TRUE      
#> 4 3          1     2             0.5           0.5             0.5  TRUE      
#> 5 4          0     0           NaN            NA              NA    TRUE      
#> 6 5          0     0           NaN            NA              NA    TRUE      
#> # ℹ 1 more variable: recommended <lgl>