clusterPower (version 0.7.0)

cps.irgtt.binary: Simulation-based power estimation for binary outcome individually randomized group treatment trials.

Description

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

Usage

cps.irgtt.binary(
  nsim = NULL,
  nsubjects = NULL,
  nclusters = NULL,
  p1 = NULL,
  p2 = NULL,
  sigma_b_sq = 0,
  sigma_b_sq2 = 0,
  alpha = 0.05,
  quiet = TRUE,
  allSimData = FALSE,
  poorFitOverride = FALSE,
  lowPowerOverride = FALSE,
  timelimitOverride = TRUE,
  nofit = FALSE,
  seed = NA
)

Arguments

nsim

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

nsubjects

Number of subjects per cluster in the clustered (arm 2) group; accepts integer (required).

nclusters

Number of clusters per arm; accepts integer (required).

p1

Expected probability of outcome in arm 1 (required)

p2

Expected probability of outcome in arm 2 (required)

sigma_b_sq

Between-cluster variance; defaults to 0. Accepts numeric.

sigma_b_sq2

Between-cluster variance for clusters in arm 2.

alpha

Significance level; default = 0.05

quiet

When set to FALSE, displays simulation progress and estimated completion time, default is TRUE.

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.

Value

A list with the following components

• Character string indicating total number of simulations, simulation type, and number of convergent models

• Number of simulations

• Data frame with columns "Power" (Estimated statistical power), "lower.95.ci" (Lower 95 confidence interval bound)

• Analytic method used for power estimation

• Significance level

• Vector containing user-defined cluster sizes

• Vector containing user-defined number of clusters

• Data frame reporting sigma_b_sq for each group

• Vector containing expected difference in probabilities 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", "converge" (Did simulated model converge?), "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)

• List of warning messages produced by non-convergent models; Includes model number for cross-referencing against model.estimates

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 binary outcomes.

Users must specify the desired number of simulations, number of subjects per cluster, number of clusters per arm, two of the following three terms: expected probability of outcome in arm 1, expected probability of outcome in arm 2, expected difference in probabilities between groups; significance level, progress updates, and simulated data set output may also be specified.

References

Snjiders, T. & Bosker, R. Multilevel Analysis: an Introduction to Basic and Advanced Multilevel Modelling. London, 1999: Sage.

Eldridge, S., Ukoumunne, O. & Carlin, J. The Intra-Cluster Correlation Coefficient in Cluster Randomized Trials: A Review of Definitions. International Statistical Review (2009), 77, 3, 378-394. doi: 10.1111/j.1751-5823.2009.00092.x

Examples

# NOT RUN {
irgtt.binary.sim <- cps.irgtt.binary(nsim = 100, nsubjects = c(150, 30), 
                        nclusters = 10, p1 = 0.44,
                        p2 = 0.2, sigma_b_sq2 = 1, alpha = 0.05, 
                        allSimData = FALSE)
# }