power.2m: Budget and/or sample size, power, MDES calculation for two-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 two-level multisite randomized trials (MRTs). It also can perform conventional power analyses (e.g., required sample size, power, and MDES calculation).

Usage

power.2m(
  cost.model = TRUE,
  expr = NULL,
  constraint = NULL,
  sig.level = 0.05,
  two.tailed = TRUE,
  d = NULL,
  power = NULL,
  m = NULL,
  n = NULL,
  J = NULL,
  p = NULL,
  icc = NULL,
  r12 = NULL,
  r22m = NULL,
  q = NULL,
  c1 = NULL,
  c2 = NULL,
  c1t = NULL,
  omega = NULL,
  dlim = NULL,
  powerlim = NULL,
  Jlim = NULL,
  mlim = NULL,
  rounded = TRUE
)

Value

Required budget (and/or required level-2 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.2m; default is NULL; if expr is specified, parameter values of icc, r12, r22m, c1, c2, c1t, p, and n used or solved in function od.2m will be passed to current function; only the values of p and n that specified or solved in function od.2m can be overwritten if constraint is specified.
constraint: Specify the constrained values of p and/or n 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 number of sites.
p: The proportion of level-1 units to be assigned to treatment.
icc: The unconditional intraclass correlation coefficient (ICC) in population or in each treatment condition.
r12: The proportion of level-1 variance explained by covariates.
r22m: The proportion of variance of site-specific treatment effect explained by covariates.
q: The number of covariates at level 2.
c1: The cost of sampling one level-1 unit in control condition.
c2: The cost of sampling one level-2 unit.
c1t: The cost of sampling one level-1 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).
Jlim: The range for searching the root of level-2 sample size (J) numerically, default is c(4, 10e10).
mlim: The range for searching the root of budget (m) numerically, default is the costs sampling Jlim level-2 units or c(4 * Jcost, 1e+10 * Jcost) with Jcost = (1 - p) * c1 * n + p * c1t * n + c2.
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 sample allocation in multisite randomized trials. The Journal of Experimental Education. <https://doi.org/10.1080/00220973.2020.1830361>

Examples

Run this code

# Unconstrained optimal design #---------
  myod1 <- od.2m(icc = 0.2, omega = 0.02, r12 = 0.5, r22m = 0.5,
              c1 = 1, c2 = 10, c1t = 10,
              varlim = c(0, 0.005))
  myod1$out # n = 19.8, p = 0.37

# ------- Power analyses by default considering costs and budget -------
# Required budget and sample size
  mym.1 <- power.2m(expr = myod1, d = 0.2, q = 1, power = 0.8)
  mym.1$out  # m = 2019, J = 20.9
  # mym.1$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  mym.1 <- power.2m(d = 0.2, power = 0.8, q = 1,
                 icc = 0.2, omega = 0.02, r12 = 0.5, r22m = 0.5,
                 c1 = 1, c2 = 10, c1t = 10,
                 n = 20, p = 0.37)
# Required budget and sample size with constrained p
  mym.2 <- power.2m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5))
  mym.2$out  # m = 2373, J = 19.8
# Required budget and sample size with constrained p and n
  mym.3 <- power.2m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5, n = 5))
  mym.3$out  # m = 2502, J = 66.7

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

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


# ------- Conventional power analyses with cost.model = FALSE-------
# Required sample size
  myJ <- power.2m(cost.model = FALSE, expr = myod1, d = 0.2, q = 1, power = 0.8)
  myJ$out  # J = 6.3
  # myL$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  myJ <- power.2m(cost.model = FALSE, d = 0.2, power = 0.8, q = 1,
                 icc = 0.2, omega = 0.02, r12 = 0.5, r22m = 0.5,
                 c1 = 1, c2 = 10, c1t = 10,
                 n = 20, p = 0.37)

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

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

Run the code above in your browser using DataLab