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

Usage

power.4m(
  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,
  L = NULL,
  p = NULL,
  icc2 = NULL,
  icc3 = NULL,
  icc4 = NULL,
  r12 = NULL,
  r22 = NULL,
  r32 = NULL,
  r42m = NULL,
  q = NULL,
  c1 = NULL,
  c2 = NULL,
  c3 = NULL,
  c4 = NULL,
  c1t = NULL,
  c2t = NULL,
  c3t = NULL,
  omega = NULL,
  dlim = NULL,
  powerlim = NULL,
  Llim = NULL,
  mlim = NULL,
  rounded = TRUE
)

Value

Required budget (and/or required level-4 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.4m; default is NULL; if expr is specified, parameter values of icc2, icc3, icc4, r12, r22, r32, r42m, c1, c2, c3, c4, c1t, c2t, c3t, p, n, J, and K used or solved in function od.4m will be passed to current function; only the values of p, n, J, and/or K that specified or solved in function od.4m can be overwritten if constraint is specified.
constraint: The constrained values of p, n, J, and/or K 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.
L: The total level-4 sample size.
p: The proportion of level-3 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.
icc4: The unconditional intraclass correlation coefficient (ICC) at level 4.
r12: The proportion of level-1 variance explained by covariates.
r22: The proportion of level-2 variance explained by covariates.
r32: The proportion of level-3 variance explained by covariates.
r42m: The proportion of variance of site-specific treatment effect explained by covariates.
q: The number of covariates at level 4.
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 in control condition.
c4: The cost of sampling one level-4 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.
c3t: The cost of sampling one level-3 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).
Llim: The range for solving the root of level-4 sample size (L) numerically, default value is c(4, 1e+10).
mlim: The range for searching the root of budget (m) numerically, default is the costs sampling Llim level-4 units or c(4 * Lcost, 1e+10 * Lcost) with Lcost = ((1 - p) * (c1 * n * J * K + c2 * J * K + c3 * K) + p * (c1t * n * J * K + c2t * J * K + c3t * K) + c4.
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.

Examples

Run this code

# Unconstrained optimal design #---------
  myod1 <- od.4m(icc2 = 0.2, icc3 = 0.1, icc4 = 0.05, omega = 0.02,
              r12 = 0.5, r22 = 0.5, r32 = 0.5, r42m = 0.5,
              c1 = 1, c2 = 5, c3 = 25,
              c1t = 1, c2t = 50, c3t = 250, c4 = 500,
              varlim = c(0, 0.005))
  myod1$out # n = 8.3, J = 3.2, K = 4.9, p = 0.36

# ------- Power analyses by default considering costs and budget -------
# Required budget and sample size
  mym.1 <- power.4m(expr = myod1, d = 0.2, q = 1, power = 0.8)
  mym.1$out  # m = 30201, L = 20.6
  # mym.1$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  mym.1 <- power.4m(d = 0.2, power = 0.8, q = 1,
                 icc2 = 0.2, icc3 = 0.1, icc4 = 0.05, omega = 0.02,
                 r12 = 0.5, r22 = 0.5, r32 = 0.5, r42m = 0.5,
                 c1 = 1, c2 = 5, c3 = 25,
                 c1t = 1, c2t = 50, c3t = 250, c4 = 500,
                 n = 8, J = 3, K = 5, p = 0.36)
# Required budget and sample size with constrained p
  mym.2 <- power.4m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5))
  mym.2$out  # m = 33183, L = 19.3
# Required budget and sample size with constrained p and n
  mym.3 <- power.4m(expr = myod1, d = 0.2, q = 1, power = 0.8,
                 constraint = list(p = 0.5, n = 20))
  mym.3$out  # m = 34262, L = 18.0

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

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


# ------- Conventional power analyses with cost.model = FALSE-------
# Required sample size
  myL <- power.4m(cost.model = FALSE, expr = myod1, d = 0.2, q = 1, power = 0.8)
  myL$out  # L = 20.6
  # myL$par  # parameters and their values used for the function
# Or, equivalently, specify every argument in the function
  myL <- power.4m(cost.model = FALSE, d = 0.2, power = 0.8, q = 1,
                  icc2 = 0.2, icc3 = 0.1, icc4 = 0.05, omega = 0.02,
                 r12 = 0.5, r22 = 0.5, r32 = 0.5, r42m = 0.5,
                 c1 = 1, c2 = 5, c3 = 25,
                 c1t = 1, c2t = 50, c3t = 250, c4 = 500,
                 n = 8, J = 3, K = 5, p = 0.36)

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

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

Run the code above in your browser using DataLab