class-design: Class design and its accessor functions
In DoE.base: Full Factorials, Orthogonal Arrays and Base Utilities for DoE Packages

Class design and accessors

R Documentation

Class design and its accessor functions

Description

Convenience functions to quickly access and modify attributes of data frames of the class design; methods for the class are described in a separate help topic

Usage

undesign(design)
redesign(design, undesigned)
desnum(design)
desnum(design) <- value
run.order(design)
run.order(design) <- value
design.info(design)
design.info(design) <- value
factor.names(design)
factor.names(design, contr.modify = TRUE, levordold = FALSE) <- value
response.names(design)
response.names(design, remove=FALSE) <- value
col.remove(design, colnames)
ord(matrix, decreasing=FALSE)

Arguments

`design`	data frame of S3 class `design`. For the structures of design objects, refer to the details section and to the value sections of the functions that create them.
`undesigned`	an object that is currently not a design but could be (e.g. obtained by applying function `undesign`
`value`	an appropriate replacement value: a numeric version of the design matrix for function `desnum` (usage not encouraged for non-experts!) a run order data frame for function `run.order` (usage not encouraged for non-experts!) a list with appropriate design information for function `design.info` (usage not encouraged for non-experts!) for function `factor.names<-` a character vector of new factor names (levels remain unchanged) or a named list of level combinations for the factors, like `factor.names` in function `fac.design` for function `response.names<-` a character vector of response names referring to variables which are already available in `design`
`contr.modify`	logical to indicate whether contrasts are to be modified to match the new levels; relevant for R factors only, not for numeric design variables; if `TRUE`, factors with 2 levels get -1/+1 contrasts, factors with more than two quantitative levels get polynomial contrasts with scores identical to the factor levels, and factors with more than two character levels get treatment contrasts; if FALSE, the contrasts remain unchanged from their previous state. If solely the contrasts are to be changed, function `change.contr` is preferrable.
`levordold`	logical to indicate whether the level ordering should follow the old function behavior; the new behavior (from version 0.27) is more plausible, in that the level ordering in the new `factor.names` corresponds to the `factor.names` entry of the `design.info` attribute; previously, the automatic level ordering of factor levels deviated from that order which even led to a changed level order when reassigning exactly the `factor.names` element of the `design.info` attribute
`remove`	logical to indicate whether responses not indicated in `value` are to be removed from the design altogether. If `TRUE`, the respective columns are deleted from the design. Otherwise, the columns remain in the data frame but loose their status as a response variable.
`colnames`	character vector of names of columns to be removed from the design; design factors or the block factor cannot be removed; with non-numeric variables, the `desnum` attribute of the design may have to be manually modified for removing the respective columns in some cases.
`matrix`	matrix, data frame or also object of class design that is to be ordered column by column
`decreasing`	logical, indicates whether decreasing order or not (increasing is default)

Details

Items of class design are data frames with attributes. They are generated by various functions that create experimental designs (cf. see also section), and by various utility functions for designs like the above extractor function for class design.

The data frame itself always contains the design in uncoded form. For many design generation functions, these are factors. For designs for quantitative factors (bbd, ccd, lhs, 2-level designs with center points), the design variables are numeric. This is always indicated by the design.info element quantitative, for which all components are TRUE in that case.

Generally, its attributes are desnum, run.order, and design.info.
Attribute desnum contains a numeric coded version of the design. For factor design variables, the content of desnum depends on the contrast information of the factors (cf. change.contr for modifying this).
Attribute run.order is a data frame with run order information (standard order, randomized order, order with replication info),
and the details of design.info partly depend on the type of design.

design.info generally is a list with first element type, further info on the design, and some options of the design call regarding randomization and replication. For almost all design types, elements include

nruns: number of runs (not adjusted for replications)
nfactors: number of factors
factor.names: named list, as can be handed to function oa.design
replications: the integer number of replications (1=unreplicated)
repeat.only: logical indicating whether replications are only repeat runs but not truly replicated
randomize: logical indicating whether the experiment was randomized
seed: integer seed for the random number generator
note that the randomization behavior has changed with R version 3.6.0;
section "Warning" provides information on reproducing randomized designs.
response.names: in the presence of response data only; the character vector identifying response columns in the data frame
creator: contains the call or the list of menu settings within package RcmdrPlugin.DoE that led to creation of the design.
Note that the randomization behavior has changed with R version 3.6.0;
section "Warning" provides information on reproducing randomized designs.

For some design types, notably designs of types starting with “FrF2” and designs that have been created by combining other designs, there can be substantial additional information available from the design.info attribute in specialized situations. Detailed information on the structure of the design.info attribute can be found in the value sections of the respective functions. A tabular overview of the available design.info elements is given on the authors homepage.

Function undesign removes all design-related attributes from a class design object; this may be necessary for making some independent code work on design objects. (For example, function reshape from package stats does not work on a class design object, presumably because of the specific extractor method for class design.) Occasionally, one may also want to reconnect a processed undesigned object to its design properties. This is the purpose of function redesign.

The functions desnum, run.order, and design.info extract the respective attribute, i.e. e.g. function design.info extracts the design information for the design. The corresponding assignment functions should only be used by very experienced users, as they may mess up things badly if they are used naively .

The functions factor.names and response.names extract the respective elements of the design.info attribute. The corresponding assignment functions allow to change factor names and/or factor codes and to exclude or include a numeric variable from the list of responses that are recognized as such by analysis procedures. Note that the response.names function can (on request, not by default) remove response variables from the data frame design. However, it is not directly able to add new responses from outside the data frame design. This is what the function add.response is for.

Function col.remove removes columns from the design and returns the design without these columns and an intact class design structure.

Value

`desnum`	returns a numeric matrix, the corresponding replacement function modifies a class design object
`run.order`	returns a 3-column data frame with standard and actual run order as well as a run order with replication identifiers attached; the corresponding replacement function modifies a class design object
`design.info`	returns the `design.info` attribute of the design; the corresponding replacement function modifies a class design object
`factor.names`	returns a named list the names of which are the names of the treatment factors of the design while the list elements are the vectors of levels for each factor
`'factor.names<-'`	returns a class `design` object with modified factor names information (renamed factors and/or changed factor levels);
`response.names`	returns a character vector of response names that (names of numeric variables within the data frame `design` that are to be treated as response variables ) ; the corresponding replacement function modifies the design
`'response.names<-'`	returns a class `design` object with modified response names information (add or remove numeric columns of the design to or from set of response variables), and potentially response columns removed from the design.
`col.remove`	returns a class `design` object with some columns removed from both the design itself and the `desnum` attribute. Response columns may be removed, but factor or block columns may not.
`ord`	returns an index vector that orders the matrix or data frame; for example, `design[ord(design),]` orders the design in increasing order with respect to the first, then the second etc. factor.

Warning

Function sample is used for the randomization functionality of this package. With R version 3.6.0, the behavior of this function has changed. Since the R version is not stored with a class design object, please check carefully if a design you want to reproduce based on a given creator or seed element of the design.info attribute has the expected randomization order.

The randomization order of a design that was created with the default settings under R version 3.6.0 or newer can only be reproduced with such a new R version.
If an R version 3.6.0 or newer is used for reproducing the randomization order of a randomized design that was created with an R version before 3.6.0, the RNGkind setting has to be modified:
RNGkind(sample.kind="Rounding")
activates the old behavior,
RNGkind(sample.kind="default")
switches back to the recommended new behavior.
For an example, see the documentation of the example data set VSGFS.

Note

Note that R contains a few functions that generate or work with an S class design, which is cursorily documented in Appendix B of the white book (Chambers and Hastie 1993) to consist of a data frame of R factors which will later be extended by numeric response columns. Most class design objects as defined in packages DoE.base and FrF2 are also compatible with this older class design; they are not, however, as soon as quantitative factors are involved, like for designs with center points in package FrF2 or for most designs in package DoE.wrapper (not yet on CRAN). If feasible with reasonable effort and useful, functions for the class design documented here incorporate the functions for the S class design (notably function plot.design).

This package is still under development; suggestions and bug reports are welcome.

Author(s)

Ulrike Groemping

References

Chambers, J.M. and Hastie, T.J. (1993). Statistical Models in S, Chapman and Hall, London.

Examples

oa12 <- oa.design(nlevels=c(2,2,6))


#### Examples for factor.names and response.names
  factor.names(oa12)
  ## rename factors
  factor.names(oa12) <- c("First.Factor", "Second.Factor", "Third.Factor")
  ## rename factors and relabel levels of first two factors
  namen <- c(rep(list(c("current","new")),2),list(""))
  names(namen) <- c("First.Factor", "Second.Factor", "Third.Factor")
  factor.names(oa12) <- namen
  oa12

  ## add a few variables to oa12
  responses <- cbind(temp=sample(23:34),y1=rexp(12),y2=runif(12))
  oa12 <- add.response(oa12, responses)
  response.names(oa12)
  ## temp (for temperature) is not meant to be a response 
  ## --> drop it from responselist but not from data
  response.names(oa12) <- c("y1","y2")

## looking at attributes of the design
  desnum(oa12)
  run.order(oa12)
  design.info(oa12)

## undesign and redesign
  u.oa12 <- undesign(oa12)
  str(u.oa12)  
  u.oa12$new <- rnorm(12)
  r.oa12 <- redesign(oa12, u.oa12)
## make known that new is also a response
  response.names(r.oa12) <- c(response.names(r.oa12), "new") 
## look at design-specific summary
  summary(r.oa12)
## look at data frame style summary instead
  summary.data.frame(r.oa12)

DoE.base documentation built on Nov. 15, 2023, 1:06 a.m.