1. Home
  2. AKEY procedure

AKEY procedure

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


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


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


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


            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


        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.




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.


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


Commands for: Design of experiments, Analysis of variance.


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 "
&          [LEVELS=4] Block,Plot
GENERATE   Block,Plot
BLOCKS     Block/Plot
MATRIX     [ROWS=4; COLUMNS=4; VALUES=0,0,1,0, 0,0,0,1, 1,0,1,1, 0,1,1,1] Bkey
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 "
MATRIX     [ROWS=4; COLUMNS=3; VALUES=1,2,0, 1,0,2, 0,1,2, 1,1,1] PFkey
TREATMENTS A + B + C + A.B//AB2 + A.C//AC2 + B.C//BC2 + A.B.C//ABC
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 "
&          [LEVELS=8] Plot
BLOCKS     Block/Plot
           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)]
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 "
&          [LEVELS=4] V,B,E
 "                      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 "
           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 "
           COLPRIMES=!(4(2)); COLMAPPINGS=!(1,2,2,3)] B1,B2,C,D,E1,E2
TREATMENTS B//(B1+B2)*C*D*E//(E1+E2)
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 "
&          [LEVELS=4] U,V
BLOCKS     U*(V/W)
           VALUES=1,0,0,0,1, 0,0,1,0,1, 0,0,0,1,1, 0,0,1,1,1] MRkey
           COLPRIMES=!(5(2)); COLMAPPINGS=!(1,1,2,2,3)] ]
Updated on March 11, 2019

Was this article helpful?