### Example: EffTox Efficacy and Toxicity Priors (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/prob_tox_samples.html

Illustrates setting up priors for an EffTox (Efficacy and Toxicity) model using `efftox_priors` from the `trialr` package. This is a precursor to fitting an EffTox model and subsequently sampling probabilities.

```r
efftox_priors <- trialr::efftox_priors
p <- efftox_priors(alpha_mean = -7.9593, alpha_sd = 3.5487,
                   beta_mean = 1.5482, beta_sd = 3.5018,
                   gamma_mean = 0.7367, gamma_sd = 2.5423,
                   zeta_mean = 3.4181, zeta_sd = 2.4406,
                   eta_mean = 0, eta_sd = 0.2,
                   psi_mean = 0, psi_sd = 1)

real_doses = c(1.0, 2.0, 4.0, 6.6, 10.0)
model <- get_trialr_efftox(real_doses = real_doses,
                           efficacy_hurdle = 0.5, toxicity_hurdle = 0.3,
                           p_e = 0.1, p_t = 0.1,
                           eff0 = 0.5, tox1 = 0.65)
```

--------------------------------

### Example: Using get_dfcrm for CRM Model Fitting (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_dfcrm.html

This R example demonstrates how to use the get_dfcrm function to initialize a CRM model. It shows fitting the model with default settings and then with a specified logistic model, and how to obtain the recommended dose based on simulated trial outcomes.

```r
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
model1 <- get_dfcrm(skeleton = skeleton, target = target)

# By default, dfcrm fits the empiric model:
outcomes <- '1NNN 2NTN'
model1 %>% fit(outcomes) %>% recommended_dose()

# But we can provide extra args to get_dfcrm that are than passed onwards to
# the call to dfcrm::crm to override the defaults. For example, if we want
# the one-parameter logistic model:
model2 <- get_dfcrm(skeleton = skeleton, target = target, model = 'logistic')
model2 %>% fit(outcomes) %>% recommended_dose()

```

--------------------------------

### Example Usage of BOIN12 Model Selector

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_boin12.html

This example demonstrates how to use the get_boin12 function to create a BOIN12 model selector and then fit it to simulated trial outcomes. It shows how to obtain the recommended dose, determine if the trial should continue, check dose admissibility, and calculate the probability of administering each dose.

```r
# Examples in Lin et al.
model <- get_boin12(num_doses = 5, phi_t = 0.35, phi_e = 0.25,
                    u2 = 40, u3 = 60, n_star = 6)
fit <- model %>% fit('1NNN 2ENT 3ETT 2EEN')
fit %>% recommended_dose()
#> [1] 2
fit %>% continue()
#> [1] TRUE
fit %>% is_randomising()
#> [1] FALSE
fit %>% dose_admissible()
#> [1]  TRUE  TRUE  TRUE FALSE FALSE
fit %>% prob_administer()
#>    1    2    3    4    5 
#> 0.25 0.50 0.25 0.00 0.00 

```

--------------------------------

### Example: Comparing BOIN12 variants with stack_sims_vert

Source: https://github.com/brockk/escalation/blob/master/docs/reference/stack_sims_vert.html

This example demonstrates how to use `stack_sims_vert` after simulating and comparing two BOIN12 variants with different stopping parameters. It shows the setup of true probabilities of toxicity and efficacy, defines the designs, runs the simulation using `simulate_compare`, and then stacks the results vertically for analysis.

```R
true_prob_tox <- c(0.05, 0.10, 0.15, 0.18, 0.45)
true_prob_eff <- c(0.40, 0.50, 0.52, 0.53, 0.53)

designs <- list(
  "BOIN12 v1" = get_boin12(num_doses = 5,
                           phi_t = 0.35, phi_e = 0.25,
                           u2 = 40, u3 = 60,
                           c_t = 0.95, c_e = 0.9) %>%
    stop_at_n(n = 36),
  "BOIN12 v2" = get_boin12(num_doses = 5,
                           phi_t = 0.35, phi_e = 0.25,
                           u2 = 40, u3 = 60,
                           c_t = 0.5, c_e = 0.5) %>%
    stop_at_n(n = 36)
)

x <- simulate_compare(
  designs,
  num_sims = 10,
  true_prob_tox,
  true_prob_eff
)

stack_sims_vert(x)
```

--------------------------------

### Example of Final Dose Selection with mTPI

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A220-mTPI.html

Demonstrates the use of `get_tpi`, `stop_at_n`, and `select_mtpi_mtd` to perform final dose selection in an mTPI design. The example shows how the trial stops and `select_mtpi_mtd` selects the recommended dose based on outcomes.

