Dopt.design {DoE.wrapper}  R Documentation 
Function for comfortably creating a Doptimal design with or without blocking based on functions optFederov or optBlock from package AlgDesign; this functionality is still somewhat experimental.
Dopt.design(nruns, data=NULL, formula=~., factor.names=NULL, nlevels=NULL,
digits=NULL, constraint=NULL, center=FALSE, nRepeats=5, seed=NULL, randomize=TRUE,
blocks=1, block.name="Blocks", wholeBlockData=NULL, qual=NULL, ...)
nruns 
number of runs in the requested design 
data 
data frame or matrix of candidate design points; 
formula 
a model formula (starting with a tilde),
for the estimation of which a Doptimal design is sought; 
factor.names 
is used for creating a candidate set (for the within Block factors)
with the help of function

nlevels 
can be omitted if the list 
digits 
is used for creating a candidate set if 
constraint 
a condition (character string!) used for reducing the candidate
set to admissible points only.

center 
requests that optimization is run for the centered model; the design is nevertheless output in noncentered coordinates 
nRepeats 
number of independent repeats of the design optimization process; increasing this number may improve the chance of finding a global optimum, but will also increase search time 
seed 
seed for generation and randomization of the design (integer number); 
randomize 
logical deciding whether or not the design should be randomized;
if it is 
blocks 
a single integer giving the number of blocks (default 1, if no blocking is needed) 
block.name 
character string: name of the blocking variable (used only if blocks are requested) 
wholeBlockData 
optional matrix or data frame that specifies the whole block characteristics; Since wholeBlockData must be completely specified by the user, optimization is for the splitplot portion of the design only. The rationale is (assumably) that the characteristics of the available blocks are known. If this is not the case, users may want to try out various possible whole block setups, or to proceed sequentially by first optimizing a whole block design for a model with the whole block factors only and subsequently using this model for adding splitplot factors. 
qual 
optional logical (length 1 or same as number of factors); ignored, if 
... 
additional arguments to functions 
Function Dopt.design
creates a Doptimal design, optionally with blocking,
and even as a splitplot design. If no blocks are required, calculations are carried
out through function optFederov
from package AlgDesign.
In case of blocked designs, function optBlock
from package AlgDesign
is behind the calculations. By specifying wholeBlockData
, a blocked design becomes
a splitplot design. The model formula can refer to both the within block data (only those
are referred to by the “.” notation) and the whole block data and interactions between both.
In comparison to direct usage of package AlgDesign, the function adds the possibility
of automatically creating the candidate points on the fly, with or without constraints.
Furthermore, it embeds the Doptimal designs into the class design
.
On the other hand, it sacrifices some of AlgDesigns flexibility; of course, users
can still use AlgDesign directly.
The Doptimal designs are particularly useful, if the classical regular designs are too demanding in run size requirements, or if constraints preclude automatic generation of orthogonal designs. Note, however, that the best design in few runs can still be very bad in absolute terms!
When specifying the design without the data
option, a full factorial in the
requested factors is the default candidate set of design points. For some situations  especially
with many factors  it may be better to start from a restricted candidate set. Such a candidate set
can be produced with another R function, e.g. oa.design
or FrF2
,
or can be manually created.
If there are doubts, whether the process has delivered a design close to the absolute optimum,
nRepeats
can be increased.
For unblocked designs, it is additionally possible to increase maxIteration
.
Also, improving the starting
value by nullify=1
or nullify=2
may lead to an improved design.
These options are handed through to function optFederov
from package AlgDesign and are documented there.
The function returns a data frame of S3 class design
with attributes attached.
The data frame contains the experimental settings.
The matrix desnum
attached as attribute desnum
contains the
model matrix of the design, using the formula as specified in the call.
Function Dopt.augment
preserves additional variables (e.g. responses) that
have been added to the design design
before augmenting. Note, however, that
the response data are NOT used in deciding about which points to augment the design with.
The attribute run.order
provides the run number in standard order (as returned from
function optFederov
in package AlgDesign) as well
as the randomized actual run order. The third column is always identical to the first.
The attribute design.info
is a list of various design properties, with type resolving to “Dopt”,
“Dopt.blocked”, “Dopt.splitplot”.
In addition to the standard list elements (cf. design
), the element
quantitative
is a vector of nfactor
logical values or NAs,
and the optional digits
elements indicates the number of digits to
which the data were rounded.
For blocked and splitplot designs, the list contains additional information on numbers and sizes of blocks or plots,
as well as the number of whole plot factors (which are always the first few factors) and splitplot factors.
The list contains a list of optimality criteria as calculated by function optFederov
,
see documentation there)
with elements D
, Dea
, A
and G
.
(Note that replications
is always 1 and repeat.only
is always FALSE;
these elements are only present to fulfill the formal requirements for class design
.
Note however, that blocked designs do in fact repeat experimental runs if nruns
and blocks
imply this.)
Since R version 3.6.0, the behavior of function sample
has changed
(correction of a biased previous behavior that should not be relevant for the randomization of designs).
For reproducing a design that was produced with an earlier R version,
please follow the steps described with the argument seed
.
This package is still under (slow) development. Reports about bugs and inconveniences are welcome.
Ulrike Groemping
Atkinson, A.C. and Donev, A.N. (1992). Optimum experimental designs. Clarendon Press, Oxford.
Federov, V.V. (1972). Theory of optimal experiments. Academic Press, New York.
Wheeler, R.E. (2004). Comments on algorithmic design. Vignette accompanying package AlgDesign. ../../AlgDesign/doc/AlgDesign.pdf.
See also optFederov
, fac.design
,
quad
, cubic
,
Dopt.augment
. Furthermore, unrelated to function Dopt.design
,
see also function gen_design
from package skpr
for a new general R package for creating Doptimal or other letter optimal designs.
## a full quadratic model with constraint in three quantitative factors
plan < Dopt.design(36,factor.names=list(eins=c(100,250),zwei=c(10,30),drei=c(25,25)),
nlevels=c(4,3,6),
formula=~quad(.),
constraint="!(eins>=200 & zwei==30 & drei==25)")
plan
cor(plan)
y < rnorm(36)
r.plan < add.response(plan, y)
plan2 < Dopt.augment(r.plan, m=10)
plot(plan2)
cor(plan2)
## designs with qualitative factors and blocks for
## an experiment on assessing stories of social situations
## where each subject is a block and receives a deck of 5 stories
plan.v < Dopt.design(480, factor.names=list(cause=c("sick","bad luck","fault"),
consequences=c("alone","children","sick spouse"),
gender=c("Female","Male"),
Age=c("young","medium","old")),
blocks=96,
constraint="!(Age==\"young\" & consequences==\"children\")",
formula=~.+cause:consequences+gender:consequences+Age:cause)
## an experiment on assessing stories of social situations
## with the whole block (=whole plot) factor gender of the assessor
## not run for saving test time on CRAN
## Not run: plan.v.splitplot < Dopt.design(480, factor.names=list(cause=c("sick","bad luck","fault"),
consequences=c("alone","children","sick spouse"),
gender.story=c("Female","Male"),
Age=c("young","medium","old")),
blocks=96,
wholeBlockData=cbind(gender=rep(c("Female","Male"),each=48)),
constraint="!(Age==\"young\" & consequences==\"children\")",
formula=~.+gender+cause:consequences+gender.story:consequences+
gender:consequences+Age:cause+gender:gender.story)
## End(Not run)