planor.designkey {planor} | R Documentation

## Search for a Design Key or a Collection of Design Keys

### 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

    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

    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)

[Package planor version 1.5-1 Index]