fac.design: Function for full factorial designs

View source: R/fac.design.R

fac.designR Documentation

Function for full factorial designs


Function for creating full factorial designs with arbitrary numbers of levels, and potentially with blocking


fac.design(nlevels=NULL, nfactors=NULL, factor.names = NULL, 
        replications=1, repeat.only = FALSE, randomize=TRUE, seed=NULL, 
        blocks=1, block.gen=NULL, block.name="Blocks", bbreps=replications, 
        wbreps=1, block.old.behavior=FALSE)



number(s) of levels, vector with nfactors entries or single number; can be omitted, if obvious from factor.names


number of factors, can be omitted if obvious from entries nlevels or factor.names


if nlevels is given, factor.names can be a character vector of factor names. In this case, default factor levels are the numbers from 1 to the number of levels for each factor.
Otherwise it must be a list of vectors with factor levels. If the list is named, list names represent factor names, otherwise default factor names are used. Default factor names are the first elements of the character vector Letters, or the factors position numbers preceded by capital F in case of more than 50 factors. If both nlevels and factor.names are given, they must be compatible.


positive integer number. Default 1 (i.e. each row just once). If larger, each design run is executed replication times. If repeat.only, repeated measurements are carried out directly in sequence, i.e. no true replication takes place, and all the repeat runs are conducted together. It is likely that the error variation generated by such a procedure will be too small, so that average values should be analyzed for an unreplicated design.

Otherwise (default), the full experiment is first carried out once, then for the second replication and so forth. In case of randomization, each such blocks is randomized separately. In this case, replication variance is more likely suitable for usage as error variance (unless e.g. the same parts are used for replication runs although build variation is important).


logical, relevant only if replications > 1. If TRUE, replications of each run are grouped together (repeated measurement rather than true replication). The default is repeat.only=FALSE, i.e. the complete experiment is conducted in replications blocks, and each run occurs in each block.


logical. If TRUE, the design is randomized. This is the default. In case of replications, the nature of randomization depends on the setting of option repeat.only.


integer seed for the random number generator
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
before running function fac.design.
It is recommended to change the setting back to the new recommended way afterwards:
For an example, see the documentation of the example data set VSGFS.


is the number of blocks into which the experiment is to be subdivided;
it must be a prime or a product of prime numbers which occur as common divisors of the numbers of levels of several factors (cf. Details section).

If the experiment is randomized, randomization happens within blocks.


provides block generating information.
Only specify block.gen, if blocks>1.
If blocks is a prime or a power of 2 (up to 2^8) or 3 (up to 3^5) or a product of powers of 2, 3, and an individual other prime, block.gen is not needed (but can be optionally specified).
If given, block.gen can be
a numeric vector of integer numbers that will be treated as a one-row matrix
OR a numeric matrix with integer elements.

There must be a row for each prime number into which blocks factorizes, and a column for each (pseudo)factor into which the experimental design factors can be partitioned (cf. Details and Examples sections and function factorize).

Rows for a p-level contributor to the block factor (p a prime) consist of entries 0 to p-1 only.


name of the block factor, default “Blocks”


between block replications; these are always taken as genuine replications, not repeat runs; default: equal to replications; CAUTION: you should not modify bbreps if you do not work with blocks, because the program code uses it instead of replications in some places


within block replications; whether or not these are taken as genuine replications depends on the setting of repeat.only


logical that can be used to activate the old (prior to version 0.27) behavior of blocking full factorial designs; the new behavior is the default, as it often creates designs with less severe confounding


fac.design creates full factorial designs, i.e. the number of runs is the product of all numbers of levels.

It is possible to subdivide the design into blocks (one hierarchy level only) by specifying an appropriate number of blocks. The method used is a generalization of the one implemented in function conf.design for symmetric factorials (i.e. factorials with all factors at the same prime number of levels) and related to the method described in Collings (1984, 1989); function conf.set from package conf.design is used for checking the confounding consequences of blocking.

Note that the number of blocks must be compatible with the factor levels; it must factor into primes that occur with high enough frequency among the pseudo-factors of the design. This statement is now explained by an example: Consider a design with five factors at 2, 2, 3, 3, 6 levels. The 6-level factor can be thought of as consisting of two pseudo-factors, a 2-level and a 3-level pseudo-factor, according to the factorization of the number 6 into the two primes 2 and 3. It is possible
to obtain two blocks by confounding the two-factor interaction of the two 2-level factors and the 2-level pseudo-factor of the 6-level factor,
or to obtain three blocks by confounding the blocking factor with the three-factor interaction of the two three-level factors and the three-level pseudo-factor of the 6-level factor,
or to get six blocks, by doing both simultaneously.
It is also possible to obtain 4 or 9 or even 36 blocks, if one is happy to confound two-factor interactions with blocks. The 36 blocks are the product of the 4 blocks from the 2-level portion with the nine blocks from the 3-level portion. For each portion separately, there is a lookup-table for blocking possibilities (block.catlg), for up to 128 blocks in 256 runs, or up to 81 blocks in 243 runs.

