DoE.base (version 0.5)

Class design and accessors: Class design and its accessor functions

Description

Convenience functions to quickly access and modify attributes of data frames of the class design that have been generated by functions FrF2, pb or fac.design

Usage

design
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, value)
response.names(design)
`response.names<-`(design, value)
## S3 method for class 'design':
[(x, i, j, drop.attr = TRUE, drop = FALSE)
## S3 method for class 'design':
print(x, show.order=design.info(x)$type %in% 
       c("FrF2.blocked", "FrF2.splitplot", "crossed", 
         "paramwide", "FrF2.paramwide", "param", "FrF2.param")  | 
       design.info(x)$replications>1, ...)
## S3 method for class 'design':
summary(object, ...)
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

x

data frame of S3 class design, like argument design

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 wit

i

indices for subsetting rows

j

indices for subsetting columns

drop.attr

logical, controls whether or not attributes are dropped; if TRUE, the result is no longer of class design, and all special design attributes are dropped; otherwise, the design attributes are adjusted to reflect the subsetting

drop

logical that controls dropping of dimensions in the Extract function for data.frame objects, which is called by the method for class design

show.order

logical; if TRUE, the design is printed with run order information; default is TRUE for design types for which this information is helpful, FALSE otherwise

...

further arguments to functions print or summary

object

data frame of S3 class design, like argument design

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)

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; the corresponding replacement function modifies a class design object in order to rename factors and/or change labels for 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
• extractor
  The extractor function returns a class design object with modified attributes or a data frame without special attributes, depending on the situation. If j is given, the function always returns a data frame without special attributes, even if drop.attr=FALSE or j=1:ncol(design). If only i is given, the default option drop.attr=TRUE also returns a data frame without attributes. Exception: Even for drop.attr=TRUE, if i is a permutation of the row numbers or a logical vector with all elements TRUE, the attributes are preserved, and attributes run.order and desnum are reordered along with the design, if necessary. If drop.attr=FALSE and j is empty, the function returns an object of class design with rows of attributes run.order and desnum selected in line with those of the design itself. In this case, the new design.info attribute is a list with entries

  • type

  {resolving to subset of design, } subset.rows{ a numeric or logical vector with the selected rows, and} orig.design.info{ which contains the original design.info attribute.}

item

ord

code

NULL

Details

Items of class design are data frames with attributes. They are generated by various functions that create experimental designs, currently by FrF2, pb, oa.design fac.design, and by various utility functions for designs like the above extractor function for class design or fix.design. The data frame itself always contains the design in uncoded form (for all currently implemented design generation functions, these are factors; for future functions for quantitative factors, this may be different). Generally, its attributes are desnum, run.order, and design.info. Attribute desnum contains a numeric coded version of the design, attribute run.order 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 [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object] For some design types, notably designs of types starting with FrF2, there can be substantial additional information available from the design.info attribute in specialized situations. Detailed information on the structure of design.info can be found in the value sections of the respective functions. 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 procudures. Note that the response.names function is not directly able to add new responses from outside the data frame design. This is what the function add.response is for. The extractor method subsets the design, taking care of the attributes accordingly. Subsetting can also handle replication in a limited way, although this is not first choice. Repeated measurements can be added to a design that has no proper replications, and proper replications can be added to a design that has no repeated measurements. The methods for print or summary provide design-specific information - especially the summary method will develop further. If a standard data frame summary is desired, explicitly use function summary.data.frame instead of summary.

See Also

See also the following functions known to produce objects of class design: FrF2, pb, fac.design, oa.design

Examples

oa12 <- oa.design(nlevels=c(2,2,6))
#### Examples for extractor function
  ## subsetting to half the runs drops all attributes per default
  oa12[1:6,]
  ## keep the attributes (usually not reasonable, but ...)
  oa12[1:6, drop.attr=FALSE]
  ## reshuffling a design
  ## (re-)randomize
  oa12[sample(12),]
  ## add repeated measurements
  oa12[rep(1:12,each=3),]
  ## add a proper replication 
  ## (does not work for blocked designs)
  oa12[c(sample(12),sample(12)),]
  ## subsetting and rbinding to loose also contrasts of factors
  str(rbind(oa12[1:2,],oa12[3:12]))
  ## keeping all non-design-related attributes like the contrasts
  str(undesign(oa12))

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

## undesign and redesign
  u.oa12 <- undesign(oa12)
  u.oa12$new <- rnorm(12)
  r.oa12 <- redesign(oa12, u.oa12)
## make known that new is also a respons
  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)