Dopt.augment: Function for augmenting a design with D-optimal additional...

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

View source: R/Dopt.augment.R

Description

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

Usage

1
2
3
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
   ## 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)
   

Example output

Loading required package: FrF2
Loading required package: DoE.base
Loading required package: grid
Loading required package: conf.design

Attaching package: 'DoE.base'

The following objects are masked from 'package:stats':

    aov, lm

The following object is masked from 'package:graphics':

    plot.design

The following object is masked from 'package:base':

    lengths

Loading required package: rsm
creating full factorial with 72 runs ...

Call:
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)")

Experimental design of type  Dopt 
36  runs

Factor settings (scale ends):
  eins zwei drei
1  100   10  -25
2  150   20  -15
3  200   30   -5
4  250         5
5             15
6             25

Optimality criteria:
          D        Dea          A          G 
7704.94759    0.57400   25.87194    0.64300 

The design itself:
   eins zwei drei
1   100   10   25
2   250   30   15
3   150   10   25
4   250   10   25
5   100   30   15
6   100   10   -5
7   100   20    5
8   250   10   15
9   200   30   -5
10  100   10   15
11  100   30    5
12  150   30   25
13  150   30  -25
14  250   20   15
15  250   30  -25
16  100   30  -25
17  200   10   25
18  100   30   25
19  200   10   -5
20  250   30  -15
21  200   10  -25
22  100   20   25
23  100   30   -5
24  100   10  -25
25  100   20  -15
26  250   30    5
27  150   20   -5
28  150   10  -25
29  250   10  -25
30  100   20  -25
31  150   30  -15
32  150   20   25
33  250   10   -5
34  200   20   -5
35  250   20   25
36  250   20  -25
class=design, type= Dopt 
creating full factorial with 72 runs ...

Multi-step-call:
[[1]]
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)")

[[2]]
Dopt.augment(r.plan, m = 10)


Experimental design of type  Dopt.augment 
46  runs

Factor settings (scale ends):
  eins zwei drei
1  100   10  -25
2  150   20  -15
3  200   30   -5
4  250         5
5             15
6             25

Optimality criteria:
          D        Dea          A          G 
7989.41609    0.67800   23.13393    0.72000 

Responses:
[1] y
Multi-step-call:
[[1]]
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)")

[[2]]
Dopt.augment(r.plan, m = 10)


Experimental design of type  Dopt.augment 
46  runs

Factor settings (scale ends):
  eins zwei drei
1  100   10  -25
2  150   20  -15
3  200   30   -5
4  250         5
5             15
6             25

Optimality criteria:
          D        Dea          A          G 
7989.41609    0.67800   23.13393    0.72000 

Responses:
[1] y

The design itself:
    eins zwei drei            y
1    100   10   25  0.165165891
2    250   30   15  4.049173744
3    150   10   25 -0.497561991
4    250   10   25  0.415589896
5    100   30   15 -0.578829477
6    100   10   -5  0.353437944
7    100   20    5 -0.458009635
8    250   10   15  0.907762646
9    200   30   -5  0.594144909
10   100   10   15  0.704684057
11   100   30    5  0.293987896
12   150   30   25  0.511790328
13   150   30  -25 -0.154129567
14   250   20   15  0.391230760
15   250   30  -25  0.393092868
16   100   30  -25  1.219362025
17   200   10   25 -0.110762453
18   100   30   25  1.850220832
19   200   10   -5  1.538848408
20   250   30  -15  0.269801339
21   200   10  -25 -0.535841253
22   100   20   25 -0.443960262
23   100   30   -5 -0.751019964
24   100   10  -25 -0.700339963
25   100   20  -15 -0.747196888
26   250   30    5  0.569930912
27   150   20   -5 -0.801239928
28   150   10  -25 -0.331122637
29   250   10  -25 -0.315355607
30   100   20  -25 -0.214420138
31   150   30  -15 -0.001855051
32   150   20   25 -0.465356582
33   250   10   -5 -0.161487472
34   200   20   -5  0.961158087
35   250   20   25  2.254710020
36   250   20  -25 -0.758444119
40   250   10  -25 -0.190539416
99   200   10   25 -1.009786613
45   100   30  -25  0.724731431
37   100   10  -25 -0.786783104
61   100   10   -5 -1.754582180
97   100   10   25 -0.238835329
48   250   30  -25 -0.972513148
96   250   30   15 -0.104141131
78   150   20    5 -0.510437427
105  100   30   25 -0.242342544
class=design, type= Dopt.augment 

DoE.wrapper documentation built on Jan. 11, 2020, 9:28 a.m.