godolphin | R Documentation |
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.
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))
design |
a character string that identifies a design in the cataloge specified
by option |
q |
the requested block size is |
all |
if TRUE (default FALSE), all possible X matrices are returned;
otherwise, |
select.catlg |
name of catalogue (not in quotes);
only relevant, if |
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 |
sort |
character string specifying a presort strategy for subgraph
isomorphism search, see |
res3 |
relevant only if |
all0 |
per default ( |
quiet |
if TRUE, the message about failure is suppressed (for using the function
inside other functions, like |
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 |
X |
a |
randomize |
logical. If TRUE, the design is randomized. This is the default.
Randomization is implemented using function
|
seed |
optional seed for the randomization process |
alias.info |
degree of effects aliased with blocks to be included in the
|
profile |
profile to use for calculation
(NULL or integer vector of up to |
parts |
list that provides factor partitions; list entries
must either be all integers from 1 to |
n |
number of factors |
p |
the number of generated factors (among the n factors);
|
XI |
a |
gen |
generators for extending |
num |
if TRUE (default FALSE), Yates column numbers are returned instead of their character representations |
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
.
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).
Ulrike Groemping
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. \Sexpr[results=rd]{tools:::Rd_expr_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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.csda.2020.107059")}. Preprint at Report 3/2019.
plot.igraph
, tkplot
,
plot.common
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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.