```r
model <- get_tpi(num_doses = 5, target = 0.25, k1 = 1, k2 = 1.5, 
                     exclusion_certainty = 0.95) %>%
      stop_at_n(n = 12) %>%
      select_mtpi_mtd(exclusion_certainty = 0.95)
    
outcomes <- '1NNN 2NTN 2NNN 3NTT'
model %>% fit(outcomes) %>% recommended_dose()
#> [1] 2
```

--------------------------------

### Example: mTPI2 Dose Selection with Stopping Rule in R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/select_mtpi2_mtd.html

This example demonstrates how to set up a dose-finding trial using the mTPI2 algorithm combined with a stopping rule. It initializes the mTPI2 model with specific parameters for the number of doses, target toxicity, and exclusion certainty, then applies a stopping rule based on the maximum sample size.

```r
# This class is intended to make the final dose selection in a mTPI2 trial:
target <- 0.25
model <- get_mtpi2(num_doses = 5, target = target,
                   epsilon1 = 0.05, epsilon2 = 0.05,
                   exclusion_certainty = 0.95) %>%
  stop_at_n(n = 12) %>%
```

--------------------------------

### Example: Crystallising and Analyzing Dose Paths (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/crystallised_dose_paths.html

This example demonstrates the usage of `crystallised_dose_paths`. It first generates dose paths using `get_three_plus_three` and `get_dose_paths`, then crystallizes these paths with provided toxicity probabilities using `calculate_probabilities`, and finally calculates the probability of recommending each dose at the terminal nodes.

```r
# Calculate dose paths for the first three cohorts in a 3+3 trial of 5 doses:
paths <- get_three_plus_three(num_doses = 5) %>%
  get_dose_paths(cohort_sizes = c(3, 3, 3))

# Set the true probabilities of toxicity
true_prob_tox <- c(0.12, 0.27, 0.44, 0.53, 0.57)
# Crytallise the paths with the probabilities of toxicity
x <- paths %>% calculate_probabilities(true_prob_tox)
# And then examine, for example, the probabilities of recommending each dose
# at the terminal nodes of these paths:
prob_recommend(x)

```

--------------------------------

### Get BOIN Dose Recommendation with Escalation Package

Source: https://context7.com/brockk/escalation/llms.txt

Illustrates the use of the Bayesian Optimal Interval Design (BOIN) in the 'escalation' R package. This design does not require a dose-toxicity skeleton and uses escalation/de-escalation boundaries. The example shows fitting the model, getting dose recommendations, and checking trial continuation, including handling overdose scenarios.

```r
library(escalation)

# Create BOIN model with 5 doses and 25% target toxicity
model <- get_boin(num_doses = 5, target = 0.25)

# Fit to outcomes
fit <- model %>% fit('1NNN 2NTN 2NNN')

# Get recommendation
fit %>% recommended_dose()

fit %>% continue()

# BOIN has native stopping rules - all doses too toxic
toxic_fit <- model %>% fit('1TTT')
toxic_fit %>% continue()

toxic_fit %>% recommended_dose()

# Check dose admissibility
fit %>% dose_admissible()

# Customize boundary parameters
model_custom <- get_boin(num_doses = 5, target = 0.25,
                          p.saf = 0.3 * 0.25, p.tox = 1.7 * 0.25)
model_custom %>% fit('1NNN 2NNT') %>% recommended_dose()
```

--------------------------------

### Example: Using try_rescue_dose with dfcrm

Source: https://github.com/brockk/escalation/blob/master/docs/reference/try_rescue_dose.html

Demonstrates how to use `try_rescue_dose` in conjunction with `get_dfcrm` and `stop_when_too_toxic`. It shows two models: one that enforces trying dose 1 in at least two patients before stopping (`model1`), and another that does not (`model2`). The examples illustrate how `model1` continues even with toxic outcomes until the rescue dose condition is met, while `model2` stops earlier.

```R
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25

# Model that demands the lowest dose (dose 1) is tried in at least two patients
model1 <- get_dfcrm(skeleton = skeleton, target = target) %>%
  stop_when_too_toxic(dose = 1, tox_threshold = 0.35, confidence = 0.8) %>%
  try_rescue_dose(dose = 1, n = 2)

# Model that stops for excess toxicity without trying dose 1
model2 <- get_dfcrm(skeleton = skeleton, target = target) %>%
  stop_when_too_toxic(dose = 1, tox_threshold = 0.35, confidence = 0.8)

# Non-toxic outcomes: both models continue at sensible doses
fit1 <- model1 %>% fit('2NNN')
fit1 %>% recommended_dose()
fit1 %>% continue()

fit2 <- model2 %>% fit('2NNN')
fit2 %>% recommended_dose()
fit2 %>% continue()

# Toxic outcomes: model1 uses dose 1 before stopping is allowed
fit1 <- model1 %>% fit('2TTT')
fit1 %>% recommended_dose()
fit1 %>% continue()

# Toxic outcomes: model2 stops despite dose 1 being untested
fit2 <- model2 %>% fit('2TTT')
fit2 %>% recommended_dose()
fit2 %>% continue()

# After dose 1 is given the requisite number of times, dose recommendation
# and stopping revert to being determined by the underlying dose selector:
fit1 <- model1 %>% fit('2TTT 1T')
fit1 %>% recommended_dose()
fit1 %>% continue()

fit1 <- model1 %>% fit('2TTT 1TT')
fit1 %>% recommended_dose()
fit1 %>% continue()
```

