Function for comfortably augmenting a design with D-optimal additional points; this functionality is still somewhat experimental.
Dopt.augment(design, m=1, formula=NULL, candidates=NULL, constraint=NULL,
center=FALSE, nRepeats=5,
seed=NULL, randomize=TRUE, ...)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.
Note that the first n runs (the ones that are already present before augmentation)
have run numbers in standard order from 1 to n (i.e. their original run numbers
in standard order, if they were also generated by Dopt.design are lost).
The attribute design.info is a list of various design properties, with type resolving to “Dopt.augment”.
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.
The list contains further entries regarding the optimality that has been achieved
(D, Dea and A).
Note that the original design is contained in the first rows of the new data set.
The original design also contains columns that are not directly part of the
design, e.g. comment columns.
Note that replications is always set to 1, even if the original design was
replicated, and repeat.only is always FALSE.
These elements are only present to fulfill the formal requirements for class design.)
an experimental design of class design,
which may not be a blocked, split-plot, neither
crossed or parameter design; it also must not be replicated with repeat.only replications.
integer number of additional points to add to design design
a model formula (starting with a tilde), for the estimation of which a D-optimal design is sought;
it can contain all column names from data
or elements or element names from factor.names, respectively;
usage of the “.”-notation for “all variables” from data or factor.names
is possible.
The default formula (if the value NULL is not changed) is the formula associated with
the design (by function formula.design).
For quantitative factors, functions quad() and cubic describe the
full quadratic or full cubic model in the listed variables (cf. examples
and the expand.formula-function from package AlgDesign).
data frame of candidate points; if not specified, candidates
are constructed as a full factorial from the
factor.names element of the design.info attribute of design
a condition (character string!) used for reducing the candidate
set to admissible points only.
constraint is evaluated on the specified data set or after automatic creation
of a full factorial candidate data set.
The variable names from data or factor.names can be used by the constraint.
Per default (i.e. if the constraint is NULL), the constraint attribute from
design is used.
If a previously-applied constraint is to be removed, specify constraint = "".
It is not possible to apply a constraint that is already violated by the
design that is to be augmented.
requests that optimization is run for the centered model; the design is nevertheless output in non-centered coordinates
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 for generation and randomization of the design (integer number);
here, the seed is needed even if the design is not randomized, because the
generation process for the optimum design involves random numbers, even if the
order of the final design is not randomized;
if a reproducible design is needed, it is therefore recommended to specify a seed
In R version 3.6.0 and later, the default behavior of function sample
has changed. If you work in a new (i.e., >= 3.6.-0) R version and want to reproduce
a randomized design from an earlier R version (before 3.6.0),
you have to change the RNGkind setting by
RNGkind(sample.kind="Rounding")
before running function Dopt.augment.
It is recommended to change the setting back to the new recommended way afterwards:
RNGkind(sample.kind="default")
For an example, see the documentation of the example data set VSGFS.
logical deciding whether or not the design should be randomized;
if it is TRUE, the design (or the additional portion of the design) returned by the
workhorse function optFederov is brought
into random order after generation. Note that the generation process
itself contains a random element per default; if exact repeatability for the
returned design is desired, it is necessary to specify a seed (option seed)
if in the case randomize=FALSE.
additional arguments to function optFederov
from package AlgDesign;
interesting arguments: maxIteration,
nullify (calculate good starting design, especially set to 1,
in which case nRepeats is set to 1;
arguments criterion and augment are not available, neither
are evaluateI, space, or rows, and args
does not have an effect.
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.
Ulrike Groemping
Function Dopt.augment augments an existing design by m D-optimal
additional points (unblocked designs, no split-plot, no parameter or crossed design,
no repeat.only replications), i.e. by points that make the design particularly efficient
for the intended model.
Option center, which is available for both blocked and unblocked designs as part of the ... argument,
requests optimization for the centered model; the design that is created is nevertheless an uncentered design.
NULL entries in the arguments are filled with automatic values that are determined
from design.
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.design. Furthermore, unrelated to function Dopt.augment,
see also function gen_design from package skpr
for a new general R package for creating D-optimal 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)")
summary(plan)
y <- rnorm(36)
r.plan <- add.response(plan, y)
plan2 <- Dopt.augment(r.plan, m=10)
summary(plan2)
## add the new response values after conducting additional experiments
y <- c(y, rnorm(10))
r.plan2 <- add.response(plan2,y, replace=TRUE)
summary(r.plan2, brief=FALSE)
Run the code above in your browser using DataLab