Overview
The boinet package provides flexible result formatting capabilities for all BOIN-ET design family results. This vignette demonstrates how to format simulation results for analysis and reporting using the built-in functionality and standard R tools.
Key Approach
While the package continues to evolve with enhanced formatting functions, this vignette shows how to work with existing boinet results using standard R data manipulation techniques.
Basic Workflow
Step 1: Run Simulation
First, run your BOIN-ET simulation as usual:
# Example TITE-BOIN-ET simulation
result <- tite.boinet(
n.dose = 5,
start.dose = 1,
size.cohort = 3,
n.cohort = 15,
toxprob = c(0.02, 0.08, 0.15, 0.25, 0.40),
effprob = c(0.10, 0.20, 0.35, 0.50, 0.65),
phi = 0.30,
delta = 0.60,
tau.T = 28,
tau.E = 42,
accrual = 7,
estpt.method = "obs.prob",
obd.method = "max.effprob",
n.sim = 1000
)Step 2: Extract and Format Data
Manual Data Extraction
# Extract operating characteristics manually
extract_oc_data <- function(boinet_result) {
dose_levels <- names(boinet_result$n.patient)
data.frame(
dose_level = dose_levels,
toxicity_prob = as.numeric(boinet_result$toxprob),
efficacy_prob = as.numeric(boinet_result$effprob),
n_patients = as.numeric(boinet_result$n.patient),
selection_prob = as.numeric(boinet_result$prop.select),
stringsAsFactors = FALSE
)
}
# Extract design parameters manually
extract_design_data <- function(boinet_result) {
params <- data.frame(
parameter = c("Target Toxicity Rate (φ)", "Target Efficacy Rate (δ)",
"Lower Toxicity Boundary (λ₁)", "Upper Toxicity Boundary (λ₂)",
"Efficacy Boundary (η₁)", "Early Stop Rate (%)",
"Average Duration (days)", "Number of Simulations"),
value = c(boinet_result$phi, boinet_result$delta,
boinet_result$lambda1, boinet_result$lambda2,
boinet_result$eta1, boinet_result$prop.stop,
boinet_result$duration, boinet_result$n.sim),
stringsAsFactors = FALSE
)
# Add time-specific parameters if available
if (!is.null(boinet_result$tau.T)) {
time_params <- data.frame(
parameter = c("Toxicity Assessment Window (days)",
"Efficacy Assessment Window (days)",
"Accrual Rate (days)"),
value = c(boinet_result$tau.T, boinet_result$tau.E, boinet_result$accrual),
stringsAsFactors = FALSE
)
params <- rbind(params, time_params)
}
return(params)
}
# Extract data
oc_data <- extract_oc_data(result)
design_data <- extract_design_data(result)
# View operating characteristics
oc_data
#> dose_level toxicity_prob efficacy_prob n_patients selection_prob
#> 1 1 0.02 0.10 8.2 5.2
#> 2 2 0.08 0.20 12.5 18.7
#> 3 3 0.15 0.35 15.8 42.1
#> 4 4 0.25 0.50 10.3 28.3
#> 5 5 0.40 0.65 7.2 5.7# View design parameters
design_data
#> parameter value
#> 1 Target Toxicity Rate (φ) 0.30
#> 2 Target Efficacy Rate (δ) 0.60
#> 3 Lower Toxicity Boundary (λ₁) 0.03
#> 4 Upper Toxicity Boundary (λ₂) 0.42
#> 5 Efficacy Boundary (η₁) 0.36
#> 6 Early Stop Rate (%) 3.20
#> 7 Average Duration (days) 156.30
#> 8 Number of Simulations 1000.00
#> 9 Toxicity Assessment Window (days) 28.00
#> 10 Efficacy Assessment Window (days) 42.00
#> 11 Accrual Rate (days) 7.00Working with Different Design Types
The same extraction approach works with all BOIN-ET design family members:
# The extraction functions work with any boinet result type:
# - tite.boinet results
# - tite.gboinet results
# - boinet results
# - gboinet results
# Example usage:
# oc_data <- extract_oc_data(any_boinet_result)
# design_data <- extract_design_data(any_boinet_result)Custom Analysis Examples
Dose Selection Analysis
# Find optimal dose
optimal_dose <- oc_data$dose_level[which.max(oc_data$selection_prob)]
cat("Optimal dose level:", optimal_dose, "\n")
#> Optimal dose level: 3
cat("Selection probability:", round(max(oc_data$selection_prob), 1), "%\n")
#> Selection probability: 42.1 %
# Doses with reasonable selection probability (>10%)
viable_doses <- oc_data[oc_data$selection_prob > 10, ]
viable_doses
#> dose_level toxicity_prob efficacy_prob n_patients selection_prob
#> 2 2 0.08 0.20 12.5 18.7
#> 3 3 0.15 0.35 15.8 42.1
#> 4 4 0.25 0.50 10.3 28.3Safety Analysis
# Assess safety profile
safety_summary <- oc_data %>%
mutate(
safety_category = case_when(
toxicity_prob <= 0.10 ~ "Low toxicity",
toxicity_prob <= 0.25 ~ "Moderate toxicity",
TRUE ~ "High toxicity"
)
) %>%
group_by(safety_category) %>%
summarise(
n_doses = n(),
total_selection_prob = sum(selection_prob),
avg_patients = mean(n_patients),
.groups = "drop"
)
safety_summary
#> # A tibble: 3 × 4
#> safety_category n_doses total_selection_prob avg_patients
#> <chr> <int> <dbl> <dbl>
#> 1 High toxicity 1 5.7 7.2
#> 2 Low toxicity 2 23.9 10.4
#> 3 Moderate toxicity 2 70.4 13.0Efficacy-Toxicity Trade-off
# Analyze efficacy-toxicity trade-off
tradeoff_data <- oc_data %>%
mutate(
benefit_risk_ratio = efficacy_prob / (toxicity_prob + 0.01), # Add small constant to avoid division by zero
utility_score = efficacy_prob - 2 * toxicity_prob # Simple utility function
) %>%
arrange(desc(utility_score))
# Top doses by utility
head(tradeoff_data[, c("dose_level", "toxicity_prob", "efficacy_prob",
"selection_prob", "utility_score")], 3)
#> dose_level toxicity_prob efficacy_prob selection_prob utility_score
#> 1 1 0.02 0.10 5.2 0.06
#> 2 3 0.15 0.35 42.1 0.05
#> 3 2 0.08 0.20 18.7 0.04Creating Visualizations
if (ggplot2_available) {
oc_data %>%
ggplot(aes(x = dose_level, y = selection_prob)) +
geom_col(fill = "steelblue", alpha = 0.7) +
geom_text(aes(label = paste0(round(selection_prob, 1), "%")),
vjust = -0.3, size = 3.5) +
labs(
x = "Dose Level",
y = "Selection Probability (%)",
title = "TITE-BOIN-ET: Dose Selection Performance",
subtitle = paste("Optimal dose:", optimal_dose,
"selected in", round(max(oc_data$selection_prob), 1), "% of trials")
) +
theme_minimal() +
theme(
plot.title = element_text(hjust = 0.5, size = 14, face = "bold"),
plot.subtitle = element_text(hjust = 0.5, size = 12)
)
} else {
cat("ggplot2 package not available. Install with: install.packages('ggplot2')\n")
}
Dose Selection Probabilities
if (ggplot2_available) {
oc_data %>%
ggplot(aes(x = toxicity_prob, y = efficacy_prob)) +
geom_point(aes(size = selection_prob), alpha = 0.7, color = "darkred") +
geom_text(aes(label = dose_level), vjust = -1.2) +
scale_size_continuous(name = "Selection\nProbability (%)", range = c(2, 10)) +
labs(
x = "True Toxicity Probability",
y = "True Efficacy Probability",
title = "Efficacy-Toxicity Profile",
subtitle = "Point size represents selection probability"
) +
theme_minimal() +
theme(
plot.title = element_text(hjust = 0.5, size = 14, face = "bold"),
plot.subtitle = element_text(hjust = 0.5, size = 12)
)
} else {
cat("ggplot2 package not available for visualization.\n")
}
Efficacy vs Toxicity Trade-off
Creating Summary Tables
Operating Characteristics Table
# Create a nicely formatted table using base R
create_oc_summary <- function(oc_data) {
formatted_data <- oc_data
formatted_data$toxicity_prob <- round(formatted_data$toxicity_prob, 3)
formatted_data$efficacy_prob <- round(formatted_data$efficacy_prob, 3)
formatted_data$n_patients <- round(formatted_data$n_patients, 1)
formatted_data$selection_prob <- round(formatted_data$selection_prob, 1)
# Rename columns for display
names(formatted_data) <- c("Dose Level", "True Toxicity Prob",
"True Efficacy Prob", "Avg N Treated",
"Selection Prob (%)")
return(formatted_data)
}
# Create formatted table
formatted_oc <- create_oc_summary(oc_data)
print(formatted_oc)
#> Dose Level True Toxicity Prob True Efficacy Prob Avg N Treated
#> 1 1 0.02 0.10 8.2
#> 2 2 0.08 0.20 12.5
#> 3 3 0.15 0.35 15.8
#> 4 4 0.25 0.50 10.3
#> 5 5 0.40 0.65 7.2
#> Selection Prob (%)
#> 1 5.2
#> 2 18.7
#> 3 42.1
#> 4 28.3
#> 5 5.7Design Parameters Table
# Create formatted design parameters table
create_design_summary <- function(design_data) {
formatted_design <- design_data
formatted_design$value <- round(as.numeric(formatted_design$value), 3)
# Clean up parameter names
names(formatted_design) <- c("Parameter", "Value")
return(formatted_design)
}
formatted_design <- create_design_summary(design_data)
print(formatted_design)
#> Parameter Value
#> 1 Target Toxicity Rate (φ) 0.30
#> 2 Target Efficacy Rate (δ) 0.60
#> 3 Lower Toxicity Boundary (λ₁) 0.03
#> 4 Upper Toxicity Boundary (λ₂) 0.42
#> 5 Efficacy Boundary (η₁) 0.36
#> 6 Early Stop Rate (%) 3.20
#> 7 Average Duration (days) 156.30
#> 8 Number of Simulations 1000.00
#> 9 Toxicity Assessment Window (days) 28.00
#> 10 Efficacy Assessment Window (days) 42.00
#> 11 Accrual Rate (days) 7.00Enhanced Summary Output
The package provides enhanced summary methods for all boinet result types:
# Enhanced summary automatically detects design type
summary(result)
#> TITE-BOIN-ET Design Operating Characteristics
#> =========================================
#>
#> Design Parameters:
#> Target Toxicity Probability: 0.30
#> Target Efficacy Probability: 0.60
#> Trial Duration: 156.3 days
#> Early Stop Probability: 3.2%
#>
#> Operating Characteristics by Dose Level:
#> # A tibble: 5 × 6
#> dose_level toxicity_prob efficacy_prob n_patients selection_prob selection_pct
#> <chr> <dbl> <dbl> <dbl> <dbl> <chr>
#> 1 1 0.02 0.1 8.2 5.2 5.2%
#> 2 2 0.08 0.2 12.5 18.7 18.7%
#> 3 3 0.15 0.35 15.8 42.1 42.1%
#> 4 4 0.25 0.5 10.3 28.3 28.3%
#> 5 5 0.4 0.65 7.2 5.7 5.7%Exporting Data
# Export data for external analysis
write.csv(oc_data, "operating_characteristics.csv", row.names = FALSE)
write.csv(design_data, "design_parameters.csv", row.names = FALSE)
# Save as RDS for R users
saveRDS(list(oc_data = oc_data, design_data = design_data), "boinet_results.rds")
# Create summary report
summary_stats <- list(
optimal_dose = optimal_dose,
max_selection_prob = max(oc_data$selection_prob),
early_stop_rate = result$prop.stop,
avg_duration = result$duration,
design_type = class(result)[1]
)
saveRDS(summary_stats, "summary_statistics.rds")Best Practices
1. Consistent Workflow
Always follow the pattern: simulate first, then extract and analyze data.
2. Data Validation
# Always check your results make sense
total_selection <- sum(oc_data$selection_prob) + as.numeric(result$prop.stop)
cat("Total probability (selection + early stop):", round(total_selection, 1), "%\n")
#> Total probability (selection + early stop): 103.2 %
# Check for reasonable dose allocation
cat("Patient allocation summary:\n")
#> Patient allocation summary:
print(summary(oc_data$n_patients))
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 7.2 8.2 10.3 10.8 12.5 15.8
# Verify dose ordering makes sense
if (all(diff(oc_data$toxicity_prob) >= 0)) {
cat("✓ Toxicity probabilities are non-decreasing\n")
} else {
cat("⚠ Warning: Toxicity probabilities not monotonic\n")
}
#> ✓ Toxicity probabilities are non-decreasing3. Reproducible Analysis
# Document analysis parameters
analysis_info <- list(
date = Sys.Date(),
design_type = class(result)[1],
r_version = R.version.string,
boinet_version = as.character(packageVersion("boinet")),
key_findings = list(
optimal_dose = optimal_dose,
selection_probability = max(oc_data$selection_prob),
early_stop_rate = as.numeric(result$prop.stop)
)
)
# Display analysis info
str(analysis_info)
#> List of 5
#> $ date : Date[1:1], format: "2025-06-05"
#> $ design_type : chr "tite.boinet"
#> $ r_version : chr "R version 4.3.3 (2024-02-29 ucrt)"
#> $ boinet_version: chr "1.2.0"
#> $ key_findings :List of 3
#> ..$ optimal_dose : chr "3"
#> ..$ selection_probability: num 42.1
#> ..$ early_stop_rate : num 3.24. Custom Utility Functions
# Create reusable utility functions
calculate_utility_score <- function(eff_prob, tox_prob, eff_weight = 1, tox_weight = 2) {
eff_weight * eff_prob - tox_weight * tox_prob
}
find_best_doses <- function(oc_data, n_top = 3) {
oc_data %>%
arrange(desc(selection_prob)) %>%
head(n_top) %>%
select(dose_level, selection_prob, toxicity_prob, efficacy_prob)
}
# Use utility functions
oc_data$utility <- calculate_utility_score(oc_data$efficacy_prob, oc_data$toxicity_prob)
top_doses <- find_best_doses(oc_data)
cat("Top doses by selection probability:\n")
#> Top doses by selection probability:
print(top_doses)
#> dose_level selection_prob toxicity_prob efficacy_prob
#> 1 3 42.1 0.15 0.35
#> 2 4 28.3 0.25 0.50
#> 3 2 18.7 0.08 0.20Advanced Analysis Examples
Sensitivity Analysis
# Analyze sensitivity to design parameters
sensitivity_summary <- data.frame(
metric = c("Optimal Dose", "Max Selection %", "Early Stop %",
"Avg Duration", "Total Patients"),
value = c(optimal_dose, round(max(oc_data$selection_prob), 1),
round(result$prop.stop, 1), round(result$duration, 0),
round(sum(oc_data$n_patients), 0)),
stringsAsFactors = FALSE
)
print(sensitivity_summary)
#> metric value
#> 1 Optimal Dose 3
#> 2 Max Selection % 42.1
#> 3 Early Stop % 3.2
#> 4 Avg Duration 156
#> 5 Total Patients 54Comparative Analysis Framework
# Framework for comparing multiple designs
create_design_comparison <- function(result_list, design_names) {
comparison_data <- data.frame()
for (i in seq_along(result_list)) {
oc_data <- extract_oc_data(result_list[[i]])
optimal_dose <- oc_data$dose_level[which.max(oc_data$selection_prob)]
summary_row <- data.frame(
design = design_names[i],
optimal_dose = optimal_dose,
max_selection = max(oc_data$selection_prob),
early_stop = result_list[[i]]$prop.stop,
avg_duration = result_list[[i]]$duration,
stringsAsFactors = FALSE
)
comparison_data <- rbind(comparison_data, summary_row)
}
return(comparison_data)
}
# Example usage (would work with multiple results)
cat("Comparison framework ready for multiple design evaluation\n")
#> Comparison framework ready for multiple design evaluationConclusion
The boinet package provides a solid foundation for analyzing BOIN-ET simulation results. Using standard R data manipulation techniques, you can:
- Extract key information from simulation results
- Create custom analyses tailored to your needs
- Generate publication-quality summaries and visualizations
- Export data for further analysis or reporting
- Build reproducible workflows for consistent analysis
As the package continues to evolve, additional convenience functions will be added, but the core approach of extracting and analyzing the structured results remains consistent across all BOIN-ET design types.
For publication-ready tables, see the gt-integration
vignette. For complete reporting workflows, see the
quarto-workflow vignette.