# Boptbd: Bayesain optimal block designs In Boptbd: Bayesian Optimal Block Designs

## Description

The function `Boptbd` is used to compute Bayesian A- or D-optimal block designs under the linear mixed effects model settings using array/block exchange algorithm of Debusho, Gemechu and Haines (2018).

## Usage

 ```1 2 3 4 5 6 7 8``` ```Boptbd(trt.N, blk.N, alpha, beta, nrep, brep, itr.cvrgval, Optcrit = "", ...) ## Default S3 method: Boptbd(trt.N, blk.N, alpha, beta, nrep, brep, itr.cvrgval, Optcrit = "", ...) ## S3 method for class 'Boptbd' print(x, ...) ## S3 method for class 'Boptbd' summary(object, ...) ```

## Arguments

 `trt.N` integer, specifying number of treatments, `v`. `blk.N` integer, specifying number of blocks, `b`. `alpha` numeric, representing the shape parameter of beta distribution. `beta` numeric, representing the shape parameter of beta distribution. `nrep` integer, specifying number of replications of the optimization procedure. `brep` integer, specifying number of Monte Carlo samples from a prior beta distribution. `itr.cvrgval` integer, specifying number of iterations required for convergence during the block exchange procedure. `Optcrit` character, specifying the optimality criteria to be used. `Optcrit` takes the letter `"A"` and `"D"` for Bayesian `A-` and `D-`optimal block designs, respectively. `x` the object to be printed. `object` an object of class `"Boptbd"`. `...` not used.

## Details

`Boptbd` computes Bayesian optimal block designs where the interest is in a comparison of all possible elementary treatment contrasts. Under the linear mixed effects model setting, where the block effects are assumed to be random, the treatment information matrix (C-matrix) is dependent on the unknown parameter `rho` (ratio of unknown variance components of random error and block effects). A Bayesian optimal design extends the locally optimal approach by specifying a prior distribution for the parameter `rho`. `Boptbd` function computes Bayesian `A-` and `D-`optimal block designs via calling of two sub-functions `Baoptbd` and `Bdoptbd`, respectively. Each function requires an initial connected block designs generated using the function `intcbd`.

The minimum value of `trt.N` and `blk.N` is 3 and `trt.N` should be less than or equal to `blk.N - 1`.

`Boptbd` perform the block exchange procedure through deletion and addition of candidate block at a time and selects a design with best block exchange with respect to the optimality criterion value. It uses the steps of Bueno Filho and Gilmour (2007) for numerical evaluation of the Bayesian criterion values.

`nrep` takes a value of greater than or equal to 2. However, to ensure optimality of the resultant design, the `nrep` should be greater than or equal to 10 and in addition, as `trt.N` and `blk.N` increase, to ensure optimality of resultant design, it is advised to further increase the value of `nrep` up to greater than or equal to 100. `brep` takes a value of greater than or equal to 2. As `brep` value increase, the execution time to generate Bayesian optimal design increase.

`itr.cvrgval` number of iterations during exchange procedure. It takes a value between 2 and `blk.N`. It is used to speedup the computer search time by setting how long should the user should wait for the exchange process to obtain any different (if any) design than the one that was produced as the result of the preceding exchange of the current array in the initial design with candidate array. This is mainly effective if `blk.N` is very large. For example `itr.cvrgval = 2`, means the exchange procedure will jump to the next block test if the exchange of the two preceding blocks with candidate block results with the same efficient designs. The function will not give error message if the users set `itr.cvrgval > blk.N` and it will automatically set `itr.cvrgval = blk.N`. The smaller the `itr.cvrgval` means the faster the exchange procedure is, but this will reduce the chance of getting optimal block design and users are advised to set `itr.cvrgval` closer to `blk.N`.

## Value

