Skip to content
Permalink
Browse files

Merge pull request #36 from Kenkleinman/lexi

Lexi
  • Loading branch information...
acbro0 committed Jun 21, 2019
2 parents 06a7ce9 + a98823e commit 784e1a9af6524e1b7aa4d7523891d11c24449d55
Showing with 3,858 additions and 1,188 deletions.
  1. +9 −0 NAMESPACE
  2. +57 −0 R/cpa.binary.R
  3. +51 −0 R/cpa.count.R
  4. +71 −0 R/cpa.did.binary.R
  5. +81 −0 R/cpa.did.normal.R
  6. +81 −0 R/cpa.ma.normal.R
  7. +61 −0 R/cpa.normal.R
  8. +77 −52 R/cps.binary.R
  9. +78 −39 R/cps.count.R
  10. +103 −0 R/cps.irgtt.binary.R
  11. +102 −0 R/cps.irgtt.count.R
  12. +106 −0 R/cps.irgtt.normal.R
  13. +146 −87 R/cps.ma.binary.R
  14. +238 −135 R/cps.ma.binary.internal.R
  15. +173 −108 R/cps.ma.count.R
  16. +312 −175 R/cps.ma.count.internal.R
  17. +163 −71 R/cps.ma.normal.R
  18. +153 −68 R/cps.ma.normal.internal.R
  19. +141 −19 R/cps.normal.R
  20. +2 −2 R/cps.sw.count.R
  21. +18 −7 R/cps.sw.normal.R
  22. +5 −9 R/createMissingVarianceParam.R
  23. +2 −0 R/summary.method.crtpwr.R
  24. +64 −46 R/validateVariance.R
  25. 0 man/1
  26. +69 −0 man/cpa.binary.Rd
  27. +61 −0 man/cpa.count.Rd
  28. +84 −0 man/cpa.did.binary.Rd
  29. +93 −0 man/cpa.did.normal.Rd
  30. +96 −0 man/cpa.ma.normal.Rd
  31. +70 −0 man/cpa.normal.Rd
  32. +11 −11 man/cps.binary.Rd
  33. +5 −5 man/cps.count.Rd
  34. +101 −0 man/cps.irgtt.binary.Rd
  35. +102 −0 man/cps.irgtt.count.Rd
  36. +103 −0 man/cps.irgtt.normal.Rd
  37. +106 −68 man/cps.ma.binary.Rd
  38. +26 −20 man/cps.ma.binary.internal.Rd
  39. +113 −70 man/cps.ma.count.Rd
  40. +60 −40 man/cps.ma.count.internal.Rd
  41. +128 −56 man/cps.ma.normal.Rd
  42. +75 −40 man/cps.ma.normal.internal.Rd
  43. +17 −10 man/cps.normal.Rd
  44. +2 −2 man/cps.sw.count.Rd
  45. +5 −7 man/createMissingVarianceParam.Rd
  46. +38 −23 man/validateVariance.Rd
  47. +197 −16 tests/test_multiarm.R
  48. +2 −2 vignettes/clusterpower.Rmd
@@ -1,10 +1,19 @@
# Generated by roxygen2: do not edit by hand

export(cpa.binary)
export(cpa.count)
export(cpa.did.binary)
export(cpa.did.normal)
export(cpa.ma.normal)
export(cpa.normal)
export(cps.binary)
export(cps.count)
export(cps.did.binary)
export(cps.did.count)
export(cps.did.normal)
export(cps.irgtt.binary)
export(cps.irgtt.count)
export(cps.irgtt.normal)
export(cps.ma.binary)
export(cps.ma.binary.internal)
export(cps.ma.count)
@@ -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)
}
@@ -0,0 +1,81 @@
#' Power calculations for multi-arm cluster randomized trials, continuous outcome
#'
#' Wrapper function for crtpwr.nmean() to compute the power of the
#' overall F-test for a multi-arm cluster randomized trial with a
#' continuous outcome, or determine parameters to obtain a target power.
#'
#' Exactly one of \code{alpha}, \code{power}, \code{narms}, \code{n},
#' \code{m}, \code{vara}, \code{varc}, and \code{vare} 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}.
#'
#' Assuming a balanced design, the between-arm variance \eqn{\sigma_a^2} (corresponding to
#' the function argument \code{vara}) can be estimated using the formula:
#'
#' \deqn{\sigma_a^2 = \sum\limits_{i=1}^{n_a}(\mu_i - \mu)^2/(n_a-1)}
#'
#' where \eqn{n_a} is the number of arms, \eqn{\mu_i} is the estimate of the \eqn{i}-th arm
#' mean, and \eqn{\mu} is the estimate of the overall mean of the outcome. This
#' variance can be computed in R using the \code{var} function and a vector of arm means.
#' For example, suppose the estimated means for a three-arm trial were 74, 80, and 86 Then the
#' estimate of the between-arm variance could be computed with \code{var(c(74,80,86))},
#' yielding a value of 36.
#'
#' @section Note:
#' This function was inspired by work from Stephane Champely (pwr.t.test),
#' Peter Dalgaard (power.t.test), and Claus Ekstrom (power.anova.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 narms The number of independent arms (conditions). It must be greater than 2.
#' @param n The number of clusters per arm. It must be greater than 1.
#' @param m The cluster size.
#' @param vara The between-arm variance.
#' @param varc The between-cluster variance.
#' @param vare The within-cluster variance.
#' @param tol Numerical tolerance used in root finding. The default provides
#' at least four significant digits.
#' @return The computed argument.
#' @examples
#' # Suppose we are planning a multi-arm trial composed of a control arm and
#' # two treatment arms. It is known that each arm will contain 5 clusters. We
#' # wish to know the minimum number of subjects per cluster necessary to
#' # attain 80% power at a 5% level of significance. A pilot study was used to
#' # determine estimates of the between-arm variance, the between-cluster
#' # variance, and the within-cluster variance. The observed means of each arm
#' # in the pilot study were 74, 80, and 86, so the between-arm variance is 36.
#' # As discussed in the "Details" section above, this can be calculated using
#' # the command var(c(74,80,86)). The within-cluster and between-cluster
#' # standard deviations were observed to be 8 and 3, respectively. This means
#' # the within-cluster and between-cluster variances are 64 and 9, respectively.
#' # These values are entered into the function as follows:
#'
#' cpa.ma.normal(narms=3,n=5,vara=36,varc=9,vare=64)
#' #
#' # The result, showing m of greater than 20, suggests 21 subjects per
#' # cluster should be used.
#' @references Murray DM. Design and Analysis of Group-Randomized Trials. New York,
#' NY: Oxford University Press; 1998.
#' @export

cpa.ma.normal <- function(alpha = 0.05, power = 0.80,
narms = NA, n = NA, m = NA,
vara = NA, varc = NA, vare = NA,
tol = .Machine$double.eps^0.25){

ma.analytic.normal <- crtpwr.nmean(alpha = alpha, power = power,
narms = narms, nclusters = n, nsubjects = m,
vara = vara, varc = varc, vare = vare,
tol = tol)

return(ma.analytic.normal)
}

0 comments on commit 784e1a9

Please sign in to comment.
You can’t perform that action at this time.