1. Home
2. AKEY procedure

# AKEY procedure

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 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 Matrix (number of treatment factors × number of block factors) key for the design Base vector (length = number of treatment factors) for the design; default is a variate of zeros 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

### 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 Kij 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 Bi for each treatment factor to allow the levels of the factor to be shifted cyclically; by default this is a variate of zeros.

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 = bi + ki1 × p[1]u + ki2 × p[2]u + … + kin × p[n]umodulo ti

where p[1]up[n]u are the values of the plot factors in unit u, and ti is the number of levels of treatment factor i. The calculated values are integers in the range 0, 1 … ti-1, but 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 ti 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.

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 allows you to 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]**Ki1 P[2]**Ki2 ... P[n]**Kin

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.

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
Updated on June 20, 2019