Returns the resultant Bayesian A- or D-optimal block design with its corresponding score value and parametric combination saved in excel file in a temporary directory. In addition, the function `Boptbd` displays the graphical layout of the resultant Bayesian optimal block designs. Specifically:

 `call` the method call. `v` number of treatments. `b` number of blocks `alpha` alpha value. `beta` beta value. `nrep` number of replications of the optimization procedure. `itr.cvrgval` number of iterations required for convergence during the exchange procedure. `Optcrit` optimality criteria. `brep` umber of Monte Carlo samples from a prior beta distribution. `OptdesF` a `2 x b` obtained Bayesain optimal block design. `Optcrtsv` score value of the optimality criteria `'Optcrit'` of the resultant Bayesian optimal block design `'OptdesF'`. `file_loc, file_loc2` location where the summary of the resultant Bayesian optimal block design is saved in .csv format. `equireplicate` logical value indicating whether the resultant Bayesian optimal block design is equireplicate or not. `vtrtrep` vector of treatment replication of the resultant Bayesian optimal block design. `Cmat` the C-matrix or treatment information matrix of the Bayesian optimal block design.

The graphical layout of the resultant Bayesain optimal block design.

NB: The function "Boptbd" also saves the summary of the resultant Bayesian optimal block design in .csv format in a temporary directory. Furthermore, this function reports only one final optimal block design, however, there is a possibility of more than one optimal block designs for a given parametric combination. The function `graphoptBbd` can be used to view and rearrange the graphical layout of the resultant optimal block design on `tcltk` window. Alternative to the function `Boptbd`, a GUI tcltk window can be used to generate Bayesain optimal block designs, see `mmenuBbd` and `fixparBbd`.

## Author(s)

Dibaba Bayisa Gemechu, Legesse Kassa Debusho, and Linda Haines

## References

Bueno Filho, J. S. de S., Gilmour, S. G. and Rosa, G. J. M. (2006). Design of microarray experiments for genetical genomics studies. Genetics, 174, 945-957

Debusho, L. K., Gemechu, D. B. and Haines, L. (2018). Algorithmic construction of optimal block designs for two-colour cDNA microarray experiments using the linear mixed effects model. Communications in Statistics - Simulation and Computation, https://doi.org/10.1080/03610918.2018.1429617.

Gemechu D. B., Debusho L. K. and Haines L. M. (2014). A-optimal designs for two-colour cDNA microarray experiments using the linear mixed effects model. Peer-reviewed Proceedings of the Annual Conference of the South African Statistical Association for 2014 (SASA 2014), Rhodes University, Grahamstown, South Africa. pp 33-40, ISBN: 978-1-86822-659-7.

`mmenuBbd`, `fixparBbd`, `intcbd`

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14``` ``` ##To obtain Bayesian A-optimal block design for the following treatment combintions: trt.N <- 3 #Number of treatments blk.N <- 3 #Number of blocks alpha <- 0.1 #alpha value beta <- 0.1 #beta value nrep <- 5 #Number of replications brep <- 5 #Number of Monte Carlo samples from a prior beta distribution, Beta(0.1, 0.1) itr.cvrgval <- 6 #Number of iterations required during the exchange procedure Optcrit <- "A" #Optimality criteria Baoptbd_example <- Boptbd(trt.N = 3, blk.N = 3, alpha = 0.1, beta = 0.1, nrep = 5, brep = 5, itr.cvrgval = 6, Optcrit = "A") summary(Baoptbd_example) ```

### Example output ```Loading required package: MASS

Attaching package: ‘igraph’

The following objects are masked from ‘package:stats’:

decompose, spectrum

The following object is masked from ‘package:base’:

union

Warning message:
no DISPLAY variable so Tk is not available

---------------------------------------
Title:  Bayesian A-optimal block design        Date: Sun Apr 18 2021 18:45:58
---------------------------------------
Call:
Boptbd.default(trt.N = 3, blk.N = 3, alpha = 0.1, beta = 0.1,
nrep = 5, brep = 5, itr.cvrgval = 6, Optcrit = "A")

Parametric combinations:

Number of treatments:           3
Number of blocks:               3
Alpha value:                    0.1
Beta value:                     0.1
Number of MC selections:        5
Number of replications:         5
Number of exchange iteration:   3
Optimality criterion used:  Bayesian A-optimality criteria

Resultant Bayesian A-optimal block design:

blk1 blk2 blk3
1    1    2    1
2    2    3    3

A-Score value:  1.218951

Summary of obtained Bayesian A-optimal block design is also saved at:
/work/tmp/tmp/Rtmpf2WLzC/Aoptbd_summary.csv
```

Boptbd documentation built on March 26, 2020, 8:38 p.m.