simulate_trials: Simulate trials defined via package 'escalation'

In precautionary: Safety Diagnostics for Dose-Escalation Trial Designs

Description

An S4 generic method providing a more abstract interface to trial simulation than the simulate_trials function of package escalation. This abstraction is needed to support simulations in which escalation's simple vectors of ‘true toxicity probabilities’ are replaced by precautionary's more realistic toxicity-distribution generators.

Usage

simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

## S4 method for signature 
## 'selector_factory,numeric,hyper_mtdi_distribution,ANY'
simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

## S4 method for signature 'selector_factory,numeric,mtdi_distribution,ANY'
simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

## S4 method for signature 'exact,missing,mtdi_distribution,ANY'
simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

## S4 method for signature 'exact,numeric,mtdi_distribution,missing'
simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

## S4 method for signature 'exact,numeric,hyper_mtdi_distribution,missing'
simulate_trials(
  selector_factory,
  num_sims,
  true_prob_tox,
  true_prob_eff = NULL,
  ...
)

Arguments

selector_factory	An object of S3 class selector_factory
num_sims	Number of simulations to run
true_prob_tox	A generator of toxicity distributions
true_prob_eff	Provided for compatibility with simulate_trials
...	Passed to subroutines

Details

If invoked interactively with num_sims > 10, then a txtProgressBar is displayed in the console. The condition on num_sims has the useful side effect of allowing this function to be invoked iteratively by extend (with num_sims = 10) without the nuisance of nested progress bars.

Examples

old <- options(dose_levels = c(0.5, 1, 2, 4, 6, 8))
mtdi_gen <- hyper_mtdi_lognormal(CV = 1
                                 , median_mtd = 6, median_sdlog = 0.5
                                 , units="mg/kg")
num_sims <- ifelse(interactive()
, 300
, 15 # avoid taxing CRAN servers
)
hsims <- get_three_plus_three(num_doses = 6,
                              allow_deescalate = TRUE) %>%
  simulate_trials(
    num_sims = num_sims
  , true_prob_tox = mtdi_gen)
summary(hsims, ordinalizer=NULL) # vanilla summary with binary toxicity
summary(hsims, ordinalizer = function(dose, r0 = sqrt(2))
  c(Gr1=dose/r0^2, Gr2=dose/r0, Gr3=dose, Gr4=dose*r0, Gr5=dose*r0^2)
)
hsims <- hsims %>% extend(num_sims = num_sims)
summary(hsims, ordinalizer = function(dose, r0 = sqrt(2))
  c(Gr1=dose/r0^2, Gr2=dose/r0, Gr3=dose, Gr4=dose*r0, Gr5=dose*r0^2)
)$safety
# Set a CRM skeleton from the average probs in above simulation
num_sims <- ifelse(interactive()
, 16
,  4  # avoid taxing CRAN servers
)
get_dfcrm(skeleton = hsims$avg_prob_tox
         ,target = 0.25
         ) %>% stop_at_n(n = 24) %>%
  simulate_trials(
    num_sims = num_sims
  , true_prob_tox = mtdi_gen
  ) -> crm_hsims
summary(crm_hsims
, ordinalizer = function(MTDi, r0 = sqrt(2))
    MTDi * r0^c(Gr1=-2, Gr2=-1, Gr3=0, Gr4=1, Gr5=2)
)
options(old)
old <- options(dose_levels = c(2, 6, 20, 60, 180, 400))
mtdi_dist <- mtdi_lognormal(CV = 0.5
                           ,median = 140
                           ,units = "ng/kg/week")
num_sims <- ifelse(interactive()
, 100
,  10  # avoid taxing CRAN servers
)
sims <- get_three_plus_three(num_doses = 6) %>%
  simulate_trials(
    num_sims = num_sims
  , true_prob_tox = mtdi_dist)
# Now set a proper ordinalizer via options():
options(ordinalizer = function(dose, r0) {
  c(Gr1=dose/r0^2, Gr2=dose/r0, Gr3=dose, Gr4=dose*r0, Gr5=dose*r0^2)
})
summary(sims, r0=2)
# Set a CRM skeleton from the average probs in above simulation
get_dfcrm(skeleton = sims$true_prob_tox
         ,target = 0.25
         ) %>% stop_at_n(n = 24) %>%
  simulate_trials(
    num_sims = 20
  , true_prob_tox = mtdi_dist
  ) -> crm_sims
summary(crm_sims
, ordinalizer = function(MTDi, r0 = sqrt(2))
    MTDi * r0^c(Gr1=-2, Gr2=-1, Gr3=0, Gr4=1, Gr5=2)
)
if (interactive()) { # don't overtax CRAN servers
crm_sims <- crm_sims %>% extend(target_mcse = 0.1)
summary(crm_sims
, ordinalizer = function(MTDi, r0 = sqrt(2))
    MTDi * r0^c(Gr1=-2, Gr2=-1, Gr3=0, Gr4=1, Gr5=2)
)$safety
}
options(old)
old <- options(
  dose_levels = c(0.5, 1, 2, 4, 6),
  ordinalizer = function(MTDi, r0 = 1.5) {
    MTDi * r0 ^ c(Gr1=-2, Gr2=-1, Gr3=0, Gr4=1, Gr5=2)
  })
mtdi_dist <- mtdi_lognormal(CV = 2
                            ,median = 5
                            ,units = "mg/kg")
design <- get_three_plus_three(num_doses = 5, allow_deescalate = TRUE)
# Note use of wrapper function 'exact'; see ?precautionary::exact.
exact(design) %>% simulate_trials(true_prob_tox = mtdi_dist) -> EXACT
stopifnot(all.equal(1, sum(exp(EXACT$log_pi))))
summary(EXACT)$safety
if (interactive()) { # don't overtax CRAN servers
# Compare with result of discrete-event simulation
design %>% simulate_trials(
  num_sims = 200
  , true_prob_tox = mtdi_dist
) -> SIMS
summary(SIMS)$safety
}
options(old)
old <- options(dose_levels = c(0.5, 1, 2, 4, 6, 8))
mtdi_gen <- hyper_mtdi_lognormal(CV = 1
                                 , median_mtd = 6, median_sdlog = 0.5
                                 , units="mg/kg")
options(ordinalizer = function(dose, r0 = sqrt(2))
  c(Gr1=dose/r0^2, Gr2=dose/r0, Gr3=dose, Gr4=dose*r0, Gr5=dose*r0^2)
)
design <- get_three_plus_three(num_doses = 6, allow_deescalate = TRUE)
ehsims <- simulate_trials(
  exact(design)
  , num_sims = 50
  , true_prob_tox = mtdi_gen
)
summary(ehsims)$safety
options(old)

precautionary documentation built on Aug. 9, 2021, 9:14 a.m.