Generates values for treatment factors using the design key method (R.W. Payne).

### Options

`PRINT` = string token |
Allows the generated `TREATMENTFACTOR` values to be printed, tabulated by the `BLOCKFACTORS` (`design` ); default `*` i.e. no printing |
---|---|

`BLOCKFACTORS` = factors |
Defines the block factors for the design; default is to take those in the formula already specified by the `BLOCKSTRUCTURE` directive, in the order in which they occur there |

`KEY` = matrix |
Matrix (number of treatment factors × number of block factors) key for the design |

`BASEVECTOR` = variate |
Base vector (length = number of treatment factors) for the design; default is a variate of zeros |

`ROWPRIMES` = variate |
Prime numbers for the rows of the `KEY` matrix |

`COLPRIMES` = variate |
Prime numbers for the columns of the `KEY` matrix |

`ROWMAPPINGS` = variate |
Mappings from the rows of the `KEY` to the `TREATMENTFACTORS` |

`COLMAPPINGS` = variate |
Mappings from the columns of the `KEY` to the `BLOCKFACTORS` |

### Parameter

`TREATMENTFACTORS` = factors |
Defines the treatment factors for the design; default is to take those in the formula already specified by the `TREATMENTSTRUCTURE` directive, in the order in which they occur there |
---|

### Description

`AKEY`

generates the values of the block factors, if necessary, in systematic order and then generates the treatment factors from the block factors using a design key. It then allows you to print the design.

The design key method, described by Patterson (1976) and Patterson & Bailey (1978), provides a very flexible way of specifying the allocation of treatments in an experimental design. The method assumes that the units are identified by a set of what are termed “plot” factors. Generally these will be the same factors that are used in the block formula. Thus, in the procedure, they are specified by an option called `BLOCKFACTORS`

which will take the factors from the formula already set by the `BLOCKSTRUCTURE`

directive (outside the procedure) as its default. However, if any of these factors has a non-prime number of levels, it may need to be specified instead as the combination of two or more (pseudo) factors: for example, in a block design with blocks of size eight, the plots might need to be indexed by three factors with two levels (see Example 4). The method can also be used to set up pseudo-factors for use in the treatment formula, and then the “plot” factors may be the treatment factors themselves (Example 3). If these “plot” factors do not already have values, they will be generated in “standard order” using the `GENERATE`

directive.

The factors whose values are to be generated are specified by the `TREATMENTFACTORS`

parameter. Again this can be omitted, and `AKEY`

will take the factors from the existing setting of the `TREATMENTSTRUCTURE`

directive, in the order in which they occur there.

The generated values of the factors can be printed by setting option `PRINT=design`

. The other options define how the values are generated. The `KEY`

option specifies a matrix known as the design key, which indicates how the values of each treatment factor are to be calculated from the plot factors. The matrix has a row for each treatment factor and a column for each plot factor; below *K _{ij}* represents the element in row

*i*and column

*j*. (This is the transpose of the form used by Patterson 1976, but in Genstat it seems more convenient to specify the treatments by rows.) There is also an option called

`BASEVECTOR`

, which can specify a variate with an element *B*for each treatment factor to allow the levels of the factor to be shifted cyclically; by default this is a variate of zeros.

_{i}The calculation assumes that the values of the plot factors are represented by the integers zero upwards (and `AKEY`

will perform this mapping automatically if necessary). The value *q*[*i*]_{u} in unit *u* of treatment factor *i* is then given by

*q*[*i*]_{u} = *b _{i}* +

*k*

_{i}_{1}×

*p*[1]

*+*

_{u}*k*

_{i}_{2}×

*p*[2]

*+ … +*

_{u}*k*×

_{in}*p*[

*n*]

_{u}modulo

*t*

_{i}where *p*[1]* _{u}* …

*p*[

*n*]

_{u}are the values of the plot factors in unit

*u*, and

*t*is the number of levels of treatment factor

_{i}*i*. The calculated values are integers in the range 0, 1 …

*t*-1, but

_{i}`AKEY`

will again map these to the defined levels if necessary. However, all this takes place behind the scenes, within `AKEY`

. The numbers of levels *t*must be prime numbers. They need not all be equal, but the key will usually be zero in any element where the row and column factors have different numbers of levels: that is, each treatment factor will usually be generated only from “plot” factors with the same number of levels as the treatment factor itself.

_{i}To illustrate the process, the treatments to be allocated (before randomization) to the plots of an *N* × *N* Latin Square may be calculated as

Latin-factor-value = Row-factor-value + Column-factor-valuemodulo *N*

The values of the extra factor in a Graeco-Latin square can then be formed as

Graeco-factor-value = Row-factor-value + 2 × Column-factor-valuemodulo *N*

