1. Home
2. FKEY directive

# FKEY directive

Forms design keys for multi-stratum experimental designs, allowing for confounded and aliased treatments.

### Options

`BASICFACTORS` = factors Factors indexing the units of the design Factors to be allocated to the units of the design Stores the design key (`ADDEDFACTORS` × `BASICFACTORS`) Can be used to input existing allocations for some of the added factors Can be used to specify that some of the factors must be constant within each combination of levels of other factors; the matrix has a row for each added factor and columns first for the basic factors and then for the added factors, ones in the entries where the row factor must be constant within the combinations of the column factors, zero elsewhere Can provide a seed to generate a random permutation of the sets of basic effects that may be allocated to each added factor, thus producing design randomly selected from all those that might be possible; default `*` i.e. no permutation Prime numbers for the rows of the `KEY` matrix Prime numbers for the columns of the `KEY` matrix Mappings from the rows of the `KEY` to the `TREATMENTFACTORS` Mappings from the columns of the `KEY` to the `BLOCKFACTORS` Structure to save all the information about the formation of the design; this can then be input later to give a different design (if possible) with the same properties

### Parameters

`REQUIRED` = formula structures Formulae each defining a list of terms that are to be estimated in the analysis Formulae each specifying terms that cannot be ignored in the context of the corresponding `REQUIRED` formula

### Description

Design keys can be used in the `GENERATE` directive to generate values of treatment factors from block factors. They also provide the basis of the representation used to store the repertoire of designs obtainable from procedure `AGDESIGN` (see Payne and Franklin 1994). This covers a range of standard situations, but cannot allow for every eventuality. `FKEY` allows you to form keys for other circumstances and, if these are likely to occur frequently, you can extend or replace the standard repertoire using procedure `FDESIGNFILE`.

The assumption in `FKEY` is that the units of the design are indexed by a set of factors known as the basic factors. The key allows the values of another set of factors, known here as the added factors, to be calculated from the basic factors. These factors are listed using the `BASICFACTORS` and `ADDEDFACTORS` options. They must all have been declared previously as factors, and their numbers of levels must have been defined. Usually the basic factors are the factors that will be used to define the block formula of the design (for example, blocks, plots, rows, columns, subplots and so on) and the added factors are the treatment factors, but in partial replicates, for example, the basic factors may be the treatment factors and the added factors the block factors.

If the basic and added factors all have prime numbers of levels the key is saved, by the `KEY` option, as a matrix with a row for each added factor and a column for each basic factor. However, if the levels are not all prime, `FKEY` will break up factors that do not have prime numbers of levels into “pseudo-factors”. Thus, a factor with six levels will be represented by the combinations of levels of two pseudo-factors, one with two levels and one with three levels. When pseudo-factors are required for the added factors, the `ROWPRIMES` option can be used to save a variate storing the (prime) number of levels corresponding to each row of the key, and the `ROWMAPPINGS` option can save a variate with an element for each row containing the number of the corresponding added factor. So, if we had two added factors, one with five and one with six levels, the `ROWPRIMES` variate might contain the values 5, 2 and 3, and the `ROWMAPPINGS` variate the values 1, 2 and 2. The second added factor (with six levels) would then be represented by two pseudo-factors, corresponding to the second and third rows of the key. The `COLPRIMES` and `COLMAPPINGS` options can similarly save details of the pseudo-factors required for basic factors with non-prime numbers of levels. The variates saved by `ROWPRIMES`, `COLPRIMES`, `ROWMAPPINGS` and `COLMAPINGS` can be used in the `AKEY` procedure, together with the key, to form the added factors automatically without the need to worry about the pseudo-factoring.

The main properties of the design are derived from the `REQUIRED` and `NONNEGLIGIBLE` parameters. Suppose we have a block design containing three blocks of nine plots. The experiment is to have three treatment factors, `A`, `B` and `C`, and these will be the added factors. The design has a block structure of plots nested within blocks

`Blocks/Plots`

In the analysis we wish to be able to estimate all main effects and interactions of the factors `A`, `B` and `C`, except the three-factor interaction `A.B.C`; these terms are specified by the formula structure supplied using the `REQUIRED` parameter. The `NONNEGLIGIBLE` parameter specifies model terms that cannot be ignored in the analysis: that is, the model terms with which these required terms cannot be confounded. Here we have the main effect `Blocks` and all main effects and interactions of the factors `A`, `B` and `C`. To form the design key `K`, we thus need to put

`FACTOR [NVALUES=27; LEVELS=3] Block,A,B,C`

`& [LEVELS=9] Plot`