5 blocks cannot be done for the above example design. Even if there were one additional factor at 5 levels, it would still not be possible to do a number of blocks with divisor 5, because this would confound the main effect of a factor with blocks and would thus generate an error.

For any primes apart from 2 or 3, only one at a time can be handled automatically. For example, if a design has three 5-level factors, it can be automatically subdivided into 5 blocks by the option blocks=5. It is also possible to run the design in 25 blocks; however, as 25=5*5, this cannot be done automatically but has to be requested by specifying the block.gen option in addition to the blocks option (in this case, block.gen=rbind(c(1,0,1),c(1,1,0)) would do the job).


fac.design returns a data frame of S3 class design with attributes attached.

The experimental factors are all stored as R factors.
For factors with 2 levels, contr.FrF2 contrasts (-1 / +1) are used.
For factors with more than 2 numerical levels, polynomial contrasts are used (i.e. analyses will per default use orthogonal polynomials).
For factors with more than 2 categorical levels, the default contrasts are used.

For changing the contrasts, use function change.contr.

The design.info attribute of the data frame has the following elements:


character string “full factorial” or “full factorial.blocked”


number of runs (replications are not counted)


number of factors


vector with number of levels for each factor


list named with (treatment) factor names and containing as entries vectors with coded factor levels


for designs of type full factorial.blocked only;
number of blocks


for designs of type full factorial.blocked only;
matrix the rows of which are the coefficients of the linear combinations that create block columns from of pseudo factors


for designs of type full factorial.blocked only;
size of each block (without consideration of wbreps)


option setting in call to FrF2


option setting in call to FrF2


for designs of type FrF2.blocked only; number of between block replications


for designs of type FrF2.blocked only; number of within block replications;
repeat.only indicates whether these are replications or repetitions only


option setting in call to FrF2


option setting in call to FrF2


call to function FrF2 (or stored menu settings, if the function has been called via the R commander plugin RcmdrPlugin.DoE)


Since R version 3.6.0, the behavior of function sample has changed (correction of a biased previous behavior that should not be relevant for the randomization of designs). For reproducing a randomized design that was produced with an earlier R version, please follow the steps described with the argument seed.


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


Ulrike Groemping


Collings, B.J. (1984). Generating the intrablock and interblock subgroups for confounding in general factorial experiments. Annals of Statistics 12, 1500–1509.

Collings, B.J. (1989). Quick confounding. Technometrics 31, 107–110.

See Also

See also FrF2, oa.design, pb, conf.set, block.catlg


  ## only specify level combination 
  ## design requested via factor.names
  fac.design(factor.names=list(one=c("a","b","c"), two=c(125,275), 
     three=c("old","new"), four=c(-1,1), five=c("min","medium","max")))
  ## design requested via character factor.names and nlevels 
  ##    (with a little German lesson for one two three)
  ### blocking designs
  fac.design(nlevels=c(2,2,3,3,6), blocks=6, seed=12345)
  ## the same design, now unnecessarily constructed via option block.gen
  ## preparation: look at the numbers of levels of pseudo factors
  ## (in this order)
  ## or, for more annotation, factorize the unblocked design
  ## positions 1 2 5 are 2-level pseudo factors
  ## positions 3 4 6 are 4-level pseudo factors
  ## blocking with highest possible interactions
  G <- rbind(two=c(1,1,0,0,1,0),three=c(0,0,1,1,0,1))
  plan.6blocks <- fac.design(nlevels=c(2,2,3,3,6), blocks=6, block.gen=G, seed=12345)
  ## two blocks, default design, but unnecessarily constructed via block.gen
  fac.design(nlevels=c(2,2,3,3,6), blocks=2, block.gen=c(1,1,0,0,1,0), seed=12345)
  ## three blocks, default design, but unnecessarily constructed via block.gen
  fac.design(nlevels=c(2,2,3,3,6), blocks=3, block.gen=c(0,0,1,1,0,1), seed=12345)
  ## nine blocks
  ## confounding two-factor interactions cannot be avoided
  ## there are warnings to that effect
  G <- rbind(CD=c(0,0,1,1,0,0),CE2=c(0,0,1,0,0,1))
  plan.9blocks <- fac.design(nlevels=c(2,2,3,3,6), blocks=9, block.gen=G, seed=12345)

  ## further automatic designs, not run for shortening run time 
  ## Not run: 
  fac.design(nlevels=c(2,2,3,3,6), blocks=4, seed=12345)
  fac.design(nlevels=c(2,2,3,3,6), blocks=9, seed=12345)
  fac.design(nlevels=c(2,2,3,3,6), blocks=36, seed=12345)
  fac.design(nlevels=c(3,5,6,10), blocks=15, seed=12345)
## End(Not run)
  ## independently check aliasing
  ## model with block main effects and all two-factor interactions
  ## 6 factors: not aliased
  ## 9 factors: aliased

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