Description Usage Arguments Details Value Testing details Author(s) Examples
View source: R/cps.ma.binary.R
This function uses iterative simulations to determine approximate power for multi-arm cluster-randomized controlled trials with binary outcomes of interest. Users can modify a variety of parameters to suit the simulations to their desired experimental situation. This function validates the user's input and passes the necessary arguments to an internal function, which performs the simulations. This function returns the summary power values for each treatment arm.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | cps.ma.binary(
nsim = 1000,
nsubjects = NULL,
narms = NULL,
nclusters = NULL,
probs = NULL,
sigma_b_sq = NULL,
alpha = 0.05,
quiet = FALSE,
method = "glmm",
multi_p_method = "bonferroni",
allSimData = FALSE,
seed = NULL,
cores = NA,
tdist = FALSE,
poorFitOverride = FALSE,
lowPowerOverride = FALSE,
timelimitOverride = TRUE,
nofit = FALSE,
optmethod = "Nelder-Mead",
return.all.models = FALSE
)
|
nsim |
Number of datasets to simulate; accepts integer (required). |
nsubjects |
Number of subjects per cluster (required); accepts an
integer if all are equal and |
narms |
Integer value representing the number of trial arms. |
nclusters |
An integer or vector of integers representing the number of clusters in each arm. |
probs |
Expected absolute treatment effect probabilities for each arm;
accepts a scalar or a vector of length |
sigma_b_sq |
Between-cluster variance; accepts a vector of length
|
alpha |
Significance level; default = 0.05. |
quiet |
When set to FALSE, displays simulation progress and estimated completion time; default is FALSE. |
method |
Analytical method, either Generalized Linear Mixed Effects Model (GLMM) or Generalized Estimating Equation (GEE). Accepts c('glmm', 'gee') (required); default = 'glmm'. |
multi_p_method |
A string indicating the method to use for adjusting
p-values for multiple comparisons. Choose one of "holm", "hochberg",
"hommel", "bonferroni", "BH", "BY", "fdr", "none". The default is
"bonferroni". See |
allSimData |
Option to output list of all simulated datasets; default = FALSE. |
seed |
Option to set.seed. Default is NULL. |
cores |
String ("all"), NA, or scalar value indicating the number of cores to be used for parallel computing. Default = NA (no parallel computing). |
tdist |
Logical value indicating whether simulated data should be drawn from a t-distribution rather than the normal distribution. Default = FALSE. |
poorFitOverride |
Option to override |
lowPowerOverride |
Option to override |
timelimitOverride |
Logical. When FALSE, stops execution if the estimated completion time is more than 2 minutes. Defaults to TRUE. |
nofit |
Option to skip model fitting and analysis and return the
simulated data.
Defaults to |
optmethod |
User-specified optimizer method. Accepts |
return.all.models |
Logical; Returns all of the fitted models and the simulated data. Defaults to FALSE. |
Users must specify the desired number of simulations, number of subjects per
cluster, number of clusters per treatment arm, group probabilities, and the
between-cluster variance. Significance level, analytic method, progress
updates, poor/singular fit override, and whether or not to return the
simulated data may also be specified. The internal function can be called
directly by the user to return the fitted models rather than the power
summaries (see ?cps.ma.normal.internal
for details).
Because the model for binary outcomes may be slower to fit than those for
other distributions, this function may be slower than its normal or
count-distributed counterparts. Users can spread the simulated data
generation and model fitting tasks across multiple cores using the
cores
argument. Users should expect that parallel computing may make
model fitting faster than using a single core for more complicated models.
For simpler models, users may prefer to use single thread computing
(cores
=1), as the processes involved in allocating memory and
copying data across cores also may take some time. For time-savings,
this function stops execution early if estimated power < 0.5 or more
than 25% of models produce a singular fit or non-convergence warning
message, unless poorFitOverride = TRUE
.
Non-convergent models are not included in the calculation of exact confidence intervals.
A list with the following components:
Data frame with columns "power" (Estimated statistical power), "lower.95.ci" (Lower 95% confidence interval bound), "upper.95.ci" (Upper 95% confidence interval bound).
Data frame with columns corresponding to each arm with descriptive suffixes as follows: ".Estimate" (Estimate of treatment effect for a given simulation), "Std.Err" (Standard error for treatment effect estimate), ".zval" (for GLMM) | ".wald" (for GEE), and ".pval" (the p-value estimate).
Table of F-test (when method="glmm") or chi^2 (when method="gee") significance test results.
Summary overall power of treatment model compared to the null model.
Produced when allSimData==TRUE. List of nsim
data frames, each containing:
"y" (simulated response value),
"trt" (indicator for treatment group or arm), and
"clust" (indicator for cluster).
Character string containing the percent
of nsim
in which the glmm fit was singular or failed to converge,
produced only when method = "glmm" & allSimData = FALSE.
Vector of length nsim
denoting
whether or not a simulation glmm fit triggered a "singular fit" or
"non-convergence" error, produced only when method = "glmm" &
allSimData=TRUE.
If nofit = T
, a data frame of the simulated data sets, containing:
"arm" (Indicator for treatment arm)
"cluster" (Indicator for cluster)
"y1" ... "yn" (Simulated response value for each of the nsim
data sets).
This function has been verified, where possible, against reference values from the NIH's GRT
Sample Size Calculator, PASS11, CRTsize::n4prop
, clusterPower::cps.binary
, and
clusterPower::cpa.binary
.
Alexandria C. Sakrejda (acbro0@umass.edu), Alexander R. Bogdan, and Ken Kleinman (ken.kleinman@gmail.com)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | ## Not run:
bin.ma.rct.unbal <- cps.ma.binary(nsim = 12,
nsubjects = list(rep(20, times=15),
rep(15, times=15),
rep(17, times=15)),
narms = 3,
nclusters = 15,
probs = c(0.35, 0.43, 0.50),
sigma_b_sq = c(0.1, 0.1, 0.1),
alpha = 0.05, allSimData = TRUE,
seed = 123, cores="all")
bin.ma.rct.bal <- cps.ma.binary(nsim = 100, nsubjects = 50, narms=3,
nclusters=8,
probs = c(0.35, 0.4, 0.5),
sigma_b_sq = 0.1, alpha = 0.05,
quiet = FALSE, method = 'glmm',
allSimData = FALSE,
multi_p_method="none",
seed = 123, cores="all",
poorFitOverride = FALSE)
## End(Not run)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.