--------------------------------

### Get TPI/mTPI Dose Recommendation with Escalation Package

Source: https://context7.com/brockk/escalation/llms.txt

Shows how to implement Toxicity Probability Interval (TPI) and modified TPI (mTPI) designs using the 'escalation' R package. These interval-based designs partition toxicity probability space and select doses based on posterior probabilities. Examples include fitting the models and checking dose admissibility.

```r
library(escalation)

# TPI design
model_tpi <- get_tpi(num_doses = 5, target = 0.25,
                      k1 = 1, k2 = 1.5, exclusion_certainty = 0.95)

fit <- model_tpi %>% fit('1NNN 2NTN')
fit %>% recommended_dose()

# mTPI design with equivalence interval
model_mtpi <- get_mtpi(num_doses = 5, target = 0.25,
                        epsilon1 = 0.05, epsilon2 = 0.05,
                        exclusion_certainty = 0.95)

fit <- model_mtpi %>% fit('1NNN 2NTN')
fit %>% recommended_dose()

# Check probability toxicity exceeds threshold
fit %>% prob_tox_exceeds(0.35)

# Check admissible doses (not excluded for toxicity)
fit %>% dose_admissible()
```

--------------------------------

### Follow Path and Get CRM Dataframe (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_dfcrm.html

This snippet demonstrates how to use the `follow_path` and `get_dfcrm` functions to initialize a CRM model. It takes a path string and skeleton as input to retrieve the initial data frame for CRM analysis.

```r
model1 <- follow_path('1NN 2NN 3NN') %>%
  get_dfcrm(skeleton = skeleton, target = target)
```

--------------------------------

### Fit 3+3 Model with get_three_plus_three in R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_three_plus_three.html

Demonstrates how to use the `get_three_plus_three` function to create a model object and then fit it with trial data. It shows how to get the recommended dose and determine if the trial should continue based on the outcomes.

```R
model <- get_three_plus_three(num_doses = 5)

fit1 <- model %>% fit('1NNN 2NTN')
fit1 %>% recommended_dose()
#> [1] 2
fit1 %>% continue()
#> [1] TRUE

fit2 <- model %>% fit('1NNN 2NTN 2NNT')
fit2 %>% recommended_dose()
#> [1] 1
fit2 %>% continue()
#> [1] FALSE
```

--------------------------------

### Fit CRM Model and Recommend Dose (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_dfcrm.html

This snippet shows how to fit a CRM model with different outcome paths and then use `recommended_dose` to get the recommended dose. It illustrates scenarios where outcomes match, diverge, or the pre-specified path ends, leading to CRM model takeover.

```r
# If outcomes match the desired path, the path is followed further:
model1 %>% fit('1NN 2N') %>% recommended_dose()
#> [1] 2

# But when the outcomes diverge:
model1 %>% fit('1NN 2T') %>% recommended_dose()
#> [1] 1

# Or the pre-specified path comes to an end:
model1 %>% fit('1NN 2NN 3NN') %>% recommended_dose()
#> [1] 5
# The CRM model takes over.
```

--------------------------------

### BOIN12 Design Example

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A310-EfficacyToxicity.html

Demonstrates the setup and initial outcome observation for the BOIN12 design. This design partitions toxicity probabilities into intervals to guide dose selection, considering both toxicity and efficacy.

