clusterPower (version 0.7.0)

cps.irgtt.count: Power simulations for cluster-randomized trials: Individually randomized group treatment trial designs, count outcome.

Description

This function utilizes iterative simulations to determine approximate power for cluster-randomized controlled trials. Users can modify a variety of parameters to suit the simulations to their desired experimental situation.

Usage

cps.irgtt.count(
  nsim = NULL,
  nsubjects = NULL,
  nclusters = NULL,
  c1 = NULL,
  c2 = NULL,
  sigma_b_sq = 0,
  sigma_b_sq2 = 0,
  family = "poisson",
  analysis = "poisson",
  negBinomSize = 1,
  alpha = 0.05,
  quiet = FALSE,
  allSimData = FALSE,
  poorFitOverride = FALSE,
  lowPowerOverride = FALSE,
  timelimitOverride = TRUE,
  nofit = FALSE,
  seed = NA,
  optmethod = "Nelder_Mead"
)

Arguments

nsim

Number of datasets to simulate; accepts integer (required).

nsubjects

Number of subjects per cluster; accepts integer (required).

nclusters

Number of clusters in the arm; accepts integer (required). Arm 1 cluster size defaults to 1.

At least 2 of the following 3 arguments must be specified:

c1

Expected outcome count in arm 1

c2

Expected outcome count in arm 2

sigma_b_sq

Between-cluster variance; defaults to 0. Accepts numeric. If between cluster variances differ between arms, the following must also be specified:

sigma_b_sq2

Between-cluster variance for clusters in arm 2

family

Distribution from which responses are simulated. Accepts Poisson ('poisson') or negative binomial ('neg.binom') (required); default = 'poisson'

analysis

Family used for regression; currently only applicable for GLMM. Accepts 'poisson' or 'neg.binom' (required); default = 'poisson'

negBinomSize

Only used when generating simulated data from the negative binomial (family = 'neg.binom'), this is the target for number of successful trials, or the dispersion parameter (the shape parameter of the gamma mixing distribution). Must be strictly positive but need not be integer. Defaults to 1.

alpha

Significance level. Default = 0.05.

quiet

When set to FALSE, displays simulation progress and estimated completion time. Default = FALSE.

allSimData

Option to output list of all simulated datasets. Default = FALSE.

poorFitOverride

Option to override stop() if more than 25% of fits fail to converge; default = FALSE.

lowPowerOverride

Option to override stop() if the power is less than 0.5 after the first 50 simulations and every ten simulations thereafter. On function execution stop, the actual power is printed in the stop message. Default = FALSE. When TRUE, this check is ignored and the calculated power is returned regardless of value.

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 FALSE.

seed

Option to set seed. Default is NA.

optmethod

Option to fit with a different optimizer. Defaults to Nelder_Mead.

Value

A list with the following components

• Character string indicating total number of simulations, distribution of simulated data, and regression family

• Number of simulations

• Data frame with columns "Power" (Estimated statistical power), "lower.95.ci" (Lower 95 "upper.95.ci" (Upper 95

• Analytic method used for power estimation

• Data frame containing families for distribution and analysis of simulated data

• Significance level

• Vector containing user-defined cluster sizes

• Vector containing user-defined number of clusters

• Data frame reporting between-cluster variances for both arms

• Vector containing expected counts and risk ratios based on user inputs

• Data frame with columns: "Estimate" (Estimate of treatment effect for a given simulation), "Std.err" (Standard error for treatment effect estimate), "Test.statistic" (z-value (for GLMM) or Wald statistic (for GEE)), "p.value", "sig.val" (Is p-value less than alpha?)

• If allSimData = TRUE, a list of data frames, each containing: "y" (Simulated response value), "trt" (Indicator for arm), "clust" (Indicator for cluster)

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).

Details

Runs the power simulation for count outcomes.

Users must specify the desired number of simulations, number of subjects per cluster, number of clusters per arm, between-cluster variance, two of the following: expected count in arm 1 (no clusters), expected count in arm 2 (clustered arm), expected difference in counts between arms; significance level, and whether or not progress updates should be displayed while the function is running.

Examples

# NOT RUN {
irgtt.count.sim <- cps.irgtt.count(nsim = 100, nsubjects = c(200, 10), nclusters = 10, 
                             c1 = 5, c2 = 7, sigma_b_sq2 = 0.1, 
                             family = 'poisson', analysis = 'poisson',
                             alpha = 0.05, quiet = FALSE, allSimData = FALSE)
# }
# NOT RUN {
# }