II Oncology Trials

twostage_results

R Documentation

This function processes the output from twostage_simulator to produce several basic plots and summary tables.

Description

For more information on function inputs and features, please see the vignette and Boonstra, et al.

Usage

twostage_results(
  csv = FALSE,
  stage2folder = NULL,
  patientdatfolder = NULL,
  dose_outcome_curves_list = NULL,
  files = NULL,
  filepath = TRUE,
  primary_objectives = NULL,
  design_labels = NULL,
  scen_per_page = 10,
  design_per_page = 3,
  prop_label_size = 4,
  min_prop_to_write = 0.25,
  legend_text_size = 6,
  text_size = 9
)

Arguments

`csv`	A logical value indicating whether the output from twostage_simulator has been saved as .csv file(s) (if .csv, then TRUE).
`stage2folder`	A character string giving the filepath to a folder containing nothing but sim_data_stage2 output from twostage_simulator, saved as .csv file(s). This should only be provided if csv = TRUE.
`patientdatfolder`	A character string giving the filepath to a folder containing nothing but patient_data output from twostage_simulator, saved as .csv file(s). This should only be provided if csv = TRUE.
`dose_outcome_curves_list`	A list of lists, with each list element containing three named elements and an optional fourth element: tox_curve, eff_curve, scenario, and, optionally, eff_curve_stage2. tox_curve is the true toxicity curve of the doses; eff_curve is the true efficacy curve of the doses; scenario is an identifier of which true data-generating scenario is being run (meant to be helpful to the user when calling this function multiple times for different data-generating scenarios). This should be the same list that was used in twostage_simulator to generate all the simulated trials. This should only be provided if csv = TRUE.
`files`	A character string giving the filepath to a folder containing nothing but the raw output from twostage_simulator, saved as .Rds file(s). Alternatively, this can a character vector containing the names of all of the raw output from twostage_simulator, stored in the workspace. This should only be provided if csv = FALSE.
`filepath`	A logical value indicating whether files contains a filepath (filepath = TRUE) or a character vector of file names stored in the workspace (filepath = FALSE). The default is TRUE. This should only be provided if csv = FALSE.
`primary_objectives`	A list containing three named elements: tox_target, tox_delta_no_exceed, and eff_target, such that tox_target is between 0 and 1, tox_delta_no_exceed is between 0 and (1 - tox_target), and eff_target is between 0 and 1. This should be the same list that was used in twostage_simulator to generate the simulated trials.
`design_labels`	A character vector giving labels for the different designs. If left NULL, the number of the design will be used as its label. This should be the same length and the same order as design_list inputted in twostage_simulator.
`scen_per_page`	A numeric value indicating the number of data-generating scenarios that should be printed per page. This can be at most 10 (the default is 10).
`design_per_page`	A numeric value indicating the number of designs that should be printed per page. This can be at most 3 (the default is 3).
`prop_label_size`	The value of the 'size' aesthetic in calls to geom_text (the default is 4).
`min_prop_to_write`	The smallest proportion to annotate in the stacked bar charts (the default is 0.25).
`legend_text_size`	The value of the 'size' argument for the legend elements in ggplots (the default is 6).
`text_size`	The value of the 'size' argument for the other text elements in ggplots (the default is 9).

Value

The function returns a named list containing two items: "plots" and "tables". tables contains:

generating_params_for_display: This is a table giving the true efficacy and toxicity of each dose for each scenario considered.
acc_dose_rec_table: This is a table giving which proportion of trials for each design and scenario combination recommended an acceptable dose (a dose meeting the toxicity and efficacy standards, if not the best dose) at the end of the trial.
mean_patients_table: This is a table giving the mean number of patients enrolled for each design and scenario combination across the different simulated trials.

plots contains:

gen_params_plot_blue: This is a list of plots providing the same information as in generating_params_for_display, in a blue color palette. If the number of designs under consideration exceeds design_per_page or the number of scenarios under consideration exceeds scen_per_page, the list will contain multiple plots. To call the first plot, we would run: results$plots$gen_param_plot[[1]] and so on for further plots.
gen_params_plot_redgreen: This is a list of plots providing the same information as in generating_params_for_display, in a red-green color palette. If the number of designs under consideration exceeds design_per_page or the number of scenarios under consideration exceeds scen_per_page, the list will contain multiple plots. To call the first plot, we would run: results$plots$gen_param_plot[[1]] and so on for further plots.
acc_dose_rec_plot: This is a plot giving which proportion of trials for each design and scenario combination recommended an acceptable dose, unacceptable dose, or made no recommendation at all. If the number of designs under consideration exceeds design_per_page or the number of scenarios under consideration exceeds scen_per_page, the list will contain multiple plots. To call the first plot, we would run: results$plots$acc_dose_rec_plot[[1]] and so on for further plots.
dose_over_time_plot: This is a filled barplot giving the distribution of dose assignments by time, where time is measured by patient number. To call the first plot, we would run: results$plots$dose_over_time_plot[[1]] and so on for further plots.
n_patients_plot: This is a boxplot of the number of patients enrolled for each design and scenario combination across the different simulated trials.
n_patients_RP2D_plot: This is a boxplot of the number of patients who received the final recommended dose for each design and scenario combination across the different simulated trials. Note that the final recommended dose may not be safe or effective–this is merely a measure of how much patient data the design will yield for the final dose it recommends.
prop_patients_accep_plot: This is a boxplot of the number of patients who received an acceptable dose (a dose meeting the toxicity and efficacy standards, if not the best dose) for each design and scenario combination across the different simulated trials.