```r
library(escalation)

outcomes <- "1NNN 2EBT"

# BOIN12 requires defining toxicity intervals and target probabilities.
# For illustration, let's use example parameters.

# Target toxicity probability (e.g., 0.3)
target_toxicity <- 0.3

# Define toxicity intervals. These define the boundaries for dose decisions.
# For BOIN12, these are typically set based on clinical judgment.
# Example: Intervals could be [0, 0.1), [0.1, 0.2), [0.2, 0.3), [0.3, 0.4), [0.4, 1.0]
# The exact intervals need to be carefully chosen.
# Let's assume a simplified set of intervals for demonstration:
toxicity_intervals <- c(0.05, 0.15, 0.25, 0.35, 0.5, 0.7)

# Define the number of dose levels
num_dose_levels <- 6

# Initialize the BOIN12 design object
# The 'target' parameter is the desired toxicity probability.
# 'intervals' defines the toxicity probability intervals.
# 'num_doses' is the total number of dose levels available.
boin12_design <- boin(target = target_toxicity, intervals = toxicity_intervals, num_doses = num_dose_levels)

# Observe outcomes and update the design
# 'outcomes' string represents observed patient outcomes.
# '1NNN' means at dose 1: 1 Normal, 1 Not-evaluable, 1 Normal, 1 Normal
# '2EBT' means at dose 2: 1 Efficacy, 1 Bad-Toxicity
# This is a simplified representation; actual outcome format might differ.

# To use the outcomes string, we need to parse it and apply it to the design.
# The 'escalation' package typically handles this internally when fitting models.
# For demonstration, let's assume we have observed data structure:
# For example, if we have observed data for dose 1 and dose 2:
# dose_idx: index of the dose level (1-based)
# toxicity: 1 if toxic, 0 otherwise
# efficacy: 1 if effective, 0 otherwise

# Let's simulate some data based on the outcomes string for illustration
# Dose 1: 3 Normal, 0 Toxic (assuming NNN means no toxicity events)
# Dose 2: 1 Efficacy, 1 Toxicity (assuming EBT means one efficacy, one toxicity)

# In a real scenario, you would use a function like 'next_dose' or 'fit'
# after providing the observed outcomes to the design object.

# Example of how you might update the design (conceptual):
# updated_boin12 <- update(boin12_design, outcomes = outcomes)

# The actual process involves fitting the model with observed data.
# Let's simulate fitting for demonstration:

# Create a simulated data frame matching the outcomes string
# Dose 1: 3 patients, 0 toxicity, 0 efficacy (assuming NNN implies no tox/eff)
data_dose1 <- data.frame(dose = 1, toxicity = c(0, 0, 0), efficacy = c(0, 0, 0))
# Dose 2: 2 patients, 1 toxicity, 1 efficacy
data_dose2 <- data.frame(dose = 2, toxicity = c(1, 0), efficacy = c(1, 0))

# Combine data
observed_data <- rbind(data_dose1, data_dose2)

# Fit the BOIN12 model with the observed data
# The 'escalation' package uses a specific structure for fitting.
# Let's assume a function call like this:
# fit_result <- escalation::fit(boin12_design, data = observed_data)

# For this example, we'll just show the initialization and the outcomes string.
print("BOIN12 design initialized.")
print(paste("Observed outcomes string:", outcomes))
print("Target toxicity probability:")
print(target_toxicity)
print("Toxicity intervals:")
print(toxicity_intervals)

```

--------------------------------

### Get Dose Indices - R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A100-DoseSelectors.html

Retrieves the integer indices representing the dose-levels under investigation. These are typically sequential integers starting from 1.

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

--------------------------------

### Example Usage of get_potential_outcomes (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_potential_outcomes.html

This example demonstrates how to use the `get_potential_outcomes` function. It initializes a list of `PatientSample` objects, sets their simulated toxicity and efficacy probabilities, defines the true probabilities for different doses, and then calls the function to generate potential outcomes.

```r
num_sims <- 10
ps <- lapply(1:num_sims, function(x) PatientSample$new()) # Assuming PatientSample is a defined class

# Set tox_u and eff_u for each simulation
set.seed(2024)
lapply(1:num_sims, function(x) {
  tox_u_new <- runif(n = 20)
  eff_u_new <- runif(n = 20)
  ps[[x]]$set_eff_and_tox(tox_u = tox_u_new, eff_u = eff_u_new)
})

true_prob_tox <- c(0.05, 0.10, 0.15, 0.18, 0.45)
true_prob_eff <- c(0.40, 0.50, 0.52, 0.53, 0.53)

get_potential_outcomes(
  patient_samples = ps,
  true_prob_tox = true_prob_tox,
  true_prob_eff = true_prob_eff
)
```

--------------------------------

### Setup and Fit TITE-NBG Model in R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A280-TITE.html

This snippet demonstrates how to initialize a TITE-NBG model using predefined dose levels and model parameters. It then fits the initialized model to a dataset named 'outcomes' and prints the fitted model's summary, including patient-level and dose-level data, and the recommended dose.