The design key thus has rows (1,1) and (1,2); as shown in Example 1, this generates the following 5 × 5 Graeco-Latin square.

` Column 0 1 2 3 4`

` Row`

` 0 0 0 1 2 2 4 3 1 4 3`

` 1 1 1 2 3 3 0 4 2 0 4`

` 2 2 2 3 4 4 1 0 3 1 0`

` 3 3 3 4 0 0 2 1 4 2 1`

` 4 4 4 0 1 1 3 2 0 3 2`

If any of the block or treatment factors has a non-prime number of levels, it must be specified as the combination of two or more (pseudo) factors: for example, in a block design with blocks of size eight, the plots would need to be specified by three factors with two levels (see Example 4). Thus the `COLPRIMES`

option lets you supply a variate listing the prime numbers for each column of the key, and the `COLMAPPINGS`

option then a variate to indicate the “plot” factor corresponding to each column. So, in Example 4, where we have

` AKEY [BLOCKFACTORS=Block,Plot; KEY=HRkey;\`

` COLPRIME=!(4(2)); COLMAP=!(1,2,2,2)]`

`COLPRIME`

specifies that the prime for each column is 2, `COLMAP`

specifies that the first column corresponds to the first “plot” factor (`Block`

in the example) and that columns 2-4 correspond to the second “plot” factor (`Plot`

in the example). The default for `COLMAP`

is a variate containing the integers 1 up to the number of “plot” factors, so it can be omitted if no pseudo-factors are required. If `COLPRIME`

is omitted, the primes for the columns are provided by the numbers of levels of the “plot” factors, as already explained. Options `ROWPRIME`

and `ROWMAP`

similarly allow you to specify pseudo-factors to generate the treatment factors.

The design key thus provides a very convenient way of defining treatment factors. Patterson & Bailey (1978) show a range of examples of keys, which are used to form the worked examples below. Essentially, the key identifies each factor i with the set of contrasts (in the usual terminology)

`P[1]**K`

_{i1} P[2]**K_{i2} ... P[n]**K_{in}

and the skill when forming a design is in selecting the best set for each factor. The Genstat design system has a repertoire of keys, and these are used by procedures `DESIGN`

and `AGDESIGN`

to generate a range of designs, including factorials, fractional factorials, Latin squares and Lattices.

Options: `PRINT`

, `BLOCKFACTORS`

, `KEY`

, `BASEVECTOR`

, `ROWPRIMES`

, `COLPRIMES`

, `ROWMAPPINGS`

, `COLMAPPINGS`

.

Parameter: `TREATMENTFACTORS`

.

### Method

The `FCLASSIFICATION`

and `FORMULA`

directives are used, if necessary, to form lists of factors from the block or treatment formulae. The factor levels are then generated using the standard Genstat facilities for calculations and manipulation.

### Action with `RESTRICT`

If any of the factors is restricted, only the part of the design not excluded by the restriction will be generated.

### References

Patterson, H.D. (1976). Generation of factorial designs. *Journal of the Royal Statistical Society Series B*, 38, 175-179.

Patterson, H.D. & Bailey, R.A. (1978). Design keys for factorial experiments. *Applied Statistics*, 27, 335-343.

### See also

Directives: `AFMINABERRATION`

, `GENERATE`

, `FKEY`

, `FPSEUDOFACTORS`

.

Commands for: Design of experiments, Analysis of variance.

### Example

CAPTION 'AKEY example',\ 'Data from Patterson & Bailey (Applied Statistics 1978).',\ 'Example 1: a Graeco-Latin square.'; STYLE=meta,plain,plain FACTOR [NVALUES=25; LEVELS=!(0...4)] Row,Column,A,B; DECIMALS=0 GENERATE Row,Column " specify key matrix (row and column labelling is unnecessary other than to indicate how the matrix is stored) " MATRIX [ROWS=!t(A,B); COLUMNS=!t(Row,Column); VALUES=1,1, 1,2] GLkey AKEY [PRINT=design; BLOCKFACTORS=Row,Column; KEY=GLkey] A,B DELETE [REDEFINE=yes] Row,Column,A,B,GLkey CAPTION 'Example 2: a single-replicate block design.' " block (pseudo) factors and treatment factors " FACTOR [NVALUES=16; LEVELS=2] X1,X2,Y1,Y2,A,B,C,D & [LEVELS=4] Block,Plot GENERATE X1,X2,Y1,Y2 GENERATE Block,Plot BLOCKS Block/Plot TREATMENTS A*B*C*D MATRIX [ROWS=4; COLUMNS=4; VALUES=0,0,1,0, 0,0,0,1, 1,0,1,1, 0,1,1,1] Bkey AKEY [BLOCKFACTORS=X1,X2,Y1,Y2; KEY=Bkey] A,B,C,D ANOVA [FACTORIAL=4] PDESIGN DELETE [REDEFINE=yes] Block,Plot,X1,X2,Y1,Y2,A,B,C,D,Bkey CAPTION 'Example 3: a design with crossing and nesting.' FACTOR [NVALUES=27; LEVELS=3] Row,Column,Subplot,A,B,C GENERATE Row,Column,Subplot BLOCKS (Row*Column)/Subplot MATRIX [ROWS=3; COLUMNS=3; VALUES=0,0,1, 1,1,1, 1,2,1] CNkey " BLOCKFACTORS option not set as block factors can be obtained from the previous BLOCKS statement " AKEY [KEY=CNkey] A,B,C " the design key method can also be used to form pseudo (treatment) factors: below AKEY generates the pseudo factors required by ANOVA for the interactions to be balanced " FACTOR [LEVELS=3] AB2,AC2,BC2,ABC MATRIX [ROWS=4; COLUMNS=3; VALUES=1,2,0, 1,0,2, 0,1,2, 1,1,1] PFkey AKEY [BLOCK=A,B,C; KEY=PFkey] AB2,AC2,BC2,ABC TREATMENTS A + B + C + A.B//AB2 + A.C//AC2 + B.C//BC2 + A.B.C//ABC ANOVA PDESIGN [BLOCKS=Row,Subplot,Column; TREATMENTS=A,B,C] DELETE [REDEFINE=yes] Row,Column,Subplot,A,B,C,AB2,AC2,BC2,ABC,CNkey,PFkey CAPTION 'Example 4: a half-replicate design.' " block (pseudo) factors and treatment factors " FACTOR [NVALUES=16; LEVELS=2] Block,A,B,C,D,E & [LEVELS=8] Plot BLOCKS Block/Plot TREATMENTS A*B*C*D*E MATRIX [ROWS=5; COLUMNS=4;\ VALUES=0,1,0,0, 0,0,1,0, 0,0,0,1, 1,1,1,0, 0,1,1,1] HRkey " TREATMENTS parameter not set as the treatment factors can be obtained from the TREATMENTS formula above " AKEY [BLOCKFACTORS=Block,Plot; KEY=HRkey;\ COLPRIME=!(4(2)); COLMAP=!(1,2,2,2)] ANOVA [FACTORIAL=1] PDESIGN [BLOCKS=Plot,Block] DELETE [REDEFINE=yes] Block,Plot,A,B,C,D,E,HRkey CAPTION 'Example 5: a quarter-replicate design.' " block (pseudo) factors and treatment factors " FACTOR [NVALUES=16; LEVELS=2] U,W,B1,B2,C,D,E1,E2 & [LEVELS=4] V,B,E MATRIX [ROWS=6; COLUMNS=4;\ " W V2 W U V1V2 W V1 U V1 W V1 V2 W "\ VALUES=0,0,0,1, 0,0,1,1, 1,1,1,1, 0,1,0,0, 1,1,0,1, 0,1,1,1] QRkey " generate treament factors " AKEY [BLOCKFACTORS=U,V,W; KEY=QRkey;\ ROWPRIMES=!(6(2)); ROWMAPPINGS=!(1,1,2,3,4,4);\ COLPRIMES=!(4(2)); COLMAPPINGS=!(1,2,2,3)] B,C,D,E " and treatment pseudo-factors " AKEY [BLOCKFACTORS=U,V,W; KEY=QRkey;\ COLPRIMES=!(4(2)); COLMAPPINGS=!(1,2,2,3)] B1,B2,C,D,E1,E2 BLOCKS U/V/W TREATMENTS B//(B1+B2)*C*D*E//(E1+E2) ANOVA [FACTORIAL=1] PDESIGN [TREATMENTS=B*C*D*E] DELETE [REDEFINE=yes] U,V,W,B,B1,B2,C,D,E,E1,E2,QRkey CAPTION 'Example 6: a multiple replicate design.' " block (pseudo) factors and treatment factors " FACTOR [NVALUES=32; LEVELS=2] W,A,B,C,D & [LEVELS=4] U,V GENERATE U,V,W BLOCKS U*(V/W) TREATMENTS A*B*C*D MATRIX [ROWS=4; COLUMNS=5;\ VALUES=1,0,0,0,1, 0,0,1,0,1, 0,0,0,1,1, 0,0,1,1,1] MRkey AKEY [BLOCKFACTORS=U,V,W; KEY=MRkey;\ COLPRIMES=!(5(2)); COLMAPPINGS=!(1,1,2,2,3)] ] ANOVA [FACTORIAL=4] PDESIGN DELETE [REDEFINE=yes] U,V,W,A,B,C,D,MRkey