simple_sim: Two Arm Bayesian Clinical Trial Simulation without Historical...
In BayesCTDesign: Two Arm Bayesian Clinical Trial Design with and Without Historical Control Data
Description
Usage
Arguments
Details
Value
Examples
View source: R/BayesCTDesigncode.R
Description
simple_sim() returns an S3 object of class bayes_ctd_array, which
will contain simulation results for power, statistic estimation, bias, variance,
and mse as requested by user.
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Arguments
trial_reps
Number of trials to replicate within each combination of
a0_vals, subj_per_arm, effect_vals, and rand_control_parms.
As the number of trials increases, the precision of the estimate will increase.
Default is 100.
outcome_type
Outcome distribution. Must be equal to weibull,
lognormal, pwe (Piecewise Exponential), gaussian,
bernoulli, or poisson. Default is weibull.
subj_per_arm
A vector of sample sizes, all of which must be positive
integers. Default is c(50, 100, 150, 200, 250).
effect_vals
A vector of effects that should be reasonable for the
outcome_type being studied, hazard ratios for Weibull, odds ratios for
Bernoulli, mean ratios for Poisson, etc.. When effect_vals contain
the null effect for a given outcome_type, the power component
of data will contain an estimate of Type One Error. In order to
have a good set of Type One Error estimates, trial_reps need to be
at least 10,000. In such a case, if the total number of combinations
made up from subj_per_arm, a0_vals, effect_vals, and
rand_control_diff is very large, the time to complete the simulation
can be substantial. Default is c(0.6, 1, 1.4).
control_parms
A vector of parameter values defining the outcome
distribution for randomized controls. See Details for what is required for
each outcome_type.
time_vec
A vector of time values that are used to create time periods
within which the exponential hazard is constant. Only used for piecewise
exponential models. Default is NULL.
censor_value
A single value at which right censoring occurs when
simulating randomized subject outcomes. Used with survival outcomes.
Default is NULL, where NULL implies no right censoring.
alpha
A number ranging between 0 and 1 that defines the acceptable Type 1
error rate. Default is 0.05.
get_var
A TRUE/FALSE indicator of whether an array of variance
estimates will be returned. Default is FALSE.
get_bias
A TRUE/FALSE indicator of whether an array of bias
estimates will be returned. Default is FALSE.
get_mse
A TRUE/FALSE indicator of whether an array of MSE
estimates will be returned. Default is FALSE.
seedval
A seed value for pseudo-random number generation.
quietly
A TRUE/FALSE indicator of whether notes are printed
to output about simulation progress as the simulation runs. If
running interactively in RStudio or running in the R console,
quietly can be set to FALSE. If running in a Notebook or
knitr document, quietly needs to be set to TRUE. Otherwise
each note will be printed on a separate line and it will take up
a lot of output space. Default is TRUE.
Details
The object bayes_ctd_array has 6 elements: a list containing simulation
results (data), copies of the 4 function arguments subj_per_arm,
a0_vals, effect_vals, and rand_control_diff, and finally
a objtype value indicating that simple_sim() was used. Each element of
data is a four-dimensional array, where each dimension is determined by the
length of parameters subj_per_arm, a0_vals, effect_vals, and
rand_control_diff. The size of data depends on which results are
requested by the user. At a minimum, at least one of subj_per_arm,
a0_vals, effect_vals, or rand_control_diff must contain at
least 2 values, while the other three must contain at least 1 value. The data
list will always contain two elements: an array of power results (power) and
an array of estimation results (est). In addition to power and
est, data may also contain elements var, bias, or
mse, depending on the values of get_var, get_bias, and
get_mse. The values returned in est are in the form of hazard ratios,
mean ratios, odds ratios, or mean differences depending on the value of
outcome_type. For a Gaussian outcome, the estimation results are
differences in group means (experimental group minus control group). For a
logistic outcome, the estimation results are odds ratios (experimental group over
control group). For lognormal and Poisson outcomes, the estimation results are mean
ratios (experimental group over control group). For a piecewise exponential or a
Weibull outcome, the estimation results are hazard ratios (experimental group over
control group). The values returned in bias, var, and mse are
on the scale of the values returned in est.
The object bayes_ctd_array has two primary methods, print() and
plot(), for printing and plotting slices of the arrays contained in
bayes_ctd_array$data.
As dimensions of the four dimensional array increases, the time required to complete
the simulation will increase; however, it will be faster than a similar simulation
based on repeated calls to MCMC routines to analyze each simulated trial.
The meaning of the estimation results, and the test used to generate power results,
depends on the outcome used. In all cases, power is based on a two-sided test
involving a (1-alpha)100% credible interval, where the interval is used to determine
if the null hypothesis should be rejected (null value outside of the interval) or
not rejected (null value inside the interval). For a Gaussian outcome, the 95%
credible interval is an interval for the difference in group means
(experimental group minus control group), and the test determines if 0 is in or
outside of the interval. For a Bernoulli outcome, the 95% credible interval
is an interval for the odds ratio (experimental group over control group),
and the test determines if 1 is in or outside of the interval. For a lognormal or
a Poisson outcome, the 95% credible interval is an interval for the mean ratio
(experimental group over control group), and the test determines if 1 is in or
outside of the interval. Finally, for a piecewise exponential or a Weibull outcome,
the 95% credible interval is an interval for the hazard ratio (experimental group
over control group), and the test determines if 1 is in or outside of the interval.
For a Gaussian outcome, the control_parms values should be (mean, sd),
where mean is the mean parameter for the control group used in a call to rnorm(),
and sd is the common sd parameter for both groups used in a call torlnorm().
For a Bernoulli outcome, the control_parms values should be (prob), where
prob is the event probability for the control group used in a call to rbinom().
For a lognormal outcome, the control_parms values should be (meanlog, sdlog),
where meanlog is the meanlog parameter for the control group used in a call to
rlnorm(), and sdlog is the common sdlog parameter for both groups used in
a call to rlnorm().
For a Poisson outcome, the control_parms value should be (lambda), where
lambda is the lambda parameter for the control group used in a call to rpois() and
is equal to the mean of a Poisson distribution.
For a Weibull outcome, the control_parms values should be (scale, shape),
where scale is the scale parameter for the control group used in a call to
rweibull(), and shape is the common shape parameter for both groups used in
a call to rweibull().
For a piecewise exponential outcome, the control_parms values should be a vector
of lambdas used in a call to eha::rpch(). Each element in control_parms
is a hazard for an interval defined by the time_vec parameter.
Please refer to the examples for illustration of package use.
Value
simple_sim() returns an S3 object of class bayes_ctd_array.
As noted in Details, an object of class bayes_ctd_array has 6 elements: a
list containing simulation results (data), copies of the 4 function
arguments subj_per_arm, a0_vals, effect_vals, and
rand_control_diff, and finally objtype indicating that simple_sim()
was used. See Details for a discussion about the contents of
data. Results from the simulation contained in the bayes_ctd_array
object can be printed or plotted using the print() and
plot() methods. The results can also be accessed using basic list
element identification and array slicing. For example, to get the power results
from a simulation, one could use the code bayes_ctd_array$data$power, where
bayes_ctd_array is replaced with the name of the variable containing the
bayes_ctd_array object. Even though this is a 4-dimensional array, the power
results only occupy a single 2-dimensional table. To print this 2-dimensional table,
one would use the code bayes_ctd_array$data$power[,1,,1], where
bayes_ctd_array is replaced with the name of the variable containing the
bayes_ctd_array object.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#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, 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)
#Tabulate the simulation results for power.
test_table <- print(x=weibull_test, measure="power",
tab_type=NULL, subj_per_arm_val=NULL, a0_val=NULL,
effect_val=NULL, rand_control_diff_val=NULL)
print(test_table)
#Create a plot of the power simulation results.
plot(x=weibull_test, measure="power", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the estimated hazard ratio simulation results.
plot(x=weibull_test, measure="est", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio variance simulation results.
plot(x=weibull_test, measure="var", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio bias simulation results.
plot(x=weibull_test, measure="bias", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio mse simulation results.
plot(x=weibull_test, measure="mse", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
BayesCTDesign documentation built on Dec. 11, 2021, 9:37 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Examples
View source: R/BayesCTDesigncode.R
Description
simple_sim() returns an S3 object of class bayes_ctd_array, which
will contain simulation results for power, statistic estimation, bias, variance,
and mse as requested by user.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
Arguments
trial_reps |
Number of trials to replicate within each combination of
|
outcome_type |
Outcome distribution. Must be equal to |
subj_per_arm |
A vector of sample sizes, all of which must be positive
integers. Default is |
effect_vals |
A vector of effects that should be reasonable for the
outcome_type being studied, hazard ratios for Weibull, odds ratios for
Bernoulli, mean ratios for Poisson, etc.. When |
control_parms |
A vector of parameter values defining the outcome
distribution for randomized controls. See Details for what is required for
each |
time_vec |
A vector of time values that are used to create time periods
within which the exponential hazard is constant. Only used for piecewise
exponential models. Default is |
censor_value |
A single value at which right censoring occurs when
simulating randomized subject outcomes. Used with survival outcomes.
Default is |
alpha |
A number ranging between 0 and 1 that defines the acceptable Type 1 error rate. Default is 0.05. |
get_var |
A TRUE/FALSE indicator of whether an array of variance
estimates will be returned. Default is |
get_bias |
A TRUE/FALSE indicator of whether an array of bias
estimates will be returned. Default is |
get_mse |
A TRUE/FALSE indicator of whether an array of MSE
estimates will be returned. Default is |
seedval |
A seed value for pseudo-random number generation. |
quietly |
A TRUE/FALSE indicator of whether notes are printed
to output about simulation progress as the simulation runs. If
running interactively in RStudio or running in the R console,
|
Details
The object bayes_ctd_array has 6 elements: a list containing simulation
results (data), copies of the 4 function arguments subj_per_arm,
a0_vals, effect_vals, and rand_control_diff, and finally
a objtype value indicating that simple_sim() was used. Each element of
data is a four-dimensional array, where each dimension is determined by the
length of parameters subj_per_arm, a0_vals, effect_vals, and
rand_control_diff. The size of data depends on which results are
requested by the user. At a minimum, at least one of subj_per_arm,
a0_vals, effect_vals, or rand_control_diff must contain at
least 2 values, while the other three must contain at least 1 value. The data
list will always contain two elements: an array of power results (power) and
an array of estimation results (est). In addition to power and
est, data may also contain elements var, bias, or
mse, depending on the values of get_var, get_bias, and
get_mse. The values returned in est are in the form of hazard ratios,
mean ratios, odds ratios, or mean differences depending on the value of
outcome_type. For a Gaussian outcome, the estimation results are
differences in group means (experimental group minus control group). For a
logistic outcome, the estimation results are odds ratios (experimental group over
control group). For lognormal and Poisson outcomes, the estimation results are mean
ratios (experimental group over control group). For a piecewise exponential or a
Weibull outcome, the estimation results are hazard ratios (experimental group over
control group). The values returned in bias, var, and mse are
on the scale of the values returned in est.
The object bayes_ctd_array has two primary methods, print() and
plot(), for printing and plotting slices of the arrays contained in
bayes_ctd_array$data.
As dimensions of the four dimensional array increases, the time required to complete the simulation will increase; however, it will be faster than a similar simulation based on repeated calls to MCMC routines to analyze each simulated trial.
The meaning of the estimation results, and the test used to generate power results, depends on the outcome used. In all cases, power is based on a two-sided test involving a (1-alpha)100% credible interval, where the interval is used to determine if the null hypothesis should be rejected (null value outside of the interval) or not rejected (null value inside the interval). For a Gaussian outcome, the 95% credible interval is an interval for the difference in group means (experimental group minus control group), and the test determines if 0 is in or outside of the interval. For a Bernoulli outcome, the 95% credible interval is an interval for the odds ratio (experimental group over control group), and the test determines if 1 is in or outside of the interval. For a lognormal or a Poisson outcome, the 95% credible interval is an interval for the mean ratio (experimental group over control group), and the test determines if 1 is in or outside of the interval. Finally, for a piecewise exponential or a Weibull outcome, the 95% credible interval is an interval for the hazard ratio (experimental group over control group), and the test determines if 1 is in or outside of the interval.
For a Gaussian outcome, the control_parms values should be (mean, sd),
where mean is the mean parameter for the control group used in a call to rnorm(),
and sd is the common sd parameter for both groups used in a call torlnorm().
For a Bernoulli outcome, the control_parms values should be (prob), where
prob is the event probability for the control group used in a call to rbinom().
For a lognormal outcome, the control_parms values should be (meanlog, sdlog),
where meanlog is the meanlog parameter for the control group used in a call to
rlnorm(), and sdlog is the common sdlog parameter for both groups used in
a call to rlnorm().
For a Poisson outcome, the control_parms value should be (lambda), where
lambda is the lambda parameter for the control group used in a call to rpois() and
is equal to the mean of a Poisson distribution.
For a Weibull outcome, the control_parms values should be (scale, shape),
where scale is the scale parameter for the control group used in a call to
rweibull(), and shape is the common shape parameter for both groups used in
a call to rweibull().
For a piecewise exponential outcome, the control_parms values should be a vector
of lambdas used in a call to eha::rpch(). Each element in control_parms
is a hazard for an interval defined by the time_vec parameter.
Please refer to the examples for illustration of package use.
Value
simple_sim() returns an S3 object of class bayes_ctd_array.
As noted in Details, an object of class bayes_ctd_array has 6 elements: a
list containing simulation results (data), copies of the 4 function
arguments subj_per_arm, a0_vals, effect_vals, and
rand_control_diff, and finally objtype indicating that simple_sim()
was used. See Details for a discussion about the contents of
data. Results from the simulation contained in the bayes_ctd_array
object can be printed or plotted using the print() and
plot() methods. The results can also be accessed using basic list
element identification and array slicing. For example, to get the power results
from a simulation, one could use the code bayes_ctd_array$data$power, where
bayes_ctd_array is replaced with the name of the variable containing the
bayes_ctd_array object. Even though this is a 4-dimensional array, the power
results only occupy a single 2-dimensional table. To print this 2-dimensional table,
one would use the code bayes_ctd_array$data$power[,1,,1], where
bayes_ctd_array is replaced with the name of the variable containing the
bayes_ctd_array object.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | #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, 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)
#Tabulate the simulation results for power.
test_table <- print(x=weibull_test, measure="power",
tab_type=NULL, subj_per_arm_val=NULL, a0_val=NULL,
effect_val=NULL, rand_control_diff_val=NULL)
print(test_table)
#Create a plot of the power simulation results.
plot(x=weibull_test, measure="power", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the estimated hazard ratio simulation results.
plot(x=weibull_test, measure="est", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio variance simulation results.
plot(x=weibull_test, measure="var", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio bias simulation results.
plot(x=weibull_test, measure="bias", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
#Create a plot of the hazard ratio mse simulation results.
plot(x=weibull_test, measure="mse", tab_type=NULL,
smooth=FALSE, plot_out=TRUE)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.