```R
dose <- c(1, 2.5, 5, 10, 15, 20, 25, 30, 40, 50, 75, 100, 150, 200, 250)

model <- get_trialr_nbg_tite(
  real_doses = dose, d_star = 250, target = 0.3,
  alpha_mean = 2.15, alpha_sd = 0.84,
  beta_mean = 0.52, beta_sd = 0.8,
  seed = 2020
)

x <- model %>% fit(outcomes)

print(x)
#> Patient-level data:
#> # A tibble: 6 × 5
#>   Patient Cohort  Dose   Tox    Weight
#>     <int>  <int> <int> <int> <dbl[1d]>
#> 1       1      1     1     0       1  
#> 2       2      2     1     0       1  
#> 3       3      3     2     0       1  
#> 4       4      4     2     0       0.9
#> 5       5      5     3     1       1  
#> 6       6      6     3     0       0.5
#> 
#> Dose-level data:
#> # A tibble: 16 × 9
#>    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.0969          0.0585 TRUE      
#>  3 2          0     2              0          0.163           0.125  TRUE      
#>  4 3          1     2              0.5        0.241           0.213  TRUE      
#>  5 4          0     0            NaN          0.346           0.335  TRUE      
#>  6 5          0     0            NaN          0.420           0.419  TRUE      
#>  7 6          0     0            NaN          0.476           0.483  TRUE      
#>  8 7          0     0            NaN          0.522           0.534  TRUE      
#>  9 8          0     0            NaN          0.559           0.573  TRUE      
#> 10 9          0     0            NaN          0.618           0.636  TRUE      
#> 11 10         0     0            NaN          0.662           0.681  TRUE      
#> 12 11         0     0            NaN          0.735           0.757  TRUE      
#> 13 12         0     0            NaN          0.781           0.804  TRUE      
#> 14 13         0     0            NaN          0.834           0.858  TRUE      
#> 15 14         0     0            NaN          0.865           0.889  TRUE      
#> 16 15         0     0            NaN          0.885           0.908  TRUE      
#> # ℹ 2 more variables: recommended <lgl>, RealDose <dbl>
#> 
#> The model targets a toxicity level of 0.3.
#> The model advocates continuing at dose 4.

recommended_dose(x)
#> [1] 4
```

--------------------------------

### Set up and run clinical trial simulation in R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A230-BOIN.html

Configures a BOIN model for a clinical trial with specified doses and toxicity targets, then runs a simulation to generate operating characteristics. Requires the 'escalation' package.

```r
model <- get_boin(num_doses = 6, target = 0.25) %>\
  stop_at_n(n = 36)

true_prob_tox <- c(0.25, 0.35, 0.5, 0.6, 0.7, 0.8)
num_sims <- 50

sims <- model %>\
  simulate_trials(num_sims = num_sims, true_prob_tox = true_prob_tox)

prob_recommend(sims)
colMeans(n_at_dose(sims))
```

--------------------------------

### Example: Get Dose Paths for CRM Trial - R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/spread_paths.html

This example demonstrates how to use `get_dfcrm` and `get_dose_paths` to calculate dose-finding paths for a CRM trial. It sets up a skeleton, target toxicity, and cohort sizes, then generates the paths. This is a prerequisite for using `spread_paths`.

```r
if (FALSE) { # \dontrun{ 
# Calculate paths for the first two cohorts of three patients a CRM trial
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
cohort_sizes <- c(3, 3)
paths <- get_dfcrm(skeleton = skeleton, target = target) %>%
  get_dose_paths(cohort_sizes = cohort_sizes)
} # }
```

--------------------------------

### BOIN12 Dose-Finding Setup and Usage (R)

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A310-EfficacyToxicity.html

Sets up and uses the BOIN12 dose-finding model. It initializes the model with specific parameters, fits it to outcomes, and retrieves the recommended dose, trial continuation status, and admissible doses. It also demonstrates the use of `stop_at_n` and `select_boin12_obd` for final dose selection.

```R
b_model <- get_boin12(
  num_doses = 5, phi_t = 0.3, phi_e = 0.5, u2 = 40, u3 = 60, n_star = 6
)

b_fit <- b_model %>% fit(outcomes)

recommended_dose(b_fit)
continue(b_fit)
dose_admissible(b_fit)
```

```R
b_model2 <- get_boin12(
  num_doses = 5, phi_t = 0.3, phi_e = 0.5, u2 = 40, u3 = 60, n_star = 6
) %>%
  stop_at_n(n = 12) %>%
  select_boin12_obd()

outcomes <- '1NNN 2NTN 2NNN 3BEN'
b_model2 %>% fit(outcomes) %>% recommended_dose()
```

--------------------------------

### Example: EffTox Dose Escalation Toxicity Probability (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/prob_tox_exceeds.html

Illustrates calculating the probability that the toxicity rate exceeds a threshold using an EffTox model. The example sets up EffTox priors, defines real doses, creates the model, fits it with sample outcomes, and then uses `prob_tox_exceeds` to get the probabilities.

