planor.designkey: Search for a Design Key or a Collection of Design Keys
In planor: Generation of Regular Factorial Designs

Description Usage Arguments Details Value Note Author(s) See Also Examples

Search for a design key or a collection of design keys that satisfy the design properties specified by the arguments. This function implements the core algorithms of the planor package.

1
2
3

planor.designkey(factors, nlevels, block, ordered, hierarchy, model,
    estimate, listofmodels, resolution, nunits, base, max.sol=1,
    randomsearch=FALSE, verbose=TRUE)

`factors`	an object of class `designfactors`, typically an output from `planor.factors`. Alternatively, you can use the arguments `factors`, `nlevels`, `ordered`, `hierarchy` as described in the syntax of `planor.factors`.
`nlevels`	see `planor.factors`. Ignored if `factors` is of class `designfactors`.
`block`	see `planor.factors`. Ignored if `factors` is of class `designfactors`.
`ordered`	see `planor.factors`. Ignored if `factors` is of class `designfactors`.
`hierarchy`	see `planor.factors`. Ignored if `factors` is of class `designfactors`.
`model`	a list of model-estimate pairs of formulae, typically an output from `planor.model`. Alternatively, you can use the arguments `model`, `estimate`, `listofmodels` and `resolution`, as described in the syntax of `planor.model`.
`estimate`	see `planor.model`. Ignored if `model` is a list.
`listofmodels`	see `planor.model`. Ignored if `model` is a list.
`resolution`	see `planor.model`. Ignored if `model` is a list. When set and there is no hierarchy, a faster algorithm is used which exploits the symmetries.
`nunits`	a scalar giving the total number of units in the design
`base`	an optional additive formula to specify the basic factors. See Note.
`max.sol`	maximum number of solutions before exit.
`randomsearch`	a `logical`. If TRUE, the searches for a key matrix are performed in a random order.
`verbose`	a `logical` to set to `TRUE` for verbose display.

The methods implemented in planor rely on a decomposition of the design search according to prime numbers. The prime numbers involved are those that decompose the numbers of levels of the factors. For example, if all factors have 2, 4, or 8 levels, then the number of units must be a power of 2 and the only prime number involved is 2. This is called the symmetric case. But if at least one factor has 6 levels, or if factor A has 2 levels and factor B has 3 levels, then the number of units must be the product of a power of 2 by a power of 3. In this case the search is automatically decomposed into one for prime 2 and one for prime 3. This is called the asymmetric case.

In the symmetric case with prime p, a regular factorial design requires a single key matrix of integers modulo p. In the asymmetric case, it requires one key matrix per prime. In planor, key matrices are stored in objects of class keymatrix. The lists made of one key matrix per prime are called design keys. They are stored in objects of class designkey.

The function planor.designkey essentially searches for design keys that satisfy the user specifications. For technical reasons, however, its output can take two different forms: either an object of class listofkeyrings or an object of class listofdesignkeys. The function planor.designkey detects automatically which case applies. In the first case (independent case), the key matrix solutions can be searched independently between primes and they are stored in objects of class listofkeyrings. The second case (recursive case) occurs exceptionnally. In that case the search cannot be independent between primes and so the different solutions are directly stored in a list of class listofdesignkeys.

An object of class listofkeyrings in most cases. Otherwise, i.e in recursive cases, an object of class listofdesignkeys.

The nunits argument is compulsory except if the base argument is used. When both arguments are missing, the program stops and it gives the size that would be required by a full factorial design. When only nunits is missing, the number of units is given by the product of the numbers of levels of the base factors.

The base formula must be an additive formula involving a subset of factors, called the basic factors. Using the base argument ensures that the design solutions will include the full factorial design for the basic factors. This option can speed up the search because it restricts the domain to be explored by the search algorithm.

Monod, H. and Bouvier, A.

planor.factors, planor.model, and the classes designfactors, listofkeyrings, listofdesignkeys

K0 <- planor.designkey(factors=c("block", LETTERS[1:4]),
  nlevels=rep(3,5), model=~block+(A+B+C+D)^2, estimate=~A+B+C+D,
  nunits=3^3, base=~A+B+C, max.sol=2)
### With automatic model generation
Km <- planor.designkey(factors=c("block", LETTERS[1:4]),
  nlevels=rep(2,5), resolution=3, nunits=2^4)

Loaded planor 1.4.1

Preliminary step 1 : processing the model specifications
Preliminary step 2 : performing prime decompositions on the factors
*** Main step for prime p = 3 : key-matrix search
  => search for columns 4 to 5 
      first visit to column 4
      first visit to column 5
    ---    col. 5 ( j = 2) 8 selected candidates
The search is closed: max.sol = 2 solution(s) found 
Preliminary step 1 : processing the model specifications
Preliminary step 2 : performing prime decompositions on the factors
*** Main step for prime p = 2 : key-matrix search
  => search for columns 2 to 5 
      first visit to column 2
    ---    col. 2 ( j = 1) 14 initial candidates
      first visit to column 3
    ---    col. 3 ( j = 2) 14 initial candidates
    ---    col. 3 ( j = 2) 13 selected candidates
      first visit to column 4
    ---    col. 4 ( j = 3) 13 initial candidates
    ---    col. 4 ( j = 3) 12 selected candidates
      first visit to column 5
    ---    col. 5 ( j = 4) 12 initial candidates
    ---    col. 5 ( j = 4) 11 selected candidates
The search is closed: max.sol = 1 solution(s) found