help ralloc

Title

ralloc - Allocation of treatments in controlled trials using random permuted blocks

Syntax

ralloc varname1 varname2 varname3 , saving(filename1) [options]

ralloc ?

where:

varname1 is the variable that will store the block identifier.

varname2 is the variable that will store the block size.

varname3 is the variable that will store treatment allocation.

filename1 is the filename (or stub of names of multiple files) that will store the randomised allocations.

Common options
idvar(varname) specifies variable to store unique study identifier

seed(#|date) sets seed for the random number generator

nsubj(#) specifies number of allocations in each stratum

ntreat(#) specifies number of treatments (1 to 10)

ratio(#) specifies allocation ratio (1:#) in 2 treatment trial. # is 1, 2, or 3

osize(#) specifies number of different block sizes (1 to 7)

init(#) specifies smallest block size to be used

[no]equal specifies whether or not the frequency of block sizes is the same

strata(#) specifies number of strata

[no]tables requests informative tables to be displayed

trtlab(label1 [label2]...) specifies value labels for at least one treatment

stratlab(label1 label2...) specifies value labels for each and every stratum
[when no using() file is specified]

[no]vallab requests value labels be attached to strata and be used as suffixes for allocation filenames

Special designs
factor(#1*#2) specifies a #1x#2 factorial trial where
#1, #2 = 2, 3 or 4

factor(#1*#2*#3) specifies a #1x#2x#3 factorial trial
where #1, #2, #3 = 2 or 3 but subject to #1 < #2 < #3

fratio(#1 #2) specifies allocation ratios in a 2x2 factorial trial where
#1, #2 = 1 or 2

xover(stand|switch|extra) specifies design of a 2x2 crossover trial

Saving file
[no]multif saves multiple files (one for each stratum) with filename1 as stub

shape(long|wide) specifies shape of filename1

File defining strata
using(filename2) names an existing .dta file holding desired stratum-specific allocation
counts

countv(varname) specifies name of the numeric variable in filename2 that stores desired number of
allocations in each stratum. countv may only be specified - and is not optional - if using is specified

Description

ralloc provides a sequence of treatments randomly permuted in blocks of
constant or varying size. If not constant, the size and order of the blocks
are also random. Allocation may be stratified by one or more variables.
In non-factorial designs, up to 10 treatments may be specified. Randomisation may also
proceed simultaneously on 2 factors: 2x2, 2x3, 3x2, 3x3, 2x4, 4x2, 3x4, 4x3 and 4x4 factorial
designs are supported, or on 3 factors: 2x2x2, 2x2x3, 2x3x3 and 3x3x3 designs are supported. ralloc
will also handle a 2x2 crossover design with or without a supplementary 3rd period as either
a "switchback" or "extra period" design (Jones and Kenward 1989).

A typical use of ralloc is in a randomised controlled clinical trial (RCT),
and, in particular, in a multicentred trial where balance in treatment
allocations may be desirable within centre and other defined strata.

The second syntax (ralloc ?) displays the syntax diagram for the first syntax.

Note that ralloc issues a clear command immediately after it is invoked, so existing data in memory
will be lost.

Options

Common options

idvar(varname) specifies the name of the unique subject identifier. This identifier is completely uninformative of any
subject characteristic.

seed(#|date) specifies the random number seed. If unspecified, the default is 1234567879. # should be an integer; if
it is not it will be truncated. Alternatively, the word date may be specified which invites ralloc to set the seed to today's
date (number of days elapsed since January 1, 1960).

nsubj(#) specifies the total number of subjects (>0) in each stratum requiring a random treatment allocation. If
unspecified, the default is 100. ralloc may yield a number greater than # if this is required to complete the final block in
any stratum. # is overridden if option using() is specified.

ntreat(#) specifies the number of treatment arms in a non-factorial design. # may be 2 to 10. ntreat()
should not be specified in a factorial design, as the number of treatment combinations is defined in the factor() option. If
unspecified, the default for a non-factorial design is 2.

ratio(#) specifies the ratio of treatment allocations to the arms of a 2 treatment non-factorial trial. # may
be 1, 2 or 3, yielding a 1:1, 1:2 or 1:3 ratio of allocations respectively. For a 3 or 4 arm non-factorial trial, only
ratio(1), the default, may be specified. However, one may allocate certain ratios by "tricking" ralloc by judicious
naming of treatments using the trtlab() option: see Examples 9 and 10 below.

osize(1|2|3|4|5|6|7) specifies how many different sizes of blocks will
be used. For example, if 3 treatment arms are chosen, then osize(5), the default, will yield possible block
sizes of 3, 6, 9, 12, and 15. Note that it is quite possible not to realise some block sizes if the number of subjects
requested by option nsubj() is low. osize(1) gives a constant block size.

init(#) specifies the initiating value of the sequence defining the block sizes. ralloc allows 5 schemas:

(1) non-factorial design with balanced allocation: In this case the default for init() is the number of
treatments given by ntreat(). This may also be specified by init(0). For example, in a 3 treatment trial,
init(9) would, if the default osize(5) were chosen, yield block sizes of 9, 12, 15, 18 and 21. If init()
were unspecified, the block sizes would be 3, 6, 9, 12 and 15.

(2) 2 treatment non-factorial design with unbalanced allocation: When a ratio > 1 has been specified for a 2
treatment trial, the default initiating value of the block size is (ratio + 1).

(3) factorial design with balanced allocation: When not specified, the default is the number of treatment
combinations, for example, 6 in a 2x3 design.

(4) 2x2 factorial design with unbalanced allocation: When fratio() is specified, the default initiating
block size is given by ((1st arg of fratio()) + 1) x ((2nd arg of fratio()) + 1).

(5) 2x2 crossover design with balanced allocation: See case (1) above.

In all cases, when specified, the argument for init() must be an integer multiple of the appropriate default.

[no]equal indicates whether or not block sizes will be allocated in equal proportions. In the example given
under the osize() option, each block would appear on roughly 20% of occasions. This may not be desirable: too many
small blocks may allow breaking the blind; too many large blocks may compromise balance of treatments in the event of
premature closure. The default (noequal) allocates treatments in proportion to elements of Pascal's triangle.
In the above example, if equal were not specified (or noequal were specified), allocation of block sizes would be
in the ratio of 1:4:6:4:1. That is, the relative frequency of small and large block sizes is down-weighted. See the
init() option for another way to limit the number of small blocks, albeit at the cost of increasing the number of
large blocks. If osize() is 1 or 2, then equality of distribution of block size(s) is forced.

strata(#) specifies the number of strata. The default is 1. The number of strata can be calculated as the product,
over all stratification variables, of the levels in each stratification variable. For example, if we had a trial running
in 10 centres and we further required balance over 2 sexes and 3 age groups, then strata(60) would be specified.
This option may be specified with or without the using() option (see below). If using() is not specified, each
stratum will hold the number of allocations specified by the nsubj() option. If using() is specified, the value
of strata() is overridden by the number of rows in filename2.

[no]tables specifies whether or not a frequency distribution of block sizes is displayed for all allocations
and, where appropriate, for each stratum. The default is notables.

trtlab(string1 [string2] ...) specifies value labels for treatments. At most 10 labels may be specified for a
non-factorial design. The number of labels that may be specified for a factorial design is equal to the sum of the
number of possible treatments in the two randomisation axes. For example, a 2x3 study will allow 5 labels. Labels
are separated by spaces and so may not themselves contain a space. A label will be truncated after the first 12
characters. The default treatment labels are A, B, C, D, E, F, G, H, I and J. An older form of the syntax for non-factorial
designs, requiring an option for each label, tr1lab(string), tr2lab(string), etc., is permitted but obsolete.
Note that treatment labels need not be unique: this may be exploited to allocate treatments in ratios other than those
permitted by ratio(). See Examples 9 and 10 below.

stratlab(string1 string2 ...) specifies value labels for the strata when a using() file is not specified.
Labels are separated by spaces and so may not themselves contain a space. The number of labels specified must equal
the number of strata specified in the strata() option.

[no]vallab specifies whether or not value labels will be used. The default is that they will not be used (novallab).
If vallab is specified then there are two situations to consider:

(i) a using file is not specified:

In this case, the value labels will have been explicitly specified in option stratlab. The labels will be attached to the
numeric stratum identifying variable, StratID, in the file of allocations. If, in addition, option multif is specified,
each label will form the suffix of the name of the file holding the treatment allocations for the respective stratum.

(i) a using file is specified:

In this case, the value labels must pre-exist for each stratum-defining variable in the using file, and will be attached to the
numeric stratum identifying variable, StratID, in the file of allocations. If, in addition, option multif is specified,
each label will form the suffix of the name of the file holding the treatment allocations for the respective stratum. Any spaces in
a value label being used as part of a filename will be replaced by underscore characters. The value labels of the stratum-defining
variables in the using file will also be attached to the same variables in the file of allocations.

Special designs

factor(string) specifies that the trial has a factorial design with two or three "axes of randomisation". string
must be one of: 2*2, 2*3, 3*2, 3*3, 2*4, 4*2, 3*4, 4*3, 4*4, 2*2*2, 2*2*3, 2*3*3 or 3*3*3. Allocation combinations are balanced
within blocks, unless fratio() is specified in a 2x2 design. The names of the treatment variables will be
varname31, varname32 and, if required for the 3-way design, varname33.

fratio(string) specifies, in the case of a 2x2 factorial design, the ratio of allocations in each axis.
The string must be one of: 1 1, 1 2, 2 1, or 2 2, that is, two digits separated by at least one space. For example,
if we require a 1:2 ratio of treatments in the first randomisation axis and a 1:1 ratio of treatments in the
second axis, fratio(2 1) would be specified.

xover(string) specifies the design as a 2x2 crossover. string may be one of stand for the standard
2 treatment, 2 period design, switch for the switchback design where each subject receives the treatment
assigned for period 1 in period 3, or extra, for the extra period design, where each subject has the treatment
assigned for period 2 replicated in period 3. The names of the treatment variables will be varname31,
varname32 and, if required, varname33.

Saving file

saving(filename1) specifies the name of the file to which data are saved. This is a required "option".
If more than one stratum is specified by either the strata() option or the using() option then, in addition to saving
all random allocations across all strata to filename1, allocations for each stratum may be saved to individual files (see
option multif). For these, filename1 is used as a stub to name one file for each stratum. There are then two cases to
consider:

(i) Stratum value labels not specified or Stratum value labels specified, but option vallab not specified:

The naming schema for stratum specific files is:

filename1_n1[_n2_n3 ... _nk]}

for a trial with 1 to k stratification variables. n1 identifies the level of the stratum of the 1st stratification variable,
n2 gives the level of the stratum of the 2nd stratification variable, etc., each stratification variable's set of suffixes being
preceded by an underscore character. Suffixes are padded with leading zeros to maintain alphanumeric sort order.

For example, if we specified saving(myfile) and multif and we had only one stratification variable
with 10 levels, the filenames would be: myfile.dta, myfile_01.dta, myfile_02.dta, ..., myfile_09.dta, and myfile_10.dta.

If there were a second stratification variable, with say, 3 levels, we would have myfile.dta plus 30 files named: myfile_01_1.dta,
myfile_01_2.dta, myfile_01_3.dta, myfile_02_1.dta, ....., myfile_10_3.dta.

(ii) Stratum value labels specified and option vallab also specified:

The naming schema for stratum specific files is:

filename1_valuelabel if no using file is specified and so labels are specified by option stratlab.

or

filename1_valuelabel1_valuelabel2 ...... if a using file is specified and so labels are derived from that file.

In the case where the value labels are defined directly in the stratlab option (that is, no using file is specified),
then, for example, if we specified saving(myfile) and multif and we had only 1 stratification variable
with 2 levels, and stratum labels specified as stratlab(Seattle_Grace Chicago_Hope) the names of the 3 files
holding allocations would be: myfile.dta, myfile_Seattle_Grace.dta, and myfile_Chicago_Hope.dta.

If there were a second stratification variable, also with, say, 2 levels, we might have specified:
stratlab(Seattle_Grace_Male Seattle_Grace_Female Chicago_Hope_Male Chicago_Hope_Female) and the 5 files produced
would be: myfile.dta, myfile_Seattle_Grace_Male.dta, myfile_Seattle_Grace_Female.dta, myfile_Chicago_Hope_Male.dta,
and myfile_Chicago_Hope_Female.dta.

Note that each value label string must contain information on all the relevant strata, in this case, the value labels each contain information on
both hospital and sex. Embedded spaces are not allowed.

In the case where the value labels are defined indirectly (that is, they are derived from the value labels of the using file), then there will
be separate value labels for each stratum-defining variable. For example, if the using file had two stratum defining variables, hospital and
sex, each of these variables will have a set of value labels. The suffix of the name of an allocation file will be a concatenation of the relevant
label from each set, with separating underscore characters. So, for the file saving allocations for females at Chicago Hope, the suffix will be
Chicago_Hope_Female, and we note that underscore characters have been substituted for the space within "Chicago Hope" and used to bind the
two value labels.

If a stratum-defining variable in the using file does not have a value label, or a value label exists but not for every level of the
stratum, then vallab will attach whatever value labels it can, and substitute the raw numeric value of the level for those that are not
available. (See Example 12 below).

[no]multif specifies that multiple files will be saved, one file holding all allocations, and a series of
files for each stratum's allocations. The default is nomultif meaning that just one file holding all allocations
will be generated.

shape(long|wide) allows specification of the output to filename1 (or to each of the files with prefix stub
filename1 if multif has been specified) in either long or wide form. In long form, the treatment listing is
sequential down page within the defined block. In wide form, the treatment listing is sequential across page within
the defined block. The default is long. A factorial or crossover design may not be specified as wide.

File defining strata

using(filename2) specifies a Stata .dta file defining the stratification schema. The file consists of numeric variables
defining strata plus one other numeric variable giving the number of subjects required to be randomised in each stratum
(the countv() variable, see below). If the stratum-defining variables have value labels then, if option vallab is
specified, these labels will be used in the treatment allocation file(s). filename2 should reside in the current data path.
Each row (observation) in this file defines a stratum. Levels of each stratification variable must be coded as consecutive
positive integers (1,2,3...). ralloc will check this and will also check that each stratum has been uniquely
specified. The program will warn, but not exit, if the product of levels over all stratification variables does not equal the
number of rows (strata).

countv(varname) specifies the numeric variable in filename2 whose values give the number of subjects (>0) requiring
randomisation in each stratum. countv() must be specified, and may only be specified, if using() is specified.
Values of the variable specified override the value of nsubj() should this option also be specified.

Remarks

ralloc addresses four (of the many) objectives of the design of a RCT:

(1) Random allocation of treatments to subjects. Each block represents a random permutation of up to 10
treatments specified.

(2) Avoiding unnecessary imbalance in the number of subjects allocated to each treatment. Allocation within blocks
of reasonable size achieves this. In the case of a trial with k treatments, even in the event of unexpected termination
of the trial, the imbalance (in each stratum) will be at most 1/k times the size of the largest block used.

(3) Maintenance of blinding by concealing the pattern of the blocks. A limited number of block sizes are chosen, the
number depending on the osize() option. Treatments are balanced within blocks; by default, there are equal numbers of each
treatment in each block, although the ratio may be varied (1:2 or 1:3) in a 2 treatment trial. Block sizes are chosen
at random with equal or unequal probabilities and then the order of block sizes is randomly shuffled. Such a scheme
makes "breaking the blind" by working out the block pattern extremely difficult. If, however, balance in the number
of allocations to each treatment is more critical than increased protection against breaking the blind, osize(1)
permits the choice of a constant block size. This may be desired in a trial with a small number of subjects.

(4) Ensuring that a record is kept of the randomisation protocol. The program saves the allocation sequence into
user-named .dta file(s). It also (i) writes an exact copy of the user's command in a note in the data file(s) and
(ii) writes the options specified (seed, number of subjects requested, etc.) and certain other useful information
(number of blocks used, number of subjects randomised, identification of the levels of each stratum defining the
schema for the current data file) as notes in the data file(s).

ralloc requires specification of 3 variables that will appear in the data set(s) that the command creates and
saves. These are listed under the syntax paragraph. The last of these (varname3) names the treatment variable
storing the randomly allocated treatment; values are 1, 2, 3, etc. labelled as "A", "B", "C", etc. respectively, unless
labels are specified with the trtlab() option.

ralloc creates two additional variables:

StratID is an integer identifier whose value is the same for every observation in a given stratum. Optionally,
value labels, specified either by stratlab() or, when a using() file is used, by slabv(), may
be attached.

SeqInBlk gives the order of the allocation within block. This variable is explicit if shape(long)
is specified, and implicit if shape(wide) is specified.

If using(filename2) is specified, ralloc adds each stratification variable to the data set and fills
observations with the values of the levels appropriate to the stratum.

If shape(wide) is specified, then each observation will be a block. ralloc will create k = max(blocksize)
new variables named varname3#, where # = 1...k, to store the allocated treatments for that block. Of course,
if a block's size, j, is such that j < k, missing values are stored in variables varname3(j+1)
through varname3k.

Should the original order of allocations be disturbed, then with the data in long form, it may be restored by

. sort StratiD varname1 SeqInBlk

The prudent user will open a log file before issuing a command such as ralloc. However, even if the
log file is lost, the data files contain, in the form of notes, the information needed to reproduce the
randomisation protocol.

Examples

Example 1: basic example

. ralloc block size treat, nsubj(600) seed(675) sav(mytrial) idvar(study_ID)

. list in 1/18, sepby(block)

allocates treatments A and B at random in a ratio of 1:1 in blocks of sizes 2, 4, 6, 8 and 10 to 600 subjects. Block
sizes are allocated unequally in the ratio 1:4:6:4:1 (Pascal's triangle). Seed is set at 675. Only 1 stratum is
specified (by default). Sequence is saved to mytrial.dta in long form. A unique subject identifier is stored in the
newly created variable study_ID.

Example 2: equal block distribution but 1:3 allocation ratio within each block

. ralloc bn bs Rx, nsubj(920) nt(2) osiz(4) ra(3) init(8) eq sav(mys)

allocates treatments A and B at random in ratio of 1:3 in blocks of sizes 8, 12, 16 and 20 to 920 subjects using
the default seed of 123456789. Roughly 25% of blocks will be of each size. Data saved in default (long) form to
mys.dta. Only 1 stratum (the default) is specified, and 1 file is saved. In fact, 932 subjects are allocated, the
extra 12 being required to complete the final block (the last block's size was 16, but the 920th subject was only
the 4th in the block).

Example 3: saving a file for each stratum's allocations

. ralloc blknum blksiz Rx, ns(494) osiz(2) eq ntreat(2) sav(mywide) shap(wide) seed(date)

trtlab(Placebo Active) strata(4) multif

allocates treatments labelled "Placebo" and "Active" equally in two block sizes, 2 and 4, to 494 subjects in each
of 4 strata (maybe it's a 4-centre trial). The seed is set to today's date in Stata's elapsed days
since January 1, 1960. Data are saved in wide form to 5 files: mywide.dta holds all allocations, and 4 additional files
named mywide_1.dta, mywide_2.dta, mywide_3.dta and mywide_4.dta hold stratum-specific allocations. A truncated listing
of data from mywide_4.dta looks like this (depending on today's date!):

. use mywide_4

. li in 1/7, noobs nodisp clean

StratID blknum blksiz Rx1 Rx2 Rx3 Rx4
4 498 2 Placebo Active . .
4 499 2 Active Placebo . .
4 500 2 Placebo Active . .
4 501 4 Active Placebo Placebo Active
4 502 2 Placebo Active . .
4 503 2 Placebo Active . .
4 504 2 Active Placebo . .

And we can easily recover the long form of the data:

. reshape long

. sort blknum SeqInBlk

. drop if Rx == .

. order StratID

. list in 1/10, noobs clean

StratID blknum SeqInBlk blksiz Rx
4 498 1 2 Placebo
4 498 2 2 Active
4 499 1 2 Active
4 499 2 2 Placebo
4 500 1 2 Placebo
4 500 2 2 Active
4 501 1 4 Active
4 501 2 4 Placebo
4 501 3 4 Placebo
4 501 4 4 Active

Example 4: unequal block size distribution and use of tables

. ralloc blknum blksiz Rx, ns(4984) osiz(4) ntr(4) sav(mys) strat(3) tab

allocates treatments A, B, C and D at random in ratio of 1:1:1:1 in blocks of sizes 4, 8, 12 and 16 to 4984 subjects
in each of 3 strata using the default seed. Block sizes are roughly in ratio of 1:3:3:1 (since equal was not
specified). For this example, the following tables will appear on-screen:

Frequency of block sizes in stratum 1:

block size | Freq. Percent Cum.
------------+-----------------------------------
4 | 62 12.50 12.50
8 | 183 36.90 49.40
12 | 185 37.30 86.69
16 | 66 13.31 100.00
------------+-----------------------------------
Total | 496 100.00

Frequency of block sizes in stratum 2:
output not shown

Frequency of block sizes in stratum 3:
output not shown

Frequency of block sizes over ALL data:

block size | Freq. Percent Cum.
------------+-----------------------------------
4 | 179 12.01 12.01
8 | 555 37.22 49.23
12 | 577 38.70 87.93
16 | 180 12.07 100.00
------------+-----------------------------------
Total | 1491 100.00

If one were to issue the command

. tab blksiz Rx

a table showing the frequency of treatment allocations across all strata would be produced:

| treatment
Block size | A B C D | Total
-----------+--------------------------------------------+----------
4 | 179 179 179 179 | 716
8 | 1110 1110 1110 1110 | 4440
12 | 1731 1731 1731 1731 | 6924
16 | 720 720 720 720 | 2880
-----------+--------------------------------------------+----------
Total | 3740 3740 3740 3740 | 14960

Note that 14960 subjects were randomised, compared with 3*4984 = 14952 requested. An extra 8 subjects were required
to ensure completeness of final blocks in the strata.

Example 5: individual specification of allocations to each stratum

Let us say we have a file, raltest6.dta, defining strata for a RCT to be conducted in 3 centres and we also seek to
balance allocations within 2 age groups. The number of allocations in each of the 6 strata are held in the variable
freq.

. use raltest6, clear

. list, clean

centre agegrp freq
1. 1 1 50
2. 1 2 80
3. 2 1 140
4. 2 2 100
5. 3 1 70
6. 3 2 100

Note that ralloc does not care about the order of variables in the dataset, nor about the sort order of the
observations, but it is easier to check the completeness of the schema if levels are coherently nested.

The command

. ralloc bID bsiz trt, sav(myrct) count(freq) using(raltest6) nsubj(80) seed(54109) multif

will produce the following output:

Counts defined in variable freq in file raltest6 will override the number of subjects specified
in option nsubj(80)

Number of strata read from file raltest6 is 6

number of stratum variables is 2

stratum variable 1 is centre

number of levels in centre is 3

stratum variable 2 is agegrp

number of levels in agegrp is 2

the stratum design and allocation numbers are:

centre agegrp freq
r1 1 1 50
r2 1 2 80
r3 2 1 140
r4 2 2 100
r5 3 1 70
r6 3 2 100

Allocations over all strata saved to file myrct.dta

....saving data from stratum 1 to file myrct_1_1.dta
....saving data from stratum 2 to file myrct_1_2.dta
....saving data from stratum 3 to file myrct_2_1.dta
....saving data from stratum 4 to file myrct_2_2.dta
....saving data from stratum 5 to file myrct_3_1.dta
....saving data from stratum 6 to file myrct_3_2.dta

Data file myrct (all allocations) is now in memory

Issue the -notes- command to review your specifications

Here are the notes saved to one of the 6 stratum-specific files generated:

. use myrct_2_1

. notes

_dta:

1. command issued was: ralloc bID bsiz trt, sav(myrct) count(freq) using(raltest6) nsubj(80)
seed(54109) multif

2. Randomisation schema created on 1 Oct 2006 22:38 using ralloc.ado version 3.3 in Stata version
9.2 born 28 Aug 2006

3. Seed used = 54109

4. Stratum definitions and numbers of allocations were defined in file 'raltest6.dta'

5. Number of strata requested = 6

6. This is a non-factorial, non-crossover trial with 2 treatments

7. See notes for parent file 'myrct.dta'

8. This is stratum 3 of 6 strata requested

9. ...level 2 of stratum variable -centre-

10. ...level 1 of stratum variable -agegrp-

If the shape(wide) option had been specified, additional notes would have been displayed:

11. Data saved in wide form:

12. ...recover 'SeqInBlk' by issuing reshape long command

13. ...then you may issue drop if trt == . without losing any allocations

Example 6: factorial design

Consider a study that aims to test both the efficacy of a blood pressure lowering medication, called BPzap,
versus a placebo, and the utility of two weight reduction exercise programs, called GymSweat and JogaBit,
versus normal activity on a specified cardiovascular endpoint. An efficient design might be a 2x3 factorial
RCT (although one should also consider if interaction is an issue here).

. ralloc blknum size Rx, sav(rctfact) factor(2*3) osiz(2) eq seed(4512) trtlab(BPzap Placebo GymSweat JogaBit normact) nsubj(300)

will allocate two treatments, called Rx1 and Rx2, to each of 300 subjects in a single stratum using a 2x3
factorial design. Blocks of size 6 and 12 with equal frequency will result. After the command we might

. list in 1/10

StratID blknum size SeqInBlk Rx1 Rx2
1. 1 1 6 1 Placebo normact
2. 1 1 6 2 BPzap JogaBit
3. 1 1 6 3 BPzap normact
4. 1 1 6 4 Placebo JogaBit
5. 1 1 6 5 BPzap GymSweat
6. 1 1 6 6 Placebo GymSweat
7. 1 2 12 1 BPzap GymSweat
8. 1 2 12 2 Placebo normact
9. 1 2 12 3 BPzap normact
10. 1 2 12 4 Placebo JogaBit

So, the 5th subject in Block 1 will receive BPzap and hits the gym, but the 2nd subject in Block 2 takes
Placebo and gets to slob around as usual.

. tab Rx1 Rx2

| Rx2
Rx1 | GymSweat JogaBit normact | Total
-----------+---------------------------------+----------
BPzap | 50 50 50 | 150
Placebo | 50 50 50 | 150
-----------+---------------------------------+----------
Total | 100 100 100 | 300

and we note the balance in allocations in each axis of the study.

Example 7: 2x2 factorial with 1:2 allocation ratios in both axes

We reformulate the preceding study as a 2x2 study by excluding the JogaBit treatment. Let's say we wish
to have twice as many on Placebo as BPzap, and also twice as many subjects on normal activity as on the
GymSweat regimen.

. ralloc blknum size Rx, sav(rctfact2) factor(2*2) osiz(2) eq seed(1131) trtlab(BPzap Placebo GymSweat normact) fratio(2 2) nsubj(300)

This command will give blocks of sizes 9 (the minimum possible with 1:2 allocation ratios in each axis) and
18 (because osize(2) was specified).

. tab Rx*

| Rx2
Rx1 | GymSweat normact | Total
-----------+----------------------+----------
BPzap | 34 68 | 102
Placebo | 68 136 | 204
-----------+----------------------+----------
Total | 102 204 | 306

Example 8: cross-over trial

We have a 2x2 crossover design supplemented by a switchback in period 3. The
trial compares a new anti-arthritic drug "HipLube" versus aspirin in chronic
osteoarthritis of the hip.

. ralloc Bnum Bsize medic, saving(chronOA) ns(28) trtlab(HipLube aspirin) xover(switch) strata(2) osiz(1) init(4)

will randomise 56 subjects (28 in each of 2 strata) using blocks of constant size, 4, and save results to chronOA.dta.
Each subject will receive either HipLube or aspirin in the 1st period, and the other drug in the 2nd period. The 1st
period's drug will be readministered in the 3rd period.

Example 9: non-standard allocation ratios

We have a parallel design with 5 treatments. We wish to allocate in the ratio 1:2:2:1:4. The ratio option does not
support this. Here's how to achieve it:

. ralloc Bnum Bsize treat, saving(mytrial) ntreat(10) nsubj(800) trtlab(A B B C C D E E E E)

. decode treat, gen(final_treat)

Note that we specified 10 "treatments", not 5, because the sum of the ratios of treatments was 10, and then we "tricked" ralloc
by duplicating the treatment names in the trtlab() option. The final decode command tidies things up; to see why,
crosstabulate variables treat and final_treat. Many other allocation ratio designs are possible with judicious choice of
ntreat() and trtlab().

Example 10: non-standard allocation ratios in a factorial design

We have a 2*3 factorial design with treatments A and B in the first axis, and C, D and E in the second axis. We wish to
allocate twice as many subjects to A (in each of C, D and E) as in B. The fratio() option does not support this.

. ralloc Bnum Bsize treat, saving(mytrial) nsubj(800) factor(3*3) trtlab(A A B C D E)

and a crosstabulation of treat1 by treat2 yields:

| treat2
treat1 | C D E | Total
-----------+---------------------------------+----------
A | 89 89 89 | 267
A | 89 89 89 | 267
B | 89 89 89 | 267
-----------+---------------------------------+----------
Total | 267 267 267 | 801

. decode treat1, gen(treat1_new)

and a crosstabulation of treat1_new by treat2 yields, as desired:

| treat2
treat1_new | C D E | Total
-----------+---------------------------------+----------
A | 178 178 178 | 534
B | 89 89 89 | 267
-----------+---------------------------------+----------
Total | 267 267 267 | 801

Note that we specified factor(3*3) not factor(2*3) and tidied up afterwards.

Example 11: a stratified 3-way (2x2x3) factorial design

We have a stratified RCT in neonates of supplemental oxygen, admission to NICU, and feeding mode.
The stratum is the parity of the mother. In this schema we specify labels both for the 7 treatments and for the 4 strata.
The application of the stratum value labels is toggled on by the vallab option.

. ralloc b s Rx, sav(temp) nsubj(500) fact(2*2*3) osize(1) strata(4) vallab multif seed(81372)

trtlab(suppl_O2 no_suppl_O2 NICU no_NICU NG_tube IV_feed breast)

stratlab(nulliparous primiparous biparous multiparous)

Part of the screen display will be:

Allocations over all strata saved to file temp.dta

....saving data from stratum 1 [nulliparous] to file temp_nulliparous.dta

....saving data from stratum 2 [primiparous] to file temp_primiparous.dta

....saving data from stratum 3 [biparous] to file temp_biparous.dta

....saving data from stratum 4 [multiparous] to file temp_multiparous.dta

. table Rx*, by(StratID)

----------------------------------------------------------------------
stratum | Rx3 and Rx2
identifier | ---- NG_tube --- ---- IV_feed --- ---- breast ----
and Rx1 | NICU no_NICU NICU no_NICU NICU no_NICU
------------+---------------------------------------------------------
nulliparous |
suppl_O2 | 42 42 42 42 42 42
no_suppl_O2 | 42 42 42 42 42 42
------------+---------------------------------------------------------
primiparous |
suppl_O2 | 42 42 42 42 42 42
no_suppl_O2 | 42 42 42 42 42 42
------------+---------------------------------------------------------
biparous |
suppl_O2 | 42 42 42 42 42 42
no_suppl_O2 | 42 42 42 42 42 42
------------+---------------------------------------------------------
multiparous |
suppl_O2 | 42 42 42 42 42 42
no_suppl_O2 | 42 42 42 42 42 42
----------------------------------------------------------------------

Example 12: individual specification of allocations to each stratum: using() file has complete stratum value labels

Let us say we have a file, raltest6_lab.dta, containing the allocation schema for a RCT with 6 strata:
3 centres (hospitals) and 2 age groups in each centre. Value labels for every level of both stratification variables
are defined in the data set.

. describe

Contains data from raltest6_lab.dta
obs: 6
vars: 3 1 Aug 2011 21:00
size: 96 (99.9% of memory free)
--------------------------------------------------------------------------
storage display value
variable name type format label variable label
--------------------------------------------------------------------------
centre byte %13.0g cenlab
agegrp int %9.0g agelab
freq int %9.0g
--------------------------------------------------------------------------

. label list

cenlab:
1 St Mary's
2 Seattle Grace
3 Chicago Hope
agelab:
1 young
2 old

. list, sep(6)

+-------------------------------+
| centre agegrp freq |
|-------------------------------|
1. | St Mary's young 50 |
2. | St Mary's old 80 |
3. | Seattle Grace young 140 |
4. | Seattle Grace old 100 |
5. | Chicago Hope young 70 |
6. | Chicago Hope old 100 |
+-------------------------------+

. ralloc b s treat, multif saving(RCTx) using(raltest6_lab) countv(freq) vallab

Part of the screen display will be:

Allocations over all strata saved to file RCTx.dta

....saving data from stratum 1 [St Mary's young] to file RCTx_St_Mary's_young.dta
....saving data from stratum 2 [St Mary's old] to file RCTx_St_Mary's_old.dta
....saving data from stratum 3 [Seattle Grace young] to file RCTx_Seattle_Grace_young.dta
....saving data from stratum 4 [Seattle Grace old] to file RCTx_Seattle_Grace_old.dta
....saving data from stratum 5 [Chicago Hope young] to file RCTx_Chicago_Hope_young.dta
....saving data from stratum 6 [Chicago Hope old] to file RCTx_Chicago_Hope_old.dta

Note that although the value labels on the variable centre in the using file raltest6_lab.dta
permit embedded spaces, these are substituted by underscores "_" in the suffixes of the stratum-specific
treatment allocation filenames. But the value labels attached to StratID and to the stratum-defining
variables within the allocation files preserve any spaces in the labels from the source (using file.

. list in 1/5

+-----------------------------------------------------------------+
| StratID b s SeqInBlk treat centre agegrp |
|-----------------------------------------------------------------|
1. | St Mary's young 1 4 1 A St Mary's young |
2. | St Mary's young 1 4 2 B St Mary's young |
3. | St Mary's young 1 4 3 B St Mary's young |
4. | St Mary's young 1 4 4 A St Mary's young |
5. | St Mary's young 2 6 1 A St Mary's young |
+-----------------------------------------------------------------+

Example 13: individual specification of allocations to each stratum: using() file has incomplete stratum value labels

Let us say we have a file, raltest12_lab.dta, containing the allocation schema for a RCT with 12 strata:
3 hospitals x 2 age groups x 2 sexes. Variables hospital and sex have value labels defined and attached, but
hospital = 2 does not have a label. Variable agegrp does not have a value label at all. If vallab
is specified, ralloc will use whatever labels are available.

. describe

Contains data from raltest12_lab.dta
obs: 12
vars: 4 2 Aug 2011 15:00
size: 108 (99.9% of memory free)
----------------------------------------------------------------
storage display value
variable name type format label variable label
----------------------------------------------------------------
centre byte %13.0g cenlab
agegrp byte %9.0g
sex byte %9.0g sexlab
freq int %9.0g
---------------------------------------------

. label list

cenlab:
1 St Mary's
3 Chicago Hope
sexlab:

1 male
2 female

. list, sepby(centre)

+---------------------------------------+
| centre agegrp sex freq |
|---------------------------------------|
1. | St Mary's 1 male 50 |
2. | St Mary's 1 female 80 |
3. | St Mary's 2 male 60 |
4. | St Mary's 2 female 80 |
|---------------------------------------|
5. | 2 1 male 140 |
6. | 2 1 female 100 |
7. | 2 2 male 100 |
8. | 2 2 female 100 |
|---------------------------------------|
9. | Chicago Hope 1 male 70 |
10. | Chicago Hope 1 female 100 |
11. | Chicago Hope 2 male 50 |
12. | Chicago Hope 2 female 50 |
+---------------------------------------+

. ralloc b s treat, multif saving(RCTx) using(raltest12_lab) countv(freq) vallab

Part of the screen display will be:

Allocations over all strata saved to file RCTx.dta

....saving data from stratum 1 [St Mary's 1 male] to file RCTx_St_Mary's_1_male.dta
....saving data from stratum 2 [St Mary's 1 female] to file RCTx_St_Mary's_1_female.dta
....saving data from stratum 3 [St Mary's 2 male] to file RCTx_St_Mary's_2_male.dta
....saving data from stratum 4 [St Mary's 2 female] to file RCTx_St_Mary's_2_female.dta
....saving data from stratum 5 [2 1 male] to file RCTx_2_1_male.dta
....saving data from stratum 6 [2 1 female] to file RCTx_2_1_female.dta
....saving data from stratum 7 [2 2 male] to file RCTx_2_2_male.dta
....saving data from stratum 8 [2 2 female] to file RCTx_2_2_female.dta
....saving data from stratum 9 [Chicago Hope 1 male] to file RCTx_Chicago_Hope_1_male.dta
....saving data from stratum 10 [Chicago Hope 1 female] to file RCTx_Chicago_Hope_1_female.dta
....saving data from stratum 11 [Chicago Hope 2 male] to file RCTx_Chicago_Hope_2_male.dta
....saving data from stratum 12 [Chicago Hope 2 female] to file RCTx_Chicago_Hope_2_female.dta

. tab StratID treat

| treat
stratum identifier | A B | Total
----------------------+----------------------+----------
St Mary's 1 male | 27 27 | 54
St Mary's 1 female | 41 41 | 82
St Mary's 2 male | 31 31 | 62
St Mary's 2 female | 40 40 | 80
2 1 male | 70 70 | 140
2 1 female | 51 51 | 102
2 2 male | 52 52 | 104
2 2 female | 51 51 | 102
Chicago Hope 1 male | 36 36 | 72
Chicago Hope 1 female | 50 50 | 100
Chicago Hope 2 male | 25 25 | 50
Chicago Hope 2 female | 27 27 | 54
----------------------+----------------------+----------
Total | 501 501 | 1,002

Acknowledgements

I thank Liddy Griffith, Tom Sullivan, Nick Cox, Nikolaos Pandis and participants at the 2nd Australian and New Zealand Stata Users Group meeting
(Melbourne, 2006) for assisting with the development and/or testing of ralloc.

Reference

Jones, B. and Kenward, M.G. 1989. Design and Analysis of Crossover Trials. London: Chapman and Hall.

Author

Philip Ryan

Data Management & Analysis Centre

Discipline of Public Health

Faculty of Health Sciences

University of Adelaide

South Australia

philip.ryan@adelaide.edu.au

See also

STB: ralloc in STB-54 sxd1.2, STB-50 sxd1.1, STB-41 sxd1

SJ: SJ 8(1):146; SJ 8(4):594