This is a core class in this package. It encapsulates that an object (e.g. a CRM model, a 3+3 model) is able to recommend doses, keep track of how many patients have been treated at what doses, what toxicity outcomes have been seen, and whether a trial should continue. It offers a consistent interface to many dose-finding methods, including CRM, TPI, mTPI, BOIN, EffTox, 3+3, and more.

Once you have a standardised interface, modularisation offers a powerful way to adorn dose-finding methods with extra desirable behaviour. selector objects can be daisy-chained togther using magrittr's pipe operator. For instance, the CRM fitting method in dfcrm is fantastic because it runs quickly and is simple to call. However, it does not recommend that a trial stops if a dose is too toxic or if n patients have already been treated at the recommended dose. Each of these behaviours can be bolted on via additional selectors. Furthermore, those behaviours and more can be bolted on to any dose selector because of the modular approach implemented in escalation. See Examples.

selector objects are obtained by calling the fit function on a selector_factory object. A selector_factory object is obtained by initially calling a function like get_dfcrm, get_three_plus_three or get_boin. Users may then add desired extra behaviour with subsequent calls to functions like stop_when_n_at_dose or stop_when_too_toxic.

The selector class also supports that an object will be able to perform inferential calculations on the rates of toxicity via functions like mean_prob_tox, median_prob_tox, and prob_tox_exceeds. However, naturally the sophistication of those calculations will vary by model implementation. For example, a full MCMC method will be able to quantify any probability you like by working with posterior samples. In contrast, a method like the crm function in dfcrm that uses the plug-in method to estimate posterior dose-toxicity curves cannot natively estimate the median probability of tox.

selector()

Details

Every selector object implements the following functions:

Some selectors also add:

See also

Examples

# Start with a simple CRM model skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6) target <- 0.25 model1 <- get_dfcrm(skeleton = skeleton, target = target) # Add a rule to stop when 9 patients are treated at the recommended dose model2 <- get_dfcrm(skeleton = skeleton, target = target) %>% stop_when_n_at_dose(n = 9, dose = 'recommended') # Add a rule to stop if toxicity rate at lowest dose likely exceeds target model3 <- get_dfcrm(skeleton = skeleton, target = target) %>% stop_when_n_at_dose(n = 9, dose = 'recommended') %>% stop_when_too_toxic(dose = 1, tox_threshold = target, confidence = 0.5) # We now have three CRM models that differ in their stopping behaviour. # Let's fit each to some outcomes to see those differences: outcomes <- '1NNN 2NTT 1NNT' fit1 <- model1 %>% fit(outcomes) fit2 <- model2 %>% fit(outcomes) fit3 <- model3 %>% fit(outcomes) fit1 %>% recommended_dose()
#> [1] 1
fit1 %>% continue()
#> [1] TRUE
fit2 %>% recommended_dose()
#> [1] 1
fit2 %>% continue()
#> [1] TRUE
fit3 %>% recommended_dose()
#> [1] NA
fit3 %>% continue()
#> [1] FALSE
# Already model3 wants to stop because of excessive toxicity. # Let's carry on with models 1 and 2 by adding another cohort: outcomes <- '1NNN 2NTT 1NNT 1NNN' fit1 <- model1 %>% fit(outcomes) fit2 <- model2 %>% fit(outcomes) fit1 %>% recommended_dose()
#> [1] 1
fit1 %>% continue()
#> [1] TRUE
fit2 %>% recommended_dose()
#> [1] 1
fit2 %>% continue()
#> [1] FALSE
# Model1 wants to continue - in fact it will never stop. # In contrast, model2 has seen 9 at dose 1 so, rather than suggest dose 1 # again, it suggests the trial should stop. # For contrast, let us consider a BOIN model on the same outcomes boin_fitter <- get_boin(num_doses = length(skeleton), target = target) fit4 <- boin_fitter %>% fit(outcomes) fit4 %>% recommended_dose()
#> [1] 2
fit4 %>% continue()
#> [1] TRUE
# Full selector interface: fit <- fit2 fit %>% tox_target()
#> [1] 0.25
fit %>% num_patients()
#> [1] 12
fit %>% cohort()
#> [1] 1 1 1 2 2 2 3 3 3 4 4 4
fit %>% doses_given()
#> [1] 1 1 1 2 2 2 1 1 1 1 1 1
fit %>% tox()
#> [1] 0 0 0 0 1 1 0 0 1 0 0 0
fit %>% num_tox()
#> [1] 3
fit %>% model_frame()
#> # A tibble: 12 x 4 #> patient cohort dose tox #> <int> <int> <int> <int> #> 1 1 1 1 0 #> 2 2 1 1 0 #> 3 3 1 1 0 #> 4 4 2 2 0 #> 5 5 2 2 1 #> 6 6 2 2 1 #> 7 7 3 1 0 #> 8 8 3 1 0 #> 9 9 3 1 1 #> 10 10 4 1 0 #> 11 11 4 1 0 #> 12 12 4 1 0
fit %>% num_doses()
#> [1] 5
fit %>% dose_indices()
#> [1] 1 2 3 4 5
fit %>% recommended_dose()
#> [1] 1
fit %>% continue()
#> [1] FALSE
fit %>% n_at_dose()
#> [1] 9 3 0 0 0
#> [1] 9
fit %>% is_randomising()
#> [1] FALSE
fit %>% prob_administer()
#> 1 2 3 4 5 #> 0.75 0.25 0.00 0.00 0.00
fit %>% tox_at_dose()
#> [1] 1 2 0 0 0
fit %>% empiric_tox_rate()
#> [1] 0.1111111 0.6666667 NaN NaN NaN
fit %>% mean_prob_tox()
#> [1] 0.2069561 0.2979677 0.4824122 0.6176620 0.7644430
fit %>% median_prob_tox()
#> [1] 0.2069561 0.2979677 0.4824122 0.6176620 0.7644430
fit %>% dose_admissible()
#> [1] TRUE TRUE TRUE TRUE TRUE
fit %>% prob_tox_quantile(0.9)
#> [1] 0.3649670 0.4608277 0.6272346 0.7346974 0.8420860
fit %>% prob_tox_exceeds(0.5)
#> [1] 0.009230096 0.054695783 0.442521884 0.851725376 0.996745367
#> [1] TRUE
fit %>% prob_tox_samples()
#> # A tibble: 4,000 x 6 #> .draw `1` `2` `3` `4` `5` #> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> #> 1 1 0.294 0.391 0.568 0.688 0.812 #> 2 2 0.154 0.237 0.420 0.564 0.727 #> 3 3 0.237 0.331 0.514 0.644 0.782 #> 4 4 0.300 0.397 0.573 0.692 0.815 #> 5 5 0.168 0.254 0.438 0.580 0.738 #> 6 6 0.360 0.456 0.623 0.732 0.840 #> 7 7 0.163 0.248 0.432 0.574 0.734 #> 8 8 0.176 0.263 0.448 0.588 0.744 #> 9 9 0.178 0.266 0.450 0.590 0.745 #> 10 10 0.353 0.449 0.618 0.727 0.837 #> # … with 3,990 more rows