godolphin {FrF2}

Functions in support of Godolphin's approach for blocking designs

Description

Function colpick handles the creation of X matrices for blocking, function FF_from_X blocks a full factorial, function X_from_profile creates an X matrix from a profile, function phimax calculations the maximum number of clear 2fis from Godolphin's approach. Further helper functions support the use of the method. The functions are meant for expert users only.

Usage

colpick(design, q, all = FALSE, select.catlg = catlg, 
      estimable = NULL, method = "VF2", sort = "natural",
      res3 = FALSE, all0 = FALSE, quiet = FALSE, 
      firsthit = is.numeric(design))
FF_from_X(X, randomize = TRUE, seed = NULL, alias.info=2)
X_from_profile(n, q, profile = NULL)
clear2fis_from_profile(n, q, profile = NULL)
X_from_parts(n, q, parts)
phimax(n, q, profile = NULL)
blockgencreate(X, p = 0)
Xcalc(XI, gen)
blockgengroup(X, p = 0, num = FALSE)
colpickIV(design, q, all = FALSE, select.catlg = catlg, 
      estimable = NULL, method = "VF2", sort = "natural",
      res3 = FALSE, all0 = FALSE, quiet = FALSE, 
      firsthit = is.numeric(design))

Arguments

design

a character string that identifies a design in the cataloge specified by option select.catlg,
OR a class catlg object with a single entry (of longer, only the first one is used),
OR an integer number of factors for which a full factorial is assumed.

q

the requested block size is 2^q

all

if TRUE (default FALSE), all possible X matrices are returned; otherwise, colpick returns the first successful one (if estimable is not NULL) or the best one (otherwise)

select.catlg

name of catalogue (not in quotes); only relevant, if design is a character string

estimable

a specification of 2fis to be kept clear in the blocked design, either as a character vector of pairs of factor letters (using the first elements of 'Letters') or as a two-row matrix of pairs of factor numbers occurring in 2fis)

method

character string identifying a subgraph isomorphism method (VF2 or LAD), see FrF2

sort

character string specifying a presort strategy for subgraph isomorphism search, see FrF2

res3

relevant only if estimable is not NULL;
per default (res3=FALSE), design will yield no result, if it has resolution III only; set res3 to TRUE for allowing a design of resolution III (almost never useful)

all0

per default (all0=FALSE), X matrices are requested to be free of all-zero columns. Set all0 to TRUE for permitting aliasing between blocks and factor main effects, i.e. for finding a suitable split-plot constructor.

quiet

if TRUE, the message about failure is suppressed (for using the function inside other functions, like FrF2)

firsthit

if TRUE, the function does not attempt to optimize the number of clear 2fis but accepts the first acceptable blocking (relevant for non-null estimable only);
per default, optimizing is suppressed for full factorials only (where it is not very reasonable to use function colpick instead of simply hand-crafting an X matrix; function FrF2 sets it to FALSE for creation of full factorials with estimability requirements);
for large applications with estimability requirements, specifying firsthit as TRUE may allow to inspect more candidates and to then possibly deepdive some of them

X

a q \times n X matrix with only 0/1 elements for block construction

randomize

logical. If TRUE, the design is randomized. This is the default. Randomization is implemented using function rerandomize.design of package DoE.base as the last step in design creation.

seed

optional seed for the randomization process
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 FrF2.
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.

alias.info

degree of effects aliased with blocks to be included in the design.info attribute

profile

profile to use for calculation (NULL or integer vector of up to 2^q-1 elements that sum to n); if NULL, the maximally balanced profile is used (which yields the overall maximum number of clear 2fis when blocking a full factorial)

parts

list that provides factor partitions; list entries must either be all integers from 1 to n or the elements of Letters[1:n]

n

number of factors

p

the number of generated factors (among the n factors); 2^{n-p} is the number of runs in the experiment)

XI

a q \times k X_I matrix with only 0/1 elements, to be extended into a q \times n X matrix for block construction, given the generators in gen (k=n-p)

gen

generators for extending XI: gen can be
a class catlg object (e.g. catlg["7-2.1"] or catlg[nruns(catlg)==32 & nfac(catlg)==7]); each nfac entry must be the sum of k and the length of the gen element)
a vector of Yates column numbers (e.g. c(7, 27))
a vector of defining contrasts (e.g. c("ABC","ABDE")) a list of vectors of base column numbers

num

if TRUE (default FALSE), Yates column numbers are returned instead of their character representations

Details

These are the functions for the Godolphin (2021) approach to blocking; most of them are user-visible. This approach and its implementation are described in Groemping (2021). Direct use of this functions is intended for expert use only.

Function colpick is the main workhorse function for blocking larger situations in function FrF2 (since version 2 of the package, it replaces the earlier approach with function blockpick.big); it makes use of function blockgencreate, and of the internal function blockgengroup.