```R
efftox_priors <- trialr::efftox_priors
p <- efftox_priors(alpha_mean = -7.9593, alpha_sd = 3.5487,
                       beta_mean = 1.5482, beta_sd = 3.5018,
                       gamma_mean = 0.7367, gamma_sd = 2.5423,
                       zeta_mean = 3.4181, zeta_sd = 2.4406,
                       eta_mean = 0, eta_sd = 0.2,
                       psi_mean = 0, psi_sd = 1)
real_doses = c(1.0, 2.0, 4.0, 6.6, 10.0)
model <- get_trialr_efftox(real_doses = real_doses,
                               efficacy_hurdle = 0.5, toxicity_hurdle = 0.3,
                               p_e = 0.1, p_t = 0.1,
                               eff0 = 0.5, tox1 = 0.65,
                               eff_star = 0.7, tox_star = 0.25,
                               priors = p, iter = 1000, chains = 1, seed = 2020)
x <- model %>%
  fit('1N 2E 3B')
prob_tox_exceeds(x, threshold = 0.45)

```

--------------------------------

### Get Recommended Dose - R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A100-DoseSelectors.html

Determines and returns the dose-level recommended by the model for the next patient based on the observed data and the chosen design. This is the primary output for guiding the trial.

```r
recommended_dose(fit)
#> [1] 2
```

--------------------------------

### Configure and Run Dose-Finding Simulation in R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A220-mTPI.html

Sets up a dose-finding model with specific parameters (number of doses, target toxicity, stopping rules) and runs a simulation to assess operating characteristics. The simulation uses a predefined set of true toxicity probabilities and a specified number of iterations. The output provides insights into dose recommendation probabilities, administration probabilities, sample size, and toxicity counts.

```r
model <- get_mtpi(num_doses = 8, target = 0.25, 
                      epsilon1 = 0.05, epsilon2 = 0.05, 
                      exclusion_certainty = 0.95) %>%
  stop_at_n(n = 30)

num_sims <- 50

sc1 <- c(0.05, 0.25, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95)

set.seed(123)
sims <- model %>%
  simulate_trials(num_sims = num_sims, true_prob_tox = sc1, next_dose = 1)

sims
```

--------------------------------

### Follow Pre-specified Dose-Escalation Path with trialr

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_trialr_crm.html

This example demonstrates how to use an initial dose-escalation plan defined by a path string. The follow_path function initializes the plan, which is then used with get_trialr_crm. The CRM model takes over if outcomes deviate from the path or when the path ends.

```r
model1 <- follow_path('1NN 2NN 3NN') %>%
      get_trialr_crm(skeleton = skeleton, target = target, model = 'empiric',
                     beta_sd = 1.34)
    
    # If outcomes match the desired path, the path is followed further:
    model1 %>% fit('1NN 2N') %>% recommended_dose()
    #> [1] 2
    
    # But when the outcomes diverge:
    model1 %>% fit('1NN 2T') %>% recommended_dose()
    #> [1] 1
    
    # Or the pre-specified path comes to an end:
    model1 %>% fit('1NN 2NN 3NN') %>% recommended_dose()
    #> [1] 5
```

--------------------------------

### Simulate Trials with Custom Stopping - R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A700-Simulation.html

Demonstrates simulating trials using `get_dfcrm` and appending a custom stopping rule with `stop_at_n`. It also shows how to override the default simulation limit using `i_like_big_trials = TRUE` and then retrieve the number of patients simulated.

```r
sims <- get_dfcrm(skeleton = skeleton, target = target) %>%
  stop_at_n(n = 99) %>%
  simulate_trials(num_sims = 1, true_prob_tox = true_prob_tox,
                  i_like_big_trials = TRUE)

num_patients(sims)
#> [1] 99
```

--------------------------------

### Fit dfcrm Model and Get Recommended Dose in R

Source: https://github.com/brockk/escalation/blob/master/README.md

Fits a CRM model to observed outcomes and retrieves the recommended dose for the next patient. This example uses the pipe operator for a concise workflow.

```r
fit <- model %>% fit('2NNN')
recommended_dose(fit)
```

--------------------------------

### Simulate 3+3 Design Performance with Escalation Package

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A700-Simulation.html

This snippet demonstrates how to simulate the performance of the 3+3 dose-escalation design. It requires the 'escalate' package and defines true probabilities of toxicity for five doses. The simulation runs a specified number of iterations to estimate probabilities of recommendation and administration, as well as sample size.

```r
library(escalation)

true_prob_tox <- c(0.12, 0.27, 0.44, 0.53, 0.57)
num_sims <- 20

set.seed(123)
sims <- get_three_plus_three(num_doses = 5) %>%
  simulate_trials(num_sims = num_sims, true_prob_tox = true_prob_tox)

print(sims)
```

--------------------------------

### Get BOIN12 Model Selector in R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_boin12.html

The get_boin12 function initializes a dose selector object for the BOIN12 model. This model is suitable for phase I/II dose-finding studies, considering both efficacy and toxicity. It requires specifying the number of doses, toxicity and efficacy thresholds, and utility values. Optional parameters control exploration stopping criteria, certainty levels, starting dose, and prior distributions.

