planor.designkey: Search for a Design Key or a Collection of Design Keys

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

View source: R/planor.R

Description

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.

Usage

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

Arguments

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.

Details

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.

Value

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

Note

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.

Author(s)

Monod, H. and Bouvier, A.

See Also

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

Examples

1
2
3
4
5
6
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)

Example output

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 

planor documentation built on March 19, 2020, 1:06 a.m.