`FKEY [BASIC=Block,Plot; ADDED=A,B,C; KEY=K;\`

`  COLPRIMES=Bplev; COLMAPPINGS=Bmap]\`

`  REQUIRED=!f(A*B*C-A.B.C); NONNEGLIGIBLE=!f(Block+A*B*C)`

If the design has more than two strata suitable for the estimation of treatment effects, the `REQUIRED` and `NONNEGLIGIBLE` parameters can specify lists of formulae, in parallel, one pair of formulae for each stratum. Each `REQUIRED` formula specifies the terms that must be estimated in one of the strata (or in a stratum below it), and the corresponding `NONNEGLIGIBLE` formula specifies the terms that cannot be ignored there. Suppose we put

`FACTOR [NVALUES=81; LEVELS=3] Block,Wplot,A,B,C,D,E`

`& [LEVELS=9] Subplot`

`FKEY [BASIC=Block,Wplot,Subplot; ADDED=A,B,C,D,E; KEY=K;\`

`  COLPRIMES=Bplev; COLMAPPINGS=Bmap]\`

`  REQUIRED=!f((A+B+C)*(A+B+C)),!f((A+B+C+D+E)*(A+B+C+D+E));\`

`  NONNEGLIGIBLE=!f(Block+Block.Wplot),!f(Block)`

Here we have a block formula

`Block / Wplot / Subplot1`

which produces three strata

`Block + Block.Wplot + Block.Wplot.Subplot`

The first formula in the `REQUITRED` list `!f((A+B+C)*(A+B+C))`, in parallel with the formula `!f(Block+Block.Wplot)` in the `NONNEGLIGIBLE` list, indicates that we do not want the main effects or two-factor interaction of factors `A`, `B` and `C` to be confounded with each other nor with `Block` or `Block.Wplot`; this ensures that they will be estimated in the `Block.Wplot.Subplot` stratum. The second pair of formulae, `!f((A+B+C+D+E) * (A+B+C+D+E))` and `!f(Block)`, indicate that we want to estimate the main effects and two-factor interactions of all the five treatment factors `A`, `B`, `C`, `D` and `E` in the Block.Wplot stratum or below; in effect this means that we are willing to have `D` and `E` and any of their interactions estimated in the `Block.Wplot` stratum.

The algorithm that `FKEY` uses to construct the key is based on the method developed by Franklin & Bailey (1977), Franklin (1985) and Kobilinsky (1995). Essentially this considers the possible orthogonal sets of contrasts amongst the main effects and interactions of the basic factors, and tries in turn to find a feasible set against which to confound each added factor. Often there are several feasible ways in which this can be done. To avoid `FKEY` selecting the same key every time, you can set the `SEED` option to an integer that will be used to generate a random permutation of the order in which the sets of basic contrasts are considered, thus producing design randomly selected from all those that might be possible; by default no permutation takes place. Alternatively, you can use the `SAVE` option to save all the information about the formation of the design; this can then be input later to provide the next possible key (if available) with the requested properties.

In a multi-stratum design, you may wish to insist that some factors are applied to complete units of one of the strata. This can be done using the `HIERARCHIES` option, which allows you to indicate that some of the added factors must be constant within each combination of levels of other factors. These constraints are specified, if required, by supplying a matrix with a row for each added factor and columns first for the basic factors and then for the added factors. The matrix contains ones in the entries where the row factor must be constant within the combinations of the column factors, and zeros elsewhere.

`FKEY` can also be used to extend an existing design, by allocating further factors to the units. The existing key should then be input using the `INKEY` option, with zeros in the rows for the new added factors.

`FKEY` can form keys for small designs fairly quickly, but for complicated arrangements you may find that it takes some time to check the various possibilities.

Options: `BASICFACTORS`, `ADDEDFACTORS`, `KEY`, `INKEY`, `HIERARCHIES`, `SEED`, `ROWPRIMES`, `COLPRIMES`, `ROWMAPPINGS`, `COLMAPPINGS`, `SAVE`.

Parameters: `REQUIRED`, `NONNEGLIGIBLE`.

Franklin, M.F. (1985). Selecting defining contrasts and and confounded effects in pn-m factorial experiments. Technometrics, 27, 165-172.

Franklin, M.F. & Bailey, R.A. (1977). Selection of defining contrasts and confounded effects in two-level experiments. Applied Statistics, 26, 321-326.

Kobilinsky, A. (1995). PLANOR: Programme de Génération Automatique de Plans d’Expériences Réguliers. INRA, Versailles.

Payne, R.W. & Franklin, M.F. (1994). Data structures and algorithms for an open system to design and analyse generally balanced designs. In: COMPSTAT 94 Proceedings in Computational Statistics (ed. R. Dutter & W. Grossmann), pp. 429-434. Physica-Verlag, Hiedelberg.

Directives: `AFMINABERRATION`, `GENERATE`, `FPSEUDOFACTORS`.

Procedures: `AKEY`, `ARANDOMIZE`, `ASAMPLESIZE`, `FACPRODUCT`, `FBASICCONTRASTS`.

Commands for: Design of experiments, Analysis of variance.

### Example

```" Examples 2:4.13.5a-c "
" Augmented design based on a 4x4 Latin square,
as in Lin & Poushinsky (1983, Biometrics)."
AGLATIN     [PRINT=*; ANALYSE=no] NROWS=4; NSQUARES=1; SEED=584578;\
TREATMENTFACTORS=!p(Genotype); ROWS=Row; COLUMNS=Column
AFAUGMENTED [PRINT=design; BLOCKSTRUCTURE=Row*Column;\
LEVTEST=!(5...132); LEVCONTROL=5; GENOTYPES=Genotype;\
NSUBPLOTS=9; SUBCONTROL=5; TESTVSCONTROL=TvsC; CONTROLS=Control
PRINT       TvsC,Genotype,Control,Row,Column
" Augmented design based on a balanced-incomplete-block design to
show how to form a design with more than one control per whole-plot."
FACTOR      [LEVELS=3; VALUES=1,1,2,2,3,3] Blocks
FACTOR      [LEVELS=3; VALUES=1,3,2,3,1,2] Genotypes
AFAUGMENTED [PRINT=design; BLOCKSTRUCTURE=Blocks; LEVTEST=!(101...118);\
GENOTYPES=Genotypes; NSUBPLOTS=8; SUBCONTROL=!(3,6)
" Augmented design with a null basic design, to show how
to form a design with systematic repeating controls."
" design with systematic repeating controls "
FACTOR      [LEVELS=32; VALUES=2,6...30] plots
FACTOR      [LEVELS=2; VALUES=(1,2)4] genotypes
AFAUGMENTED [SUBPLOTS=plots; LEVTEST=!(3...26);\
GENOTYPES=genotypes; CONTROLS=controls
PRINT       plots,genotypes,controls
```