```r
get_boin12(
  num_doses,
  phi_t,
  phi_e,
  u1 = 100,
  u2,
  u3,
  u4 = 0,
  n_star = 6,
  c_t = 0.95,
  c_e = 0.9,
  start_dose = 1,
  prior_alpha = 1,
  prior_beta = 1,
  ...
)
```

--------------------------------

### Fit and Recommend Dose with TPI Model (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/select_tpi_mtd.html

This snippet shows how to initialize a TPI model, fit it with observed outcomes, and then recommend the next dose. It highlights the modularity of the package, allowing for dose selection at every decision point.

```r
outcomes <- '1NNN 2NTN 2NNN 3NTT'
model %>% fit(outcomes) %>% recommended_dose()
#> [1] 2

# However, since behaviour is modular in this package, we can use this method
# to select dose at every dose decision if we wanted:
model2 <- get_tpi(num_doses = 5, target = target,
                      k1 = 1, k2 = 1.5,
                      exclusion_certainty = 0.95) %>%
  select_tpi_mtd(when = 'always', exclusion_certainty = 0.95)
model2 %>% fit('1NNT') %>% recommended_dose()
#> [1] 1
model2 %>% fit('1NNN 2NNT') %>% recommended_dose()
#> [1] 1
```

--------------------------------

### Setting up a BOIN-COMB Design for Simulation in R

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A360-Combinations.html

This code snippet initializes a BOIN-COMB design for combination therapies with a specified number of doses and target toxicity. It then sets a stopping rule based on the sample size and selects the appropriate BOIN-COMB method for dose selection. This is a prerequisite for running simulations.

```r
model <- get_boin_comb(num_doses = num_doses, target = target) %>%
   stop_at_n(n = 12) %>%
   select_boin_comb_mtd()
```

--------------------------------

### Get patients per dose (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/n_at_dose.html

The `n_at_dose` function returns an integer vector representing the number of patients evaluated at each dose level. It takes an object of class `selector` as input. The example demonstrates its use after fitting a CRM model.

```R
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
outcomes <- '1NNN 2NTN'
fit <- get_dfcrm(skeleton = skeleton, target = target) %>%
  fit(outcomes)
fit %>% n_at_dose()

```

--------------------------------

### Example: CRM Toxicity Probability Samples (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/prob_tox_samples.html

Demonstrates how to obtain toxicity probability samples using the CRM (Continual Reassessment Method) design. It shows fitting a CRM model and then calling `prob_tox_samples` with both default (wide) and `tall = TRUE` arguments.

```r
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
outcomes <- '1NNN 2NTN'
fit <- get_dfcrm(skeleton = skeleton, target = target) %>%
  fit(outcomes)

# Wide format (default)
fit %>%
  prob_tox_samples()

# Tall format
fit %>%
  prob_tox_samples(tall = TRUE)
```

--------------------------------

### Calculate Dose Paths from Start of Trial (R)

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A600-DosePaths.html

Calculates and visualizes dose paths for a BOIN model from the beginning of a trial. This function, `get_dose_paths`, is used without specifying `previous_outcomes`, providing a baseline comparison to analyses that account for prior data. It also includes conditional visualization for RStudio.

```r
paths <- get_boin(num_doses = 4, target = target) %>%
  get_dose_paths(cohort_sizes = rep(3, 2))

if(Sys.getenv("RSTUDIO") == "1") {
  graph_paths(paths, viridis_palette = 'viridis')
}
```

--------------------------------

### Example: CRM Dose Escalation Toxicity Probability (R)

Source: https://github.com/brockk/escalation/blob/master/docs/reference/prob_tox_exceeds.html

Demonstrates calculating the probability that the toxicity rate at each dose exceeds a threshold plus 10% using a CRM model. It shows the setup of the skeleton, target, outcomes, fitting the model, and then applying `prob_tox_exceeds`.

```R
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
outcomes <- '1NNN 2NTN'
fit <- get_dfcrm(skeleton = skeleton, target = target) %>%
  fit(outcomes)
# What is probability that tox rate at each dose exceeds target by >= 10%?
fit %>%
  prob_tox_exceeds(threshold = target + 0.1)

```

--------------------------------

### Example: Using get_random_selector in R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/get_random_selector.html

Demonstrates how to use the `get_random_selector` function to create a dose selector model. It shows fitting the model to observed outcomes and recommending a dose, including scenarios where the random selector is preceded by a fixed dose path.

