od.3m: Optimal sample allocation calculation for three-level MRTs...

In odr: Optimal Design and Statistical Power for Experimental Studies Investigating Main, Mediation, and Moderation Effects

Optimal sample allocation calculation for three-level MRTs detecting main effects

Description

The optimal design of two-level multisite randomized trials (MRTs) detecting main effects is to calculate the optimal sample allocation that minimize the budget to achieve a fixed statistical power (e.g., 80 algorithm. Alternatively, the function can calculate the optimal allocation that minimizes the variance of a treatment effect under a fixed budget, which is less precise than the ACO algorithm. The optimal design parameters include the level-1 sample size per level-2 unit (n), the level-2 sample size per level-3 unit (J), and the proportion of level-2 unit to be assigned to treatment (p). This function solves the optimal n, J and/or p with and without constraints.

Usage

od.3m(
  n = NULL,
  J = NULL,
  p = NULL,
  icc2 = NULL,
  icc3 = NULL,
  r12 = NULL,
  r22 = NULL,
  r32m = NULL,
  c1 = NULL,
  c2 = NULL,
  c3 = NULL,
  c1t = NULL,
  c2t = NULL,
  omega = NULL,
  m = NULL,
  plots = TRUE,
  plot.by = NULL,
  nlim = NULL,
  Jlim = NULL,
  plim = NULL,
  varlim = NULL,
  nlab = NULL,
  Jlab = NULL,
  plab = NULL,
  varlab = NULL,
  Klim = c(6, 1e+10),
  q = 1,
  d = 0.1,
  vartitle = NULL,
  verbose = TRUE,
  iter = 100,
  tol = 1e-10,
  power = 0.8,
  ACO = TRUE,
  d.p = c(0.5, 0.9),
  d.n = c(2, 1000),
  d.J = c(2, 1000),
  sig.level = 0.05,
  two.tailed = TRUE,
  nrange = c(2, 10000),
  Jrange = c(2, 10000),
  max.value = Inf,
  max.iter = 300,
  e = 1e-10,
  n.of.ants = 10,
  n.of.archive = 50,
  q.aco = 1e-04,
  xi = 0.5
)

Arguments

n	The level-1 sample size per level-2 unit.
J	The level-2 sample size per level-3 unit.
p	The proportion of level-2 units within each level-3 site 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.
c1	The cost of sampling one level-1 unit in control condition.
c2	The cost of sampling one level-2 unit (site).
c3	The cost of sampling one level-3 unit (site).
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.
m	Total budget, default is the total costs of sampling 60 level-3 units.
plots	Logical, provide variance plots if TRUE, otherwise not; default value is TRUE.
plot.by	Plot the variance by n, J and/or p; default value is plot.by = list(n = "n", J = "J", p = "p").
nlim	The plot range for n, default value is c(2, 50).
Jlim	The range for solving the root of level-2 sample size (J) numerically, default value is c(6, 1e+10).
plim	The plot range for p, default value is c(0, 1).
varlim	The plot range for variance, default value is c(0, 0.05).
nlab	The plot label for n, default value is "Level-1 Sample Size: n".
Jlab	The plot label for J, default value is "Level-2 Sample Size: J".
plab	The plot label for p, default value is "Proportion Level-2 Units in Treatment: p".
varlab	The plot label for variance, default value is "Variance".
Klim	The plot range for K, default value is c(2, 50).
q	The number of covariates at level 2. Default is 1.
d	Standardized effect size, default is 0.1.
vartitle	The title of variance plot, default value is NULL.
verbose	Logical; print the values of n, J, and p if TRUE, otherwise not; default value is TRUE.#'
iter	Number of iterations; default value is 100.
tol	Tolerance for convergence; default value is 1e-10.
power	Statistical power.
ACO	Logic. If TRUE, the function will use the ant colony optimization (ACO) algorithm to identify optimal allocations. If FALSE, the function will use the first-order derivative method to identify optimal allocations. Default is TRUE.
d.p	The initial sampling domains for p. Default is c(0.1, 0.5).
d.n	The initial sampling domain for n. Default is c(2, 1000).
d.J	The initial sampling domain for J. Default is c(2, 1000).
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.
nrange	The range of the level-1 sample size per level-2 unit that used to exclude unreasonable values. Default value is c(2, 10000).
Jrange	The range of the level-2 sample size per level-3 unit that used to exclude unreasonable values. Default value is c(2, 10000).
max.value	Maximal value of optimization when used as the stopping criterion. Default is -Inf.
max.iter	Maximal number of function evaluations when used as the stopping criterion.
e	Maximum error value used when solution quality used as the stopping criterion, default is 1e-10.
n.of.ants	Number of ants used in each iteration after the initialization of power analysis for calculating required budget, default value is 10.
n.of.archive	Size of the solution archive, default is 100.
q.aco	Locality of the ACO search (0,1), default is 0.0001.
xi	Convergence pressure (0, Inf), suggested: (0, 1), default is 0.5.

Value

Unconstrained or constrained optimal sample allocation (n, J, and p). The function also returns the variance of the treatment effect, function name, design type, and parameters used in the calculation.

References

Shen, Z., & Kelcey, B. (2022). Optimal sampling ratios in three-level multisite experiments. Journal of Research on Educational Effectiveness, 15(1), 130-150. <https://doi.org/10.1080/19345747.2021.1953200>

Examples

# 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 # output
# Plots by p and J
  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), plot.by = list(p = 'p', J = 'J'))

# Constrained optimal design with p = 0.5 #---------
  myod2 <- 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), p = 0.5)
  myod2$out
# Relative efficiency (RE)
  myre <- re(od = myod1, subod= myod2)
  myre$re # RE = 0.81

# Constrained optimal design with n = 5 #---------
  myod3 <- 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), n = 5)
  myod3$out
# Relative efficiency (RE)
  myre <- re(od = myod1, subod= myod3)
  myre$re # RE = 0.89

# Constrained n, J and p, no calculation performed #---------
  myod4 <- 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), p = 0.5, n = 15, J = 20)
  myod4$out
# Relative efficiency (RE)
  myre <- re(od = myod1, subod= myod4)
  myre$re # RE = 0.75

odr documentation built on June 8, 2025, 10:50 a.m.