plot.bayes_ctd_array {BayesCTDesign}

Plot Data from Two Arm Bayesian Clinical Trial Simulation.

Description

plot.bayes_ctd_array() takes an S3 object of class bayes_ctd_array, and creates a line plot from a one or two dimensional slice of the data generated by a clinical trial simulation using historic_sim() or simple_sim(). The plotted results can be smoothed or unsmoothed.

Usage

## S3 method for class 'bayes_ctd_array'
plot(
  x = NULL,
  measure = "power",
  tab_type = "WX|YZ",
  smooth = FALSE,
  plot_out = TRUE,
  subj_per_arm_val = NULL,
  a0_val = NULL,
  effect_val = NULL,
  rand_control_diff_val = NULL,
  span = 0.75,
  degree = 2,
  family = "gaussian",
  title = NULL,
  ylim = NULL,
  ...
)

Arguments

x

Name of object of class bayes_ctd_array containing data from clinical trial simulation.

measure

Must be equal to power, est, var, bias, or mse. Default is power. Case does not matter.

tab_type

A character string that must equal WX|YZ, WY|XZ, WZ|XY, XY|WZ, XZ|WY, YZ|WX, ZX|WY, XW|YZ, YW|XZ, YX|WZ, ZW|XY, ZX|WY, ZY|WX when x is generated by historic_sim(). Default is WX|YZ. When x is generated by simple_sim(), tab_type is ignored.

smooth

A true/false parameter indicating whether smoothed results should be plotted. Note, smoothing of simulation results requires the length of subj_per_arm_val or a0_val or effect_val or rand_control_diff_val, whichever populates the x-axis on the graph to contain enough elements to justify the smoothing. No checking occurs to determine if enough elements are present to justify smoothing. Default is FALSE.

plot_out

A true/false parameter indicating whether the plot should be produced. This parameter is useful if the user only wants a table of smoothed values. Default is TRUE.

subj_per_arm_val

Must be non-missing, if x is generated by historic_sim() and sample size is being held constant. If x is generated by historic_sim() and sample size is being held constant, subj_per_arm_val must equal a value submitted to historic_sim() within the subj_per_arm parameter. When x is generated by simple_sim(), subj_per_arm_val is ignored.

a0_val

Must be non-missing, if x is generated by historic_sim() and a0, the power prior parameter, is being held constant. If x is generated by historic_sim() and a0 is being held constant, a0_val must equal a value submitted to historic_sim() within the a0_val parameter. When x is generated by simple_sim(), a0_val is ignored.

effect_val

Must be non-missing, if x is generated by historic_sim() and effect is being held constant. If x is generated by historic_sim() and effect is being held constant, effect_val must equal a value submitted to historic_sim() within the effect_vals parameter. When x is generated by simple_sim(), effect_val is ignored.

rand_control_diff_val

Must be non-missing, if x is generated by historic_sim() and differences between randomized and historical controls are being held constant. If x is generated by historic_sim() and control differences are being held constant, rand_control_diff_val must equal a value submitted to historic_sim() within the rand_control_diff parameter. When x is generated by simple_sim(), rand_control_diff_val is ignored.

span

The span parameter value for a call loess(). Default is 0.75. If span is a single number, then that value will be used to smooth the data in all columns of the table being plotted. If span is a vector, then it must have length equal to the number of columns being plotted.

degree

The degree parameter value for a call loess(). Default is 2. The value of degree will be used for all columns being plotted.

family

The family parameter value for a call loess(). Default is "gaussian". The value of family will be used for all columns being plotted.

title

Title for the plot.

ylim

Lower and upper limits for y-axis of plot.

...

further arguments passed to or from other methods.

Details

If the object of class bayes_ctd_array is created by historic_sim(), the function plot() allows the user to create line plots of user-specified 1- or 2- dimensional slices of the simulation results based on slicing code described below. If the object of class bayes_ctd_array is created by simple_sim(), a basic plot of characteristic by sample size and effect is created.

If the object of class bayes_ctd_array is created by simple_sim(), then all four trial characteristics (subj_per_arm_val, a0_vals, effect_val, and rand_control_diff_val) can be ignored as can the parameter defining what type of plot to create through the parameter tab_type. A call to plot() will require the user to specify a measure (power, est, var, bias, or mse).

