# godolphin: Functions in support of Godolphin's approach for blocking... In FrF2: Fractional Factorial Designs with 2-Level Factors

 godolphin R Documentation

## 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 \code{q} times \code{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).

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.

Gr<f6>mping, 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.

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

FrF2 documentation built on May 9, 2022, 5:07 p.m.