```r
prob_select = c(0.1, 0.3, 0.5, 0.07, 0.03)
model <- get_random_selector(prob_select = prob_select)
fit <- model %>% fit('1NTN')
fit %>% recommended_dose() # This is random

# Example with a preceding path
model <- follow_path('1NN 2NN 3NN') %>%
  get_random_selector(prob_select = prob_select)
fit <- model %>% fit('1NN')
fit %>% recommended_dose() # This is not-random; it comes from the path.
fit <- model %>% fit('1NN 2NT')
fit %>% recommended_dose() # This is random; the path is discarded.
```

--------------------------------

### 3+3 Design: Stick on One Toxicity (R)

Source: https://github.com/brockk/escalation/blob/master/README.md

Illustrates the behavior of a 3+3 design when encountering one toxicity. This example shows that the design will remain at the current dose level if one out of three patients experiences a toxicity. It uses `fit` to simulate outcomes and `recommended_dose` to get the dose suggestion.

```r
x <- get_three_plus_three(num_doses = 5) %>%
  fit("1NNN 2NNN 3NNT")
recommended_dose(x)
```

--------------------------------

### Fit Empiric Model with trialr

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A205-CRM.html

This code snippet shows how to fit an empiric dose-escalation model using the 'trialr' package via the 'escalation' interface. It requires the dose skeleton, target toxicity, and the beta_sd parameter for the prior distribution.

```R
model4 <- get_trialr_crm(skeleton = skeleton, target = target, model = 'empiric', 
                             beta_sd = beta_sd)
```

--------------------------------

### Get 3+3 Dose Recommendation with Escalation Package

Source: https://context7.com/brockk/escalation/llms.txt

Demonstrates the classic 3+3 dose-escalation design using the 'escalation' R package. This rule-based design does not require statistical modeling and uses fixed cohorts with pre-defined escalation and stopping rules. The examples show escalating, staying, and stopping based on observed toxicities.

```r
library(escalation)

# Create 3+3 design
model <- get_three_plus_three(num_doses = 5)

# Escalate after 0/3 toxicities
fit1 <- model %>% fit('1NNN')
fit1 %>% recommended_dose()

fit1 %>% continue()

# Stay after 1/3 toxicity, treat 3 more
fit2 <- model %>% fit('1NNN 2NTN')
fit2 %>% recommended_dose()

fit2 %>% continue()

# Stop after 2/6 toxicities at a dose
fit3 <- model %>% fit('1NNN 2NTN 2NNT')
fit3 %>% recommended_dose()

fit3 %>% continue()

# Allow de-escalation variant (Korn et al.)
model_korn <- get_three_plus_three(num_doses = 5, allow_deescalate = TRUE)
model_korn %>% fit('2NTT') %>% recommended_dose()
```

--------------------------------

### Simulate Clinical Trial Designs with Stopping Rules (R)

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A205-CRM.html

This code snippet demonstrates how to configure and run a clinical trial simulation using the `get_dfcrm` function and applying multiple stopping rules. It calculates operating characteristics for a given design over a specified number of iterations. Dependencies include the `trialr` package and its associated functions.

```r
model <- get_dfcrm(skeleton = skeleton, target = target, model = 'empiric', 
                       scale = beta_sd) %>%
  stop_when_too_toxic(dose = 1, tox_threshold = target, confidence = 0.8) %>%
  stop_when_n_at_dose(dose = 'recommended', n = 9) %>%
  stop_at_n(n = 24)

num_sims <- 50
sc1 <- c(0.25, 0.5, 0.6, 0.7, 0.8)

set.seed(123)
sims <- model %>%
  simulate_trials(num_sims = num_sims, true_prob_tox = sc1, next_dose = 1)

sims
```

--------------------------------

### Get Target Toxicity Rate using `tox_target` in R

Source: https://github.com/brockk/escalation/blob/master/docs/reference/tox_target.html

The `tox_target` function retrieves the target toxicity rate from a dose-escalation model object. It takes a model object (typically created by functions like `get_dfcrm`) as input and returns the target toxicity rate as a numeric value. If the model does not support a target toxicity rate, it returns NULL. The example demonstrates creating a model, fitting it to data, and then extracting the target toxicity rate.

```r
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
target <- 0.25
model <- get_dfcrm(skeleton = skeleton, target = target)
fit <- model %>% fit('1NNN 2NTN')
fit %>% tox_target()
#> [1] 0.25
```

--------------------------------

### Return All Model Fits in Simulations (R)

Source: https://github.com/brockk/escalation/blob/master/docs/articles/A700-Simulation.html

Retains all model fits for each simulated trial by setting `return_all_fits = TRUE` in `simulate_trials`. This is useful for detailed analysis but can consume significant memory with many simulations.

```r
sims <- get_three_plus_three(num_doses = 5) %>%
  simulate_trials(num_sims = num_sims, true_prob_tox = true_prob_tox,
                  return_all_fits = TRUE)
```

```r
sapply(sims$fits, length)
```

```r
as_tibble(sims) %>% head(12)
```