# Kenkleinman/clusterPower

Merge pull request #36 from Kenkleinman/lexi

Lexi
 @@ -0,0 +1,57 @@ #' Power calculations for simple cluster randomized trials, binary outcome #' #' Wrapper function that uses crtpwr.2prop to compute the power of #' a simple cluster randomized trial with a binary outcome, #' or determine parameters to obtain a target power. See ?crtpwr.2prop #' for additional details. #' #' @section Authors: #' Alexandria Sakrejda, Jonathan Moyer (\email{jon.moyer@@gmail.com}), #' Ken Kleinman (\email{ken.kleinman@@gmail.com}) #' @param alpha The level of significance of the test, the probability of a #' Type I error. #' @param power The power of the test, 1 minus the probability of a Type II #' error. #' @param n The number of clusters per condition. It must be greater than 1. #' @param m The mean of the cluster sizes. #' @param CV The coefficient of variation of the cluster sizes. When \code{cv} = 0, #' the clusters all have the same size. #' @param p1 The expected proportion in the treatment group. #' @param p2 The proportion in the control group. #' @param ICC The intraclass correlation. #' @param pooled Logical indicating if pooled standard error should be used. #' @param p1inc Logical indicating if p1 is expected to be greater than p2. #' @param tol Numerical tolerance used in root finding. The default provides #' at least four significant digits. #' @return The computed argument. #' @examples #' # Find the number of clusters per condition needed for a trial with alpha = .05, #' # power = 0.8, 10 observations per cluster, no variation in cluster size, probability #' # in condition 1 of .1 and condition 2 of .2, and icc = 0.1. #' cpa.binary(m=10 ,p1=.1, p2=.2, ICC=.1) #' # #' # The result, showimg nclusters of greater than 37, suggests 38 clusters per #' # condition should be used. #' @references Donner A, Klar N. Design and Analysis of Cluster Randomization #' Trials in Health Research. London; Arnold; 2000. #' @references Wu S, Crespi CM, Wong WK. Comparison of Methods for Estimating Intraclass #' Correlation Coefficient for Binary Responses in Cancer Prevention Cluster Randomized #' Trials. Contemp Clin Trials. 2012; 33(5): 869-880. doi:10.1016/j.cct.2012.05.004 London: Arnold; 2000. #' @export cpa.binary <- function(alpha = 0.05, power = 0.80, n = NA, m = NA, CV = 0, p1 = NA, p2 = NA, ICC = NA, pooled = FALSE, p1inc = TRUE, tol = .Machine$double.eps^0.25){ simple.analytic.binary <- crtpwr.2prop(alpha = alpha, power = power, nclusters = n, nsubjects = m, cv = CV, p1 = p1, p2 = p2, icc = ICC, pooled = pooled, p1inc = p1inc, tol = tol) return(simple.analytic.binary) }  @@ -0,0 +1,51 @@ #' Power calculations for simple cluster randomized trials, count outcome #' #' Wrapper function that uses crtpwr.2rate to compute the power of a #' simple cluster randomized trial with a count outcome, #' or determine parameters to obtain a target power. For additional #' details, see ?crtpwr.2rate help page. #' #' @section Authors: #' Jonathan Moyer (\email{jon.moyer@@gmail.com}), Ken Kleinman (\email{ken.kleinman@@gmail.com}) #' #' @param alpha The level of significance of the test, the probability of a #' Type I error. #' @param power The power of the test, 1 minus the probability of a Type II #' error. #' @param nclusters The number of clusters per condition. It must be greater than 1. #' @param py The number of person-years of observation per cluster. #' @param r1 The expected mean event rate per unit time in the treatment group. #' @param r2 The mean event rate per unit time in the control group. #' @param cvb The between-cluster coefficient of variation. #' @param r1inc Logical indicating if r1 is expected to be greater than r2. This is #' only important to specify if one of r1 or r2 is NA. #' @param tol Numerical tolerance used in root finding. The default provides #' at least four significant digits. #' @return The computed argument. #' @examples #' # Find the number of clusters per condition needed for a trial with alpha = 0.05, #' # power = 0.80, 10 person-years per cluster, rate in condition 1 of 0.10 #' # and condition 2 of 0.20, and CVB = 0.10. #' cpa.count(m=10, r1=0.10, r2=0.20, CV=0.10) #' # #' # The result, showimg nclusters of greater than 24, suggests 25 clusters per #' # condition should be used. #' #' @references Donner A, Klar N. Design and Analysis of Cluster Randomization Trials in Health Research. Chichester, UK; 2009. #' #' @references Hayes JR, Moulton LH. Cluster Randomized Trials. Boca Raton, FL: CRC Press; 2009. #' @export cpa.count <- function(alpha = 0.05, power = 0.80, n = NA, m = NA, r1 = NA, r2 = NA, CV = NA, r1inc = TRUE, tol = .Machine$double.eps^0.25){ simple.analytic.count <- crtpwr.2rate(alpha = alpha, power = power, nclusters = n, py = m, r1 = r1, r2 = r2, cvb = CV, r1inc = r1inc, tol = tol) return(simple.analytic.count) }
 @@ -0,0 +1,71 @@ #' Power calculations for difference-in-difference cluster randomized trials, binary outcome #' #' Wrapper function that uses crtpwr.2propD() to compute the power #' of a difference-in-difference cluster randomized trial design #' with a binary outcome, or determine parameters to obtain a target #' power. For additional details, see ?crtpwr.2propD. #' #' Exactly one of \code{alpha}, \code{power}, \code{n}, \code{m}, #' \code{p}, \code{did}, \code{ICC}, \code{rho_c}, and \code{rho_s} must be passed as \code{NA}. #' Note that \code{alpha} and \code{power} have non-\code{NA} #' defaults, so if those are the parameters of interest they must be #' explicitly passed as \code{NA}. #' #' @section Authors: #' Alexandria Sakrejda, Jonathan Moyer (\email{jon.moyer@@gmail.com}), Ken Kleinman (\email{ken.kleinman@@gmail.com}) #' #' @section Note: #' This function was inspired by work from Stephane Champely (pwr.t.test) and #' Peter Dalgaard (power.t.test). As with those functions, 'uniroot' is used to #' solve power equation for unknowns, so you may see #' errors from it, notably about inability to bracket the root when #' invalid arguments are given. #' #' @param alpha The level of significance of the test, the probability of a #' Type I error. #' @param power The power of the test, 1 minus the probability of a Type II #' error. #' @param n The number of clusters per condition. It must be greater than 1. #' @param m The mean of the cluster sizes. #' @param p The expected mean proportion at the post-test, averaged across treatment and control arms. #' @param did The expected absolute difference. #' @param ICC The intraclass correlation. #' @param rho_c The correlation between baseline and post-test outcomes at the #' cluster level. This value can be used in both cross-sectional and cohort #' designs. If this quantity is unknown, a value of 0 is a conservative estimate. #' @param rho_s The correlation between baseline and post-test outcomes at the #' subject level. This should be used for a cohort design or a mixture of cohort #' and cross-sectional designs. In a purely cross-sectional design (baseline subjects #' are completely different from post-test subjects), this value should be 0. #' @param tol Numerical tolerance used in root finding. The default provides #' at least four significant digits. #' @return The computed argument. #' @examples #' # Find the number of clusters per condition needed for a trial with alpha = .05, #' # power = 0.8, 50 observations per cluster, expected mean post-test proportion of .50, #' # expected difference of .1, ICC = 0.05, cluster level correlation of 0.3, and subject level #' # correlation of 0.7. #' cpa.did.binary(m=50 ,p=.5, did=.1, ICC=.05, rho_c=.3, rho_s=.7) #' # #' # The result, showimg nclusters of greater than 32, suggests 33 clusters per #' # condition should be used. #' #' @references Murray D. Design and Analysis of Group-Randomized Trials. New York, NY: Oxford #' University Press; 1998. #' #' @export cpa.did.binary <- function(alpha = 0.05, power = 0.80, n = NA, m = NA, p = NA, did = NA, ICC = NA, rho_c = NA, rho_s = NA, tol = .Machine$double.eps^0.25){ did.analytic.binary <- crtpwr.2propD(alpha = alpha, power = power, nclusters = n, nsubjects = m, p = p, d = did, icc = ICC, rho_c = rho_c, rho_s = rho_s, tol = tol) return(did.analytic.binary) }  @@ -0,0 +1,81 @@ #' Power calculations for difference-in-difference cluster randomized trials, continuous outcome #' #' Wrapper function that uses crtpwr.2meanD() to compute the power of a #' difference-in-difference cluster randomized trial design with a #' continuous outcome, or determine parameters to obtain a target power. #' See ?crtpwr.2meanD for additional details. #' #' Exactly one of \code{alpha}, \code{power}, \code{nclusters}, \code{nsubjects}, #' \code{d}, \code{icc}, \code{rho_c}, \code{rho_s}, and \code{vart} #' must be passed as \code{NA}. Note that \code{alpha} and\code{power} #' have non-\code{NA} defaults, so if those are the parameters of #' interest they must be explicitly passed as \code{NA}. #' #' If \code{nsubjects} is a vector the values, \code{nclusters} will be recalculated #' using the values in \code{nsubjects}. #' #' @section Note: #' This function was inspired by work from Stephane Champely (pwr.t.test) and #' Peter Dalgaard (power.t.test). As with those functions, 'uniroot' is used to #' solve power equation for unknowns, so you may see #' errors from it, notably about inability to bracket the root when #' invalid arguments are given. #' #' @section Authors: #' Alexandria Sakrejda, Jonathan Moyer (\email{jon.moyer@@gmail.com}), Ken Kleinman (\email{ken.kleinman@@gmail.com}) #' #' @param alpha The level of significance of the test, the probability of a #' Type I error. #' @param power The power of the test, 1 minus the probability of a Type II #' error. #' @param n The number of clusters per condition. It must be greater than 1. #' @param m The mean of the cluster sizes. #' @param difference.control The difference in mean change in the control arm. #' @param intervention.control The difference in mean change in the intervention arm. #' @param ICC The intraclass correlation. #' @param rho_c The correlation between baseline and post-test outcomes at the #' cluster level. This value can be used in both cross-sectional and cohort #' designs. If this quantity is unknown, a value of 0 is a conservative estimate. #' @param rho_s The correlation between baseline and post-test outcomes at the #' subject level. This should be used for a cohort design or a mixture of cohort #' and cross-sectional designs. In a purely cross-sectional design (baseline subjects #' are completely different from post-test subjects), this value should be 0. #' @param vart The total variation of the outcome (the sum of within- and between-cluster variation). #' @param tol Numerical tolerance used in root finding. The default provides #' at least four significant digits. #' @return The computed argument. #' @examples #' # Find the number of clusters per condition needed for a trial with alpha = 0.05, #' # power = 0.80, m = 100, difference.control = 5, difference.intervention = 4.5, #' units, ICC = 0.05, rho_c = 0.50, rho_s = 0.70, #' # and vart = 1 unit. #' cpa.did.normal(m = 100 , difference.control = 5, difference.intervention = 4.5, ICC = 0.05, rho_c = 0.50, rho_s = 0.70, vart = 1) #' # #' # The result, nclusters = 4.683358, suggests 5 clusters per condition should be used. #' #' @references Rutterford C, Copas A, Eldridge S. (2015) Methods for sample size #' determination in cluster randomized trials. Int J Epidemiol. 44(3):1051-1067. #' @references Teerenstra S, Eldridge S, Graff M, de Hoop E, Borm, GF. (2012) A simple #' sample size formula for analysis of covariance in cluster randomized trials. #' Statist Med. 31:2169-2178 #' #' @export cpa.did.normal <- function(alpha = 0.05, power = 0.80, n = NA, m = NA, difference.control = NA, difference.intervention = NA, ICC = NA, rho_c = NA, rho_s = NA, vart = NA, tol = .Machine$double.eps^0.25){ did.analytic.normal <- crtpwr.2meanD(alpha = alpha, power = power, nclusters = n, nsubjects = m, d = difference.control-difference.intervention, icc = ICC, rho_c = rho_c, rho_s = rho_s, vart = vart, tol = tol) return(did.analytic.normal) }