power.2m {odr}

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
)

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.

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.

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

# 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