Designs and Functions

Rules for Function Names

For experiments detecting main effects, this package includes fourcategorical of functions and they areod,plot.power,power, andre. Forod andpowerfunctions, if a function name follows .# (e.g., od.2), this function isfor #-level designs with treatment assignment at the top level (# in 1,2, 3). If a function name follows .#m (e.g., od.2m), this function isfor #-level multisite-randomized trials.

Functions

Designs and Functions

Rules for Function Names

There are two categories of functions for designs detecting mediationeffects. They areod andpower functions. The functionnames follow additional rules as these functions will add additionalnumbers to represent the levels of the treatment assignment, themediator and the outcome. For example,od.2.221 is theod function for two-level cluster-randomized trials (.2) withthe treatment assignment and the mediator at the level two, and theoutcome at the level 1 (.221).od.2m.111 is theodfunction for two-level multisite-randomized trials (.2m) with thetreatment assignment, the mediator, and the outcome at the level one(.111).

Functions

There are two categorical functions for designs detecting mediationeffects and they areod andpower.odfunction can calculate optimal design parameters with and without aconstraint(s).power function can perform power analysis.

Designs and Functions

Rules for Function Names

There are two categories of functions for designs detectingmoderation effects. They areod andpower functions.The function names follow additional rules as these functions will addadditional numbers to represent the levels of the treatment assignment,the moderator and the outcome. For example,od.2.221m is theod function for two-level cluster-randomized trials (.2) withthe treatment assignment and the moderator at the level two, and theoutcome at the level 1 (.221), and for moderators (m) rather than formediators.od.2m.111m is theod function for two-levelmultisite-randomized trials (.2m) with the treatment assignment, themoderator, and the outcome at the level one (.111) for moderators(m).

Functions

There are two categorical functions for designs detecting mediationeffects and they areod andpower.odfunction can calculate optimal design parameters with and without aconstraint(s).power function can perform power analysis.

Functionod

Given cost structure (i.e., the costs of sampling each unit atdifferent levels and treatment conditions), this function solves theoptimal sample allocation with and without constraints.

To solve the optimal sample allocation of a two-levelcluster-randomized trial, we need the following information

• icc: intraclass correlation coefficient
• r12: the proportion of level-one outcome variance explained bycovariates
• r22: the proportion of level-two outcome variance explained bycovariates
• c1: the cost of sampling each additional level-one unit in thecontrol condition
• c2: the cost of sampling each additional level-two unit in thecontrol condition
• c1t: the cost of sampling each additional level-one unit in theexperimental condition
• c2t: the cost of sampling each additional level-two unit in theexperimental condition
• m: a total fixed budget used to plot the variance curves, defaultvalue is the cost of sampling 60 level-two units across treatmentconditions.

library(odr)

# unconstrained optimal designmyod1<-od.2(icc =0.2,r12 =0.5,r22 =0.5,c1 =1,c2 =5,c1t =1,c2t =50,varlim =c(0.01,0.02))

## The optimal level-1 sample size per level-2 unit (n) is 8.878572.## The optimal proportion of level-2 units in treatment (p) is 0.326828.

# The function by default prints messages of output and plots the variance curves; one can turn off message and specify one or no plot.# myod1$out # output;# myod1$par # parameters used in the calculation.

# constrained optimal design with n = 20myod2<-od.2(icc =0.2,r12 =0.5,r22 =0.5,c1 =1,c2 =5,c1t =1,c2t =50,plot.by =list(p ="p"),n =20,varlim =c(0.005,0.030))

## The constrained level-1 sample size per level-2 unit (n) is 20.## The optimal proportion of level-2 units in treatment (p) is 0.3740667.

# myod2$out # output# myod2$par # parameters used in the calculation.

# constrained optimal design with p = 0.5myod3<-od.2(icc =0.2,r12 =0.5,r22 =0.5,c1 =1,c2 =5,c1t =1,c2t =50,p =0.5,varlim =c(0.005,0.020))

## The optimal level-1 sample size per level-2 unit (n) is 10.48809.## The constrained proportion of level-2 units in treatment (p) is 0.5.

# myod3$out # output;# myod3$par # parameters used in the calculation.

# constrained n and p, no calculation performedmyod4<-od.2(icc =0.2,r12 =0.5,r22 =0.5,c1 =1,c2 =5,c1t =1,c2t =50,plots =FALSE,n =20,p =0.5,varlim =c(0.005,0.025))

## ===============================## Both p and n are constrained, there is no calculation from other parameters.## ===============================## The constrained level-1 sample size per level-2 unit (n) is 20.## The constrained proportion of level-2 units in treatment (p) is 0.5.

Please see additional examples in corresponding functions byuncommenting below lines.

# ?od.1# ?od.3# ?od.4# ?od.2m# ?od.3m# ?od.4m

Functionplot.power

This function plots the statistical power curves for the identifiedoptimal sample allocation. It takes the output from anodfunction as the key inputs. Other arguments include

• q: the number of covariates at the proper level, which depends onthe type of the design
• d: standardized main treatment effect
• power: the power level for the main effect
• other parameters that vary across designs

The function will first calculate the required budget to achieve thetarget power level (80%) if the budget is not explicitly specified.Then, it calculate the power under different allocations under the samebudget and plot the power curve(s) against the sample allocations.

myplot<-plot.power(expr = myod1,q =1,d = .1)

myplot

## $mfrow## [1] 1 1

Functionpower

This function by default can perform power analyses accommodatingcost structures (i.e., cost.model = TRUE), one of ‘power’, ‘m’, and ‘d’must be NULL. For example, if ‘power’ is NULL, the function calculatesstatistical power under a fixed budget and cost structure; if ‘d’ isNULL, the function calculates minimum detectable effect size (i.e., d)under a fixed budget and desired power level; if ‘m’ is NULL, thefunction calculate required budget (and required sample size) to achievedesired power level to detect a treatment effect.

This function also can conduct conventional power analysis or poweranalysis without accommodating cost structures by specifying cost.model= FALSE, the conventional power analyses include statistical powercalculation, minimum detectable effect size calculation, and requiredsample size calculation.

mym<-power.2(expr = myod1,d =0.3,q =1,power =0.8)# mym$out  # m =1702, J = 59

figure<-par(mfrow =c(1,2))budget<-NULLnrange<-c(2:50)for (nin nrange)  budget<-c(budget,power.2(expr = myod1,constraint =list (n = n),d =0.3,q =1,power =0.8)$out$m)plot(nrange, budget,type ="l",lty =1,xlim =c(0,50),ylim =c(1500,3500),xlab ="Level-1 sample size: n",ylab ="Budget",main ="",col ="black")abline(v =9,lty =2,col ="Blue")budget<-NULLprange<-seq(0.05,0.95,by =0.005)for (pin prange)  budget<-c(budget,power.2(expr = myod1,constraint =list (p = p),d =0.3,q =1,power =0.8)$out$m)plot(prange, budget,type ="l",lty =1,xlim =c(0,1),ylim =c(1500,7000),xlab ="Porportion groups in treatment: p",ylab ="Budget",main ="",col ="black")abline(v =0.33,lty =2,col ="Blue")

par(figure)

mypower<-power.2(expr = myod1,q =1,d =0.3,m =1702)# mypower$out  # power = 0.80

figure<-par(mfrow =c (1,2))pwr<-NULLnrange<-c(2:50)for (nin nrange)  pwr<-c(pwr,power.2(expr = myod1,constraint =list (n = n),d =0.3,q =1,m =1702)$out)plot(nrange, pwr,type ="l",lty =1,xlim =c(0,50),ylim =c(0.4,0.9),xlab ="Level-1 sample size: n",ylab ="Power",main ="",col ="black")abline(v =9,lty =2,col ="Blue")pwr<-NULLprange<-seq(0.05,0.95,by =0.005)for (pin prange)  pwr<-c(pwr,power.2(expr = myod1,constraint =list (p = p),d =0.3,q =1,m =1702)$out)plot(prange, pwr,type ="l",lty =1,xlim =c(0,1),ylim =c(0.1,0.9),xlab ="Porportion groups in treatment: p",ylab ="Power",main ="",col ="black")abline(v =0.33,lty =2,col ="Blue")

par(figure)

mymdes<-power.2(expr = myod1,q =1,power =0.80,m =1702)# above experssion takes parameters and outputs from od.2 function. Equivalently, each parameter can be explicitly specified.# mym <- power.2(icc = 0.2, r12 = 0.5, r22 = 0.5, c1 = 1, c2 = 5, c1t = 1, c2t = 50,#                     n = 9, p = 0.33, d = 0.3, q = 1, power = 0.8)# mymdes$out  # d = 0.30

figure<-par(mfrow =c (1,2))MDES<-NULLnrange<-c(2:50)for (nin nrange)  MDES<-c(MDES,power.2(expr = myod1,constraint =list (n = n),power =0.8,q =1,m =1702)$out)plot(nrange, MDES,type ="l",lty =1,xlim =c(0,50),ylim =c(0.3,0.8),xlab ="Level-1 sample size: n",ylab ="MDES",main ="",col ="black")abline(v =9,lty =2,col ="Blue")MDES<-NULLprange<-seq(0.05,0.95,by =0.005)for (pin prange)  MDES<-c(MDES,power.2(expr = myod1,constraint =list (p = p),power =0.8,q =1,m =1702)$out)plot(prange, MDES,type ="l",lty =1,xlim =c(0,1),ylim =c(0.3,0.8),xlab ="Porportion groups in treatment: p",ylab ="MDES",main ="",col ="black")abline(v =0.33,lty =2,col ="Blue")

par(figure)

# Required level-2 sample size calculationmyJ<-power.2(cost.model =FALSE,expr = myod1,d =0.3,q =1,power =0.8)# above experssion takes parameters and outputs from od.2 function. Equivalently, each parameter can be explicitly specified.# myJ <- power.2(icc = 0.2, r12 = 0.5, r22 = 0.5,#                     cost.model = FALSE, n = 9, p = 0.33, d = 0.3, q = 1, power = 0.8)myJ$out# J = 59

## $J## [1] 58.99295

# Power calculationmypower1<-power.2(cost.model =FALSE,expr = myod1,J =59,d =0.3,q =1)mypower1$out# power = 0.80

## $power## [1] 0.8000486

# Minimum detectable effect size calculationmymdes1<-power.2(cost.model =FALSE,expr = myod1,J =59,power =0.8,q =1)mymdes1$out# d = 0.30

## $d## [1] 0.2999819

figure<-par(mfrow =c (1,2))pwr<-NULLmrange<-c(300:3000)for (min mrange)  pwr<-c(pwr,power.2(expr = myod1,d =0.3,q =1,m = m)$out)plot(mrange, pwr,type ="l",lty =1,xlim =c(300,3000),ylim =c(0,1),xlab ="Budget",ylab ="Power",main ="",col ="black")abline(v =1702,lty =2,col ="Blue")pwr<-NULLJrange<-c(4:100)for (Jin Jrange)  pwr<-c(pwr,power.2(expr = myod1,cost.model =FALSE,d =0.3,q =1,J = J)$out)plot(Jrange, pwr,type ="l",lty =1,xlim =c(4,100),ylim =c(0,1),xlab ="Level-2 sample size: J",ylab ="Power",main ="",col ="black")abline(v =59,lty =2,col ="Blue")

par(figure)

# ?power.1# ?power.3# ?power.4# ?power.2m# ?power.3m# ?power.4m

Functionre

Calculate the relative efficiency (RE) of two designs, this functionuses the returns fromod function

Based on above examples inod functions, calculate therelative efficiency

# relative efficiency (RE) of a constrained design comparing with the optimal designmyre<-re(od = myod1,subod= myod2)

## The relative efficiency (RE) of the two two-level CRTs is 0.8790305.

myre$re# get the output (i.e., RE = 0.88)

## [1] 0.8790305

# relative efficiency (RE) of a constrained design comparing with the unconstrained optimal onemyre<-re(od = myod1,subod= myod3)

## The relative efficiency (RE) of the two two-level CRTs is 0.8975086.

# relative efficiency (RE) of a constrained design comparing with the unconstrained optimal onemyre<-re(od = myod1,subod= myod4)

## The relative efficiency (RE) of the two two-level CRTs is 0.8266527.

For additional examples, please see example sections in correspondingod functions by uncommenting below lines.

# ?od.1# ?od.2# ?od.3# ?od.4# ?od.2m# ?od.3m# ?od.4m

# Optimal sample allocation and statistical power for randomized controlled trialsmyod<-od.1.111(a = .3,b = .5,c1 =10,c1t =100,verbose =FALSE)mypower<-power.1.111(expr = myod,power = .8)# mypower# Conventional power analysesmypower<-power.1.111(cost.model =FALSE,a = .3,b = .5,test ="joint",power = .8,p =.5)# mypower