Dopt.augment {DoE.wrapper}

Function for augmenting a design with D-optimal additional points using optFederov from package AlgDesign

Description

Function for comfortably augmenting a design with D-optimal additional points; this functionality is still somewhat experimental.

Usage

Dopt.augment(design, m=1, formula=NULL, candidates=NULL, constraint=NULL, 
    center=FALSE, nRepeats=5, 
    seed=NULL, randomize=TRUE, ...)

Arguments

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.

m

integer number of additional points to add to design design

formula

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).

candidates

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

constraint

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.

center

requests that optimization is run for the centered model; the design is nevertheless output in non-centered 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);
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.

randomize

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.

Details

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.

Value

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.)

Warning

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.

Note

This package is still under (slow) development. Reports about bugs and inconveniences are welcome.

Author(s)

Ulrike Groemping

References

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

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.

Examples

   ## 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)