power.3m: Budget and/or sample size, power, MDES calculation for three-level MRTs detecting main effects

Description

This function can calculate required budget for desired power, power or minimum detectable effect size (MDES) under fixed budget for three-level multisite randomized trials (MRTs). It also can perform conventional power analyses (e.g., required sample size, power, and MDES calculation).

Usage

power.3m(
  cost.model = TRUE,
  expr = NULL,
  constraint = NULL,
  sig.level = 0.05,
  two.tailed = TRUE,
  d = NULL,
  power = NULL,
  m = NULL,
  n = NULL,
  J = NULL,
  K = NULL,
  p = NULL,
  icc2 = NULL,
  icc3 = NULL,
  r12 = NULL,
  r22 = NULL,
  r32m = NULL,
  q = NULL,
  c1 = NULL,
  c2 = NULL,
  c3 = NULL,
  c1t = NULL,
  c2t = NULL,
  omega = NULL,
  dlim = NULL,
  powerlim = NULL,
  Klim = NULL,
  mlim = NULL,
  rounded = TRUE
)

Value

Required budget (and/or required level-3 sample size), statistical power, or MDES depending on the specification of parameters. The function also returns the function name, design type, and parameters used in the calculation.

Arguments

cost.model: Logical; power analyses accommodating costs and budget (e.g., required budget for desired power, power/MDES under fixed budget) if TRUE, otherwise conventional power analyses (e.g., required sample size, power, or MDES calculation); default value is TRUE.
expr: Returned objects from function od.3m; default is NULL; if expr is specified, parameter values of icc2, icc3, r12, r22, r32m, c1, c2, c3, c1t, c2t, p, n, and J used or solved in function od.3m will be passed to current function; only the values of p, n, and/or J that specified or solved in function od.3m can be overwritten if constraint is specified.
constraint: Specify the constrained values of p, n, and/or J, in list format to overwrite those from expr; default value is NULL.
sig.level: Significance level or type I error rate, default value is 0.05.
two.tailed: Logical; two-tailed tests if TRUE, otherwise one-tailed tests; default value is TRUE.
d: Effect size.
power: Statistical power.
m: Total budget.
n: The level-1 sample size per level-2 unit.
J: The level-2 sample size per level-3 unit.
K: The level-3 sample size per level-4 unit.
p: The proportion of level-2 units to be assigned to treatment.
icc2: The unconditional intraclass correlation coefficient (ICC) at level 2.
icc3: The unconditional intraclass correlation coefficient (ICC) at level 3.
r12: The proportion of level-1 variance explained by covariates.
r22: The proportion of level-2 variance explained by covariates.
r32m: The proportion of variance of site-specific treatment effect explained by covariates.
q: The number of covariates at level 3.
c1: The cost of sampling one level-1 unit in control condition.
c2: The cost of sampling one level-2 unit in control condition.
c3: The cost of sampling one level-3 unit.
c1t: The cost of sampling one level-1 unit in treatment condition.
c2t: The cost of sampling one level-2 unit in treatment condition.
omega: The standardized variance of site-specific treatment effect.
dlim: The range for solving the root of effect size (d) numerically, default value is c(0, 5).
powerlim: The range for solving the root of power (power) numerically, default value is c(1e-10, 1 - 1e-10).
Klim: The range for searching the root of level-3 sample size (K) numerically, default value is c(4, 1e+10).
mlim: The range for searching the root of budget (m) numerically, default is the costs sampling Klim level-3 units or c(4 * Kcost, 1e+10 * Kcost) with Kcost = ((1 - p) * (c1 * n * J + c2 * J) + p * (c1t * n * J + c2t * J) + c3.
rounded: Logical; round the values of p, n/J/K that are from functions od.4 to two decimal places and integer, respectively if TRUE, otherwise no rounding; default value is TRUE.

References

Shen, Z., & Kelcey, B. (in press). Optimal sampling ratios in three-level multisite experiments. Journal of Research on Educational Effectiveness.

Examples

Run this code

# Unconstrained optimal design #---------
  myod1 <- od.3m(icc2 = 0.2, icc3 = 0.1, omega = 0.02,
              r12 = 0.5, r22 = 0.5, r32m = 0.5,
              c1 = 1, c2 = 5,
              c1t = 1, c2t = 200, c3 = 200,
              varlim = c(0, 0.005))
  myod1$out # n = 13.1, J = 15.3, p = 0.23

# ------- Power analyses by default considering costs and budget -------
# Required budget and sample size
  mym.1 <- power.3m(expr = myod1, d = 0.2, q = 1, power = 0.8)
  mym.1$out  # m = 15491, K = 13.6
  # mym.1$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  mym.1 <- power.3m(d = 0.2, power = 0.8, q = 1,
                 icc2 = 0.2, icc3 = 0.1, omega = 0.02,
                  r12 = 0.5, r22 = 0.5, r32m = 0.5,
                  c1 = 1, c2 = 5,
                  c1t = 1, c2t = 200, c3 = 200,
                  n = 13, J = 15, p = 0.23)
# Required budget and sample size with constrained p
  mym.2 <- power.3m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5))
  mym.2$out  # m = 21072, K = 10.9
# Required budget and sample size with constrained p and n
  mym.3 <- power.3m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5, n = 20))
  mym.3$out  # m = 21252, K = 10.4

# Power calculation
  mypower <- power.3m(expr = myod1, q = 1, d = 0.2, m = 15491)
  mypower$out  # power = 0.80
# Power calculation under constrained p (p = 0.5)
  mypower.1 <- power.3m(expr = myod1, q = 1, d = 0.2, m = 15491,
                 constraint = list(p = 0.5))
  mypower.1$out  # power = 0.62

# MDES calculation
  mymdes <- power.3m(expr = myod1, q = 1, power = 0.80, m = 15491)
  mymdes$out  # d = 0.20


# ------- Conventional power analyses with cost.model = FALSE-------
# Required sample size
  myK <- power.3m(cost.model = FALSE, expr = myod1, d = 0.2, q = 1, power = 0.8)
  myK$out  # K = 13.6
  # myK$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  myK <- power.3m(cost.model = FALSE, d = 0.2, power = 0.8, q = 1,
                  icc2 = 0.2, icc3 = 0.1, omega = 0.02,
                  r12 = 0.5, r22 = 0.5, r32m = 0.5,
                  c1 = 1, c2 = 5,
                  c1t = 1, c2t = 200, c3 = 200,
                  n = 13, J = 15, p = 0.23)

# Power calculation
  mypower1 <- power.3m(cost.model = FALSE, expr = myod1, K = 13.6, d = 0.2, q = 1)
  mypower1$out  # power = 0.80

# MDES calculation
  mymdes1 <- power.3m(cost.model = FALSE, expr = myod1, K = 13.6, power = 0.8, q = 1)
  mymdes1$out  # d = 0.20

Run the code above in your browser using DataLab