Function FF_from_X creates a class design object. Design size is limited by computer memory and run time. The function can use an X matrix that was produced by function colpick; but note that it is quite easy to hand-craft an X matrix for a full factorial, even with estimability requirements. The light-weight function does not have arguments for customization; it can be post-processed, however, e.g. using function factor.names<-.

Function X_from_profile creates an X matrix that corresponds to the specified profile.

Function phimax returns the maximum number of 2fis that can be kept clear when blocking a full factorial design in n factors into blocks of size 2^q, given the specified profile.

Function blockgencreate creates block generators from an X matrix for blocking a design in 2^{n-p}=2^k runs into blocks of size 2^q, where n and q are derived from X as the number of columns and rows, respectively. The generators are returned as a character vector that consists of strings of base factor letters.

Function Xcalc extends a q\times k matrix X_I by p=n-k columns (X_II in Godolphin notatation) based on the generators provided in gen.

Function blockgengroup is internal only, as are functions colpickIV and clear2fis_from_profile.

Value

Function colpick returns a list of at least two elements:
if all is FALSE, the list consists of the matrix X, the character vector clear.2fis and possibly the integer vector map,
otherwise of list-valued elements X_matrices, clearlist and profiles and maplist.

Function FF_from_X returns a class design object of type FrF2.blocked.

Function phimax returns a real number.

Function blockgencreate returns a character vector of generators in terms of Letters combinations of the first $n-p$ factors.

Function Xcalc returns a q\times n matrix (in case of a single generator) or a list of such matrices (if gen is a class catlg object with more than one element).

The internal function blockgengroup returns a character vector of all effects (denoted as base column letter combinations) aliased with the block main effect, or corresponding Yates column numbers.

The internal function colpickIV returns almost the same type of results as colpick. The difference:
if all is TRUE, there is an integer vector map instead of the maplist element, because the map does not depend on the choice of X-matrix (separate subgraph isomorphism checking is skipped with this function).

Author(s)

Ulrike Groemping

References

Groemping, U. (2012). Creating clear designs: a graph-based algorithm and a catalogue of clear compromise plans. IIE Transactions 44, 988–1001. Early preprint available at http://www1.bht-berlin.de/FB_II/reports/Report-2010-005.pdf.

Godolphin, J. (2021). Construction of Blocked Factorial Designs to Estimate Main Effects and Selected Two-Factor Interactions. J. Royal Statistical Society B 83, 5-29. doi: 10.1111/rssb.12397.

Groemping, U. (2021). An algorithm for blocking regular fractional factorial 2-level designs with clear two-factor interactions. Computational Statistics and Data Analysis 153, 1-18. doi: 10.1016/j.csda.2020.107059. Preprint at Report 3/2019.

See Also

plot.igraph, tkplot, plot.common

Examples

phimax(7, 2)  ## 16 2fis can be clear, if 128 run full factorial is blocked 
              ## into 32 blocks of size 2^2=4

## X matrices for blocking full factorials
## do not care about which factors have which role
X_from_profile(7, 2, c(3,2,2))
   # X_from_profile(7, 2, c(2,2,3)) returns same matrix
## ensure specific partition, i.e. specific requirement CIG to be accommodated
X <- X_from_parts(7, 2, parts=list(c("A","D","F"), c("B","G"), c("C","E")))

## blocked full factorial
summary(FF_from_X(X))

## using colpick
## estimable in standard letters
requ <- c("BA", "BC", "BD", "BE", "BF", "BG", "BH", "BJ")
## estimability requirement in factor names
fn <- Letters[15:23] ## P to X
requfn <- requ
requfn <- sapply(1:8, function(obj) gsub(Letters[obj], fn[obj], requfn[obj]))

## obtain X matrix for accommodating estimability requirement in 9-4.2
(aus <- colpick("9-4.2", 2, estimable=requ))
## obtain the same matrix manually with Xcalc
XI <- aus$X[,1:5]
## obtain the same matrix manually with Xcalc
all(Xcalc(XI, catlg["9-4.2"])==aus$X)
## inspect X matrices generated from XI
Xcalc(XI, catlg[nruns(catlg)==32 & nfac(catlg)==9 & res(catlg)>=4])

## factor permutation needed
aus$map
## calculate block generators
blockgencreate(aus$X, p=4)
## automatic creation from the design 9-4.2 uses these block generators
summary(FrF2(32, 9, blocks=8, estimable=requ, factor.names=fn, 
    alias.block.2fis = TRUE, select.catlg = catlg["9-4.2"]), 
    brief=TRUE)
## can also be reproduced manually (internal function invperm does the permuting)
summary(FrF2(design="9-4.2", blocks=blockgencreate(aus$X, p=4), 
    factor.names=fn[FrF2:::invperm(aus$map)], 
    alias.block.2fis = TRUE), 
    brief=TRUE)