If the object of class bayes_ctd_array is created by historic_sim(), when calling plot() the user must specify a measure to plot (power, est, var, bias, or mse) and may be required to specify a plot type through the tab_type parameter. A plot type, tab_type, will be required if 3 of the 4 trial characteristics are equal to a vector of 2 or more values. This plot type specification uses the letters W, X, Y, and Z. The letter W represents the subject per arm dimension. The letter X represents the a0 dimension. The letter Y represents the effect dimension. The letter Z represents the control difference dimension. To plot a slice of the 4-dimensional array, these letters are put into an AB|CD pattern just like in print(). The two letters to the right of the vertical bar define which variables are held constant. The two letters to the left of the vertical bar define which variables are going to show up in the plot. The first letter defines the x-axis variable and the second letter defines the stratification variable. The result is a plot of power, estimate, variance, bias, or mse by the trial characteristic represented by the first letter. On this plot, one line will be created for each value of the trial characteristic represented by the second letter. For example if tab_type equals WX|YZ, then effect and control differences will be held constant, while sample size will be represented along the horizontal axis and a0 values will be represented by separate lines. The actual values that are plotted on the y-axis depend on what measure is requested in the parameter measure.

• tab_type='WX|YZ', Sample Size by a0

• tab_type='WY|XZ', Sample Size by Effect

• tab_type='WZ|XY', Sample Size by Control Differences

• tab_type='XY|WZ', a0 by Effect

• tab_type='XZ|WY', a0 by Control Differences

• tab_type='YZ|WX', Effect by Control Differences

• tab_type='ZX|WY', Control Differences by a0

• tab_type='XW|YZ', a0 by Sample Size

• tab_type='YW|XZ', Effect by Sample Size

• tab_type='YX|WZ', Effect by a0

• tab_type='ZW|XY', Control Differences by Sample Size

• tab_type='ZY|WX', Control Differences by Effect

It is very important to populate the values of subj_per_arm_val, a0_val, effect_val, and rand_control_diff_val correctly given the value of tab_type, when the object of class bayes_ctd_array is created by historic_sim() and at least 3 of the four parameters have more than one value. On, the other hand, if 2 or more of the four parameters have only one value, then subj_per_arm_val, a0_vals, effect_val, rand_control_diff_val, as well as tab_type can be ignored. If the last two letters are YZ, then effect_val and rand_control_diff_val must be populated. If the last two letters are XZ, then a0_val and rand_control_diff_val must be populated. If the last two letters are XY, then a0_val and effect_val must be populated. If the last two letters are WZ, then sample_val and rand_control_diff_val must be populated. If the last two letters are WY, then sample_size_val and effect_val must be populated. If the last two letters are WX, then sample_size_val and a0_val must be populated.

If the object of class bayes_ctd_array is created by simple_sim(), the parameters tab_type, subj_per_arm_val, a0_val, effect_val, and rand_control_diff_val are ignored.

Value

plot() returns a plot for a two dimensional array of simulation results. If smooth is TRUE, then the plot is based on a smoothed version of the simulation results. If smooth is FALSE, then the plot is based on the raw data from the simulation results. What actually is plotted depends on the value of measure. If plot_out is FALSE, the plot is not created. This option is useful when the user wants a table of smoothed simulation results but does not want the plot. Smoothing of simulation results requires the length of subj_per_arm_val or a0_val or effect_val or rand_control_diff_val, whichever populates the x-axis on the graph to contain enough elements to justify the smoothing. No checking occurs to determine if enough elements are present to justify smoothing.

Examples

#Run a Weibull simulation, using simple_sim().
#For meaningful results, trial_reps needs to be much larger than 2.
weibull_test <- simple_sim(trial_reps = 2, outcome_type = "weibull",
                           subj_per_arm = c(50, 100, 150, 200),
                           effect_vals = c(0.6, 1),
                           control_parms = c(2.82487,3), time_vec = NULL,
                           censor_value = NULL, alpha = 0.05,
                           get_var = TRUE, get_bias = TRUE, get_mse = TRUE,
                           seedval=123, quietly=TRUE)

#Create a plot of the power simulation results.
plot(x=weibull_test, measure="power", tab_type=NULL,
     smooth=FALSE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL)
#Create a plot of the hazard ratio simulation results.
plot(x=weibull_test, measure="est", tab_type=NULL,
     smooth=FALSE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL)
#Create a plot of the hazard ratio variance simulation results.
plot(x=weibull_test, measure="var", tab_type=NULL,
     smooth=FALSE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL)
#Create a plot of the hazard ratio bias simulation results.
plot(x=weibull_test, measure="bias", tab_type=NULL,
     smooth=FALSE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL)
#Create a plot of the hazard ratio mse simulation results.
plot(x=weibull_test, measure="mse", tab_type=NULL,
     smooth=FALSE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL)


#Run a second Weibull simulation, using simple_sim() and smooth the plot.
#For meaningful results, trial_reps needs to be larger than 100.
weibull_test2 <- simple_sim(trial_reps = 100, outcome_type = "weibull",
                            subj_per_arm = c(50, 75, 100, 125, 150, 175, 200, 225, 250),
                            effect_vals = c(0.6, 1, 1.4),
                            control_parms = c(2.82487,3), time_vec = NULL,
                            censor_value = NULL, alpha = 0.05, get_var = TRUE,
                            get_bias = TRUE, get_mse = TRUE, seedval=123,
                            quietly=TRUE)

#Create a plot of the power simulation results.
plot(x=weibull_test2, measure="power", tab_type=NULL,
     smooth=TRUE, plot_out=TRUE, subj_per_arm_val=NULL, a0_val=NULL,
     effect_val=NULL, rand_control_diff_val=NULL, span=c(1,1,1))



#Run a third weibull simulation, using historic_sim().
#Note: historic_sim() can take a while to run.
#Generate a sample of historical data for use in example.
set.seed(2250)
SampleHistData <- genweibulldata(sample_size=60, scale1=2.82487,
                                 hazard_ratio=0.6, common_shape=3,
                                 censor_value=3)
histdata <- subset(SampleHistData, subset=(treatment==0))
histdata$id <- histdata$id+10000

#For meaningful results, trial_reps needs to be larger than 100.
weibull_test3 <- historic_sim(trial_reps = 100, outcome_type = "weibull",
                              subj_per_arm = c(50, 100, 150, 200, 250),
                              a0_vals = c(0, 0.33, 0.67, 1),
                              effect_vals = c(0.6, 1, 1.4),
                              rand_control_diff = c(0.8, 1, 1.2),
                              hist_control_data = histdata, time_vec = NULL,
                              censor_value = 3, alpha = 0.05, get_var = TRUE,
                              get_bias = TRUE, get_mse = TRUE, seedval=123,
                              quietly=TRUE)

#Create a plot of the power simulation results.
plot(x=weibull_test3, measure="power", tab_type="WX|YZ",
     smooth=FALSE, plot_out=TRUE, effect_val=0.6,
     rand_control_diff_val=1.0)



#Run a Gaussian simulation, using historic_sim()
#Generate a sample of historical Gaussian data for use in example.
set.seed(2250)
samplehistdata <- gengaussiandata(sample_size=60, mu1=25, mean_diff=0, common_sd=3)
histdata <- subset(samplehistdata, subset=(treatment==0))
histdata$id <- histdata$id+10000

#For meaningful results, trial_reps needs to be larger than 100.
gaussian_test <- historic_sim(trial_reps = 100, outcome_type = "gaussian",
                             subj_per_arm = c(150),
                             a0_vals = c(1.0),
                             effect_vals = c(0.15),
                             rand_control_diff = c(-4.0,-3.5,-3.0,-2.5,-2.0,
                                                   -1.5,-1.0,-0.5,0,0.5,1.0),
                             hist_control_data = histdata, time_vec = NULL,
                             censor_value = 3, alpha = 0.05, get_var = TRUE,
                             get_bias = TRUE, get_mse = TRUE, seedval=123,
                             quietly=TRUE)
test_table <- print(x=gaussian_test, measure="power",
                         tab_type=NULL, effect_val=NULL,
                         subj_per_arm_val=NULL)
print(test_table)
#Create a plot of the power simulation results.
plot(x=gaussian_test, measure="power", tab_type=NULL,
     smooth=TRUE, plot_out=TRUE, effect_val=NULL,
     rand_control_diff_val=NULL)



#Generate a sample of historical pwe data for use in example.
set.seed(2250)
nvalHC <- 60
time.vec <- c(0.3,0.9,1.5,2.1,2.4)
lambdaHC.vec <- c(0.19,0.35,0.56,0.47,0.38,0.34)
censor.value <- 3

SampleHistData <- genpwedata(nvalHC, lambdaHC.vec, 1.0, time.vec, censor.value)
histdata <- subset(SampleHistData, subset=(treatment==0))
histdata$indicator <- 2 #If set to 2, then historical controls will be collapsed with
#randomized controls, when time_vec is re-considered and
#potentially restructured.  If set to 1, then historical
#controls will be treated as a separated cohort when
#time_vec is being assessed for restructuring.
histdata$id <- histdata$id+10000

#Run a pwe simulation, using historic_sim().
#For meaningful results, trial_reps needs to be larger than 100.
pwe_test <- historic_sim(trial_reps = 100, outcome_type = "pwe",
                        subj_per_arm = c(25,50,75,100,125,150,175,200,225,250),
                        a0_vals = c(1.0),
                        effect_vals = c(0.6),
                        rand_control_diff = c(1.8),
                        hist_control_data = histdata, time_vec = time.vec,
                        censor_value = 3, alpha = 0.05, get_var = TRUE,
                        get_bias = TRUE, get_mse = TRUE, seedval=123,
                        quietly=TRUE)

#Create a plot of the power simulation results.
plot(x=pwe_test, measure="power", tab_type=NULL,
     smooth=TRUE, plot_out=TRUE, effect_val=NULL,
     rand_control_diff_val=NULL)