optimal.bira2c1: Model 2.1: COSA Solver for 2-Level Constant Effects Blocked...

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/bira2c1.R


optimal.bira2c1 finds constrained optimal sample allocation (COSA) solutions for designs with 2-levels where level 1 units are randomly assigned to treatment and control groups within level 2 units (school intercepts only). COSA can be found in the following forms, (i) under budgetary constraints given marginal costs per unit, (ii) under power contraints given marginal costs per unit, (iii) under MDES contraints given marginal costs per unit, and (iv) under sample size contraints for one or more levels along with any of the i,ii, or iii options.


  optimal.bira2c1(cn, cJ, cost=NULL, n=NULL, J=NULL,
                 power=.80, mdes=.25, alpha=.05, two.tail=TRUE,
                 nJ0=c(10,10), ncase=10, gm=2,
                 constrain="cost", optimizer="auglag_cobyla",
                 P=.50, g1=0, R12=0)



marginal cost per level 1 unit.


marginal cost per level 2 unit.


total cost or budget.


harmonic mean of level 1 units across level 2 units (or simple average).


level 2 sample size.


statistical power (1 - type II error).


minimum detectable effect size.


probability of type I error.


logical; TRUE for two-tailed hypothesis testing, FALSE for one-tailed hypothesis testing.


vector with a length of two to specifiy starting values for level 1 and level 2 sample sizes.


number of cases to show in the output.


grid multiplier to increase the range of sample size search for each level.


one of the followings can be constrained at a specified cost or value: "cost", "power", or "mdes".


algorithm to find optimal sample sizes given total cost, power, or MDES. Available algorithms: "auglag_cobyla", "auglag_lbfgs", "auglag_mma", or "auglag_slsqp".


average proportion of level 1 units randomly assigned to treatment within level 2 units.


number of covariates at level 1.


proportion of level 1 variance in the outcome explained by level 1 covariates.


Constrained optimal sample allocation (COSA; Hedges & Borenstein, 2014; Raudenbush, 1997; Raudenbush & Liu, 2000) problems are solved using nloptr (Ypma, 2014) package, an implementation of NLopt (Johnson, n.d.) in R (R Core Team, 2016). More specifically, Augmented Lagrangian method is used for global optimization (AUGLAG, Birgin & Martines, 2008; Conn, Gould, & Toint, 1991) in conjuction with one of the following local optimization algorithms: Constrained Optimization by Linear Approximations (COBYLA, Powell, 1994), Low Storage BFGS (LBFGS, Liu & Nocedal, 1989), Method of Moving Asymptotes (MMA, Svanberg, 2002), or Sequental Least-Squares Quadratic Programming (SLSQP, Kraft, 1988). See NLopt website for a brief summary.

nloptr returns values that are not integer. Rounding may produce cost, power or MDES values different from what was specified. A better solution is approximated using brute force. If the constrained value (cost, power or MDES) in the output deviates from what was specified, increasing grid multiplier (gm) often solves the problem. More cases can be printed by increasing ncase.

Further definition of design parameters can be found in Dong & Maynard (2013).



function name.


list of parameters used in the function.


list of nloptr log and output.


solution after rounding. MDES is calculated at the specified power (default .80), and power is calculated at the specified MDES (default .25).


best integer solutions around round.optim solution. MDES is calculated at the specified power (default .80), and power is calculated at the specified MDES (default .25).


Metin Bulus [email protected] Nianbo Dong [email protected]


Birgin, E. G., Martinez, J. M. (2008) Improving ultimate convergence of an augmented Lagrangian method. Optimization Methods and Software 23(2), 177-195.

Conn, A. R., Gould, N. I. M., & Toint, P.L. (1991). A globally convergent augmented Lagrangian algorithm for optimization with general constraints and simple bounds. SIAM J. Numer. Anal. 28(2), 545-572.

Dong, N., & Maynard, R. A. (2013). PowerUp!: A Tool for Calculating Minum Detectable Effect Sizes and Minimum Required Sample Sizes for Experimental and Quasi-Experimental Design Studies,Journal of Research on Educational Effectiveness, 6(1), 24-6.

Hedges, L. V., & Borenstein, M. (2014). Conditional Optimal Design in Three- and Four-Level Experiments. Journal of Educational and Behavioral Statistics, 39(4), 257-281

Hedges, L. & Rhoads, C.(2009). Statistical Power Analysis in Education Research (NCSER 2010-3006). Washington, DC: National Center for Special Education Research, Institute of Education Sciences, U.S. Department of Education. This report is available on the IES website at http://ies.ed.gov/ncser/.

Johnson, S. G. (n.d.). The NLopt nonlinear-optimization package. Package available at http://ab-initio.mit.edu/nlopt.

Kraft, D. (1988). A software package for sequential quadratic programming. Obersfaffeuhofen, Germany: DFVLR.

Liu, D. C., & Nocedal, J. (1989). On the limited memory BFGS method for large scale optimization. Mathematical programming, 45(1-3), 503-528.

Powell, M. J. (1994). A direct search optimization method that models the objective and constraint functions by linear interpolation. In Advances in optimization and numerical analysis (pp. 51-67). Springer Netherlands.

R Core Team (2016). R: A language and environment for statistical computin . R Foundation for Statistical Computing, Vienna, Austria. https://www.R-project.org.

Raudenbush, S. W. (1997). Statistical analysis and optimal design for cluster randomized trials. Psychological Methods, 2, 173-185.

Raudenbush, S. W., & Liu, X. (2000). Statistical power and optimal design for multisite trials. Psychological Methods, 5, 199-213.

Svanberg, K. (2002). A class of globally convergent optimization methods based on conservative convex separable approximations. SIAM journal on optimization, 12(2), 555-573.

Ypma, J. (2014). nloptr: R interface to NLopt. R package version 1.0.4. Package available at https://cran.r-project.org/package=nloptr

See Also

mdes.bira2c1, power.bira2c1, mrss.bira2c1


## Not run: 

     optimal.bira2c1(cn=1, cJ=10, cost=560,

## End(Not run)

Example output

Loading required package: nloptr
[1] "optimal.bira2c1"

[1] 1

[1] 10

[1] 560



[1] 0.8

[1] 0.25

[1] 0.05

[1] TRUE

[1] 10 10

[1] 10

[1] 2

[1] "cost"

[1] "auglag_cobyla"

[1] 0.5

[1] 0

[1] 0

[1] 34.94176 12.46059

[1] 0.009187057

[1] 1001



[1] 5

[1] "NLOPT_MAXEVAL_REACHED: Optimization stopped because maxeval (above) was reached."

      n  J cost  mdes power
[1,] 35 12  540 0.274 0.724

       n  J cost  mdes power
 [1,] 33 13  559 0.271 0.733
 [2,] 37 12  564 0.267 0.748
 [3,] 36 12  552 0.270 0.736
 [4,] 34 13  572 0.267 0.746
 [5,] 32 13  546 0.275 0.720
 [6,] 31 14  574 0.270 0.738
 [7,] 38 12  576 0.263 0.759
 [8,] 35 12  540 0.274 0.724
 [9,] 39 11  539 0.271 0.733
[10,] 35 13  585 0.263 0.758

[1] "pars"

PowerUpR documentation built on May 29, 2017, 2:47 p.m.