{smcl}
{* 2007-10-07}
{cmd:help ralloc}
{hline}

{title:Title}

{p 4 8 2}
{bf:ralloc -- Random allocation of treatments in controlled trials}


{title:Syntax}

{p 8 17 2}
{bf:ralloc} {it:varname1}   {it:varname2}   {it:varname3} {cmd:,} {opt sav:ing}{bf:(}{it:filename1}{bf:)}  [{it:options}]

{p 8 17 2}
{bf:ralloc ?}

{p 4 4 2}
where:

{p 8}
{it: varname1} is the variable that will store the block identifier.{p_end}
{p 8}
{it: varname2} is the variable that will store the block size.{p_end}
{p 8}
{it: varname3} is the variable that will store treatment allocation.{p_end}
{p 8}
{it: filename1} is the file that will store the randomised allocations.{p_end}


{synoptset 30 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Common options}
{synopt:{opt idvar(varname)}}species variable to store unique study identifier{p_end}
{synopt:{opt se:ed(#|"date")}}set seed for the random number generator{p_end}
{synopt:{opt ns:ubj(#)}}specifies number of allocations in each stratum{p_end}
{synopt:{opt nt:reat(#)}}specifies number of treatments (1 to 10){p_end}
{synopt:{opt ra:tio(#)}}specifies allocation ratio (1:#) in 2 treatment trial. # is 1, 2, or 3{p_end}
{synopt:{opt os:ize(#)}}specifies number of different block sizes (1 to 7){p_end}
{synopt:{opt init(#)}}specifies smallest block size to be used{p_end}
{synopt:[{cmdab:no:}]{opt eq:ual}}specifies whether or not the frequency of block sizes is the same{p_end}
{synopt:{opt strat:a(#)}}specifies number of strata{p_end}
{synopt:[{cmdab:no}]{opt tab:les}}request informative tables to be displayed{p_end}
{synopt:{opt trtlab}{bf:(}{it:label1 [label2]}...{bf:)}}specifies treatment labels{p_end}
{synopt:{opt matsiz(#)}}set matrix size{p_end}

{syntab:Special designs}
{synopt:{opt fact:or}{bf:(}{it:#1}{bf:*}{it:#2}{bf:)}}specifies a {it:#1}x{it:#2} factorial trial where 
{it:#1}, {it:#2} = 2, 3 or 4.{p_end}
{synopt:{opt fact:or}{bf:(}{it:#1}{bf:*}{it:#2}{bf:*}{it:#3}{bf:)}}specifies a {it:#1}x{it:#2}x{it:#3} factorial trial
 where {it:#1}, {it:#2}, {it:#3} = 2 or 3  but subject to {it:#1} {ul:<} {it:#2} {ul:<} {it:#3} {p_end}
{synopt:{opt fra:tio}{bf:(}{it:#1} {it:#2}{bf:)}}specifies allocation ratios in a 2x2 factorial trial where 
{it:#1}, {it:#2} = 1 or 2.{p_end}
{synopt:{opt xo:ver(stand|switch|extra)}}specifies design of a 2x2 crossover trial{p_end}

{syntab:Saving file}
{synopt:[{cmdab:no}]{opt multif}}save multiple files (one for each stratum) with {it:filename1} as stub{p_end}
{synopt:{opt shap:e(long|wide)}}specifies shape of {it:filename1}{p_end}

{syntab:File defining strata}
{synopt:{opt us:ing}{bf:(}{it:filename2}{bf:)}}names an existing .dta file holding desired stratum specific allocation 
counts{p_end}
{synopt:{opt count:v}{bf:(}{it:varname}{bf:)}}specifies name of variable in {it:filename2} that stores desired number of 
allocations in each stratum{p_end}
{synoptline}


{title:Description}

{p 4 4 2}
{bf: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 for 2x2x2, 2x2x3, 2x3x3 and 3x3x3 designs. {bf:ralloc} 
will also handle a 2x2 crossover design with or without a supplementary 3rd period as either 
a "switchback" or "extra period" design ({it:Jones and Kenward 1989}). {p_end}

{p 4 4 2}
A typical use of {bf: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.

{p 4 4 2}
The second syntax ({cmd:ralloc ?}) displays the syntax diagram for the first syntax.


{title:Options}

{dlgtab:Common options}

{p 4 8 2}
{opt idvar(varname)} specifies the name of the unique subject identifier. This identifier is completely uninformative of any 
subject characteristic.

{p 4 8 2}
{opt 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 {bf:ralloc} to set the seed to today's 
date (number of days elapsed since Jan 1 1960). 

{p 4 8 2}
{opt nsubj}{bf:(}{it:#}{bf:)} specifies the total number of subjects {it:in each stratum} requiring a random treatment allocation. If 
unspecified, the default is 100. {bf:ralloc} may yield a number greater than # if this is required to complete the final block in
any stratum. # is overridden if option {bf:using} is specified.

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

{p 4 8 2}
{opt ratio}{bf:(}{it:#}{bf:)} 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 
{bf:ratio(}1{bf:)}, the default, may be specified. However, one may allocate certain ratios by "tricking" {bf:ralloc} by judicious 
naming of treatments using the {bf:trtlab} option - see Examples 9 and 10 below.

{p 4 8 2}
{opt osize}{bf:(}1{bf:|}2{bf:|}3{bf:|}4{bf:|}5{bf:|}6{bf:|}7{bf:)} specifies how many different sizes of blocks will 
be used. For example, if 3 treatment arms are chosen, then {bf:osize(}5{bf:)}, 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 {bf:nsubj} is low. {bf:osize(}1{bf:)} gives a constant block size.

{p 4 8 2}
{opt init(#)} specifies the initiating value of the sequence defining the block sizes. {cmd:ralloc} allows 5 schema:{p_end}

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

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

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

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

{p 8 12 2}
(5) {it:2x2 crossover design with balanced allocation}: See case (1) above.

{p 8 12 2}
In all cases, when specified, {opt init} must be an integer multiple of the appropriate default.

{p 4 8 2}
{opt [no]}{opt equal} indicates whether or not block sizes will be allocated in equal proportions. In the example given 
under the {bf: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 ({bf:noequal}) allocates treatments in proportion to elements of Pascal's triangle. 
In the above example, if {bf:equal} were not specified (or {bf: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 
{bf:init} option for another way to limit the number of small blocks, albeit at the cost of increasing the number of
large blocks.  If {bf:osize} is 1 or 2, then equality of distribution of block size(s) is forced.

{p 4 8 2}
{opt 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 {opt strata(60)} would be specified.
This option may be specified with or without the {opt using} option (see below). If {opt using} is not specified, each 
stratum will hold the number of allocations specified by the {opt nsubj} option. If {opt using} is specified, the value 
of {opt strata} is overridden by the number of rows in {it:filename2}. Note that {cmd:ralloc} uses Stata matrices and 
so an absolute upper limit on the number of strata that may be specified is 800 (Intercooled).

{p 4 8 2}
{opt [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 {bf:notables}.

{p 4 8 2}
{opt 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 8 
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: {opt tr1lab(string)}, {opt 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 {bf:ratio}.  See Examples 9 and 10 below.

{p 4 8 2}
{opt matsiz(#)} sets the maximum size of a Stata matrix. This is a rarely used option, as {cmd:ralloc} chooses a 
matrix size appropriate to the stratification schema specified.


{dlgtab:Special designs}

{p 4 8 2}
{opt factor(string)} specifies that the trial has a factorial design with two or three "axes of randomisation". {it: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 {opt fratio} is specified in a 2x2 design. The names of the treatment variables will be 
{it:varname3}1, {it:varname3}2 and, if required for the 3-way design, {it:varname3}3.

{p 4 8 2}
{opt fratio(string)} specifies, in the case of a 2x2 factorial design, the ratio of allocations in {it: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, {opt fratio(2 1)} would be specified.

{p 4 8 2}
{opt xover(string)} specifies the design as a 2x2 crossover. {it:string} may be one of {it:stand} for the standard 
2 treatment, 2 period design, {it:switch} for the switchback design where each subject receives the treatment
assigned for period 1 in period 3, or {it: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 {it:varname3}1,
{it:varname3}2 and, if required, {it:varname3}3.


{dlgtab:Saving file}

{p 4 8 2}
{cmd:saving}{bf:(}{it:filename1}{bf:)} specifies the name of the file to which data are saved. This is a required "option". 
If more than one stratum is specified, either by the {cmd:strata} option or the {cmd:using} option then, in addition to saving 
all random allocations across all strata to {it:filename1}, allocations for each stratum may be saved to individual files (see 
option {cmd:multif}). For these, {it:filename1} is used as a stub to name one file for each stratum. The schema is:

{center:{it:filename1_n1}[{it:_n2_n3} ... {it:_nk}]}

{p 8 8 2}
for a trial with 1 to k stratification variables. {it:n1} identifies the level of the stratum of the 1st stratification variable, 
{it: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. 

{p 8 8 2}
For example, if we specified {cmd:saving}{bf:(}myfile{bf:)} {it:and} {cmd:multif} and we had only one stratification variable 
with 10 levels, the filenames would be: myfile, myfile_01, myfile_02, ..., myfile_09, myfile_10 (each with .dta extension). If 
there were a second stratification variable, with say, 3 levels, we would have myfile.dta plus 30 files named: myfile_01_1, 
myfile_01_2, myfile_01_3, myfile_02_1, ....., myfile_10_3.

{p 4 8 2}
{opt [no]}{opt 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 {cmd:nomultif} meaning that just one file holding all allocations 
will be generated.

{p 4 8 2}
{opt shape(long|wide)} allows specification of the output to {it:filename1} (or to each of the files with prefix stub 
{it:filename1} if {opt 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.


{dlgtab:File defining strata}

{p 4 8 2}
{opt using(filename2)} is a Stata .dta file defining the stratification schema. The file must consist solely of variables 
defining strata plus one other variable giving the number of subjects required to be randomised in each stratum (the {bf:countv} 
variable, see below). {it:filename2} should reside in the current data path. Each row (observation) in this file defines a 
stratum. Levels of a stratification variable must be coded as consecutive positive integers (1,2,3...). {cmd:ralloc} will 
check this and will also check that the product of levels over all stratification variables equals the number of rows (strata).

{p 4 8 2}
{opt countv(varname)} specifies the variable in {it:filename2} whose values give the number of subjects requiring 
randomisation in each stratum. {bf:countv} is specified if and only if {bf:using} is specified. Values of the variable 
specified override the value of {bf:nsubj} should this option also be specified.


{title:Remarks}

{p 4 4 2}
{cmd:ralloc} addresses 4 (of the many) objectives of the design of a RCT:{p_end}

{p 4 8 2}
(1) Random allocation of treatments to subjects. Each block represents a random permutation of up to 10
treatments specified.

{p 4 8 2}
(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 {it:k} treatments, even in the event of unexpected termination 
of the trial, the imbalance (in each stratum) will be at most 1/{it:k} times the size of the largest block used.

{p 4 8 2}
(3) Maintenance of blinding by concealing the pattern of the blocks. A limited number of block sizes are chosen, the 
number depending on the {opt osize} option. Treatments are balanced within blocks; by default, 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, {opt osize(1)} 
permits the choice of a constant block size. This may be desired in a trial with a small number of subjects.

{p 4 8 2}
(4) Ensuring that a record is kept of the randomisation protocol. The program saves the allocation sequence into 
user-named .{it: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).

{p 4 4 2}
{cmd: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 ({it: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 {opt trtlab} option. In a factorial or crossover design the variable name may be only 
7 characters long to permit a "1", "2", or "3" to be suffixed (permits use under older versions of Stata with limits
on the length of variable names). {p_end}

{p 4 4 2}
{cmd:ralloc} creates 2 additional variables: {p_end}

{p 6 10 2}
{bf:StratID} is an integer identifier constant for each observation in a given stratum. {p_end}

{p 6 10 2}
{bf:SeqInBlk} gives the order of the allocation within block.  This variable is explicit if {opt shape(long)} 
is specified, and implicit if {opt shape(wide)} is specified. {p_end}

{p 4 4 2}
If {opt using(filename2)} is specified, {cmd:ralloc} adds each stratification variable to the data set and fills 
observations with the values of the levels appropriate to the stratum.

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

{p 4 4 2}
Should the original order of allocations be disturbed, then with the data in long form, it may be restored by:

{p 20 4 2}  . {helpb sort} {bf:StratiD}  {it:varname1}  {bf:SeqInBlk}

{p 4 4 2}
Note that {cmd:ralloc} issues a {helpb clear} command immediately after it is invoked, so existing data in memory 
will be lost.

{p 4 4 2}
The prudent user will open a {helpb log:log file} before issuing a command such as {cmd:ralloc}. However, even if the 
log file is lost, the data files contain, in the form of {helpb notes}, the information needed to reproduce the 
randomisation protocol. {p_end}


{title:Examples}

{p 2}
{bf:Example 1: basic example} {p_end}

{p 4 8 2}
{cmd:. ralloc block size treat, nsubj(600) seed(675) sav(mytrial) idvar(study_ID)} {p_end}
{p 4 8 2}
{cmd:. list in 1/18, sepby(block)} {p_end}

{p 4 4 2}
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 {bf:study_ID}.{p_end}


{p 2}
{bf:Example 2: equal block distribution but 1:3 allocation ratio within each block}{p_end}

{p 4 8 2}
{cmd:. ralloc bn bs Rx, nsubj(920) nt(2) osiz(4) ra(3) init(8) eq sav(mys)} {p_end}

{p 4 4 2}
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 
Stata's 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).{p_end}


{p 2}
{bf:Example 3: saving a file for each stratum's allocations} {p_end}

{p 4 8 2}
{cmd:. ralloc blknum blksiz Rx, ns(494) osiz(2) eq ntreat(2) sav(mywide) shap(wide) seed(date)}{p_end}
{p 8}
{cmd:trtlab(Placebo Active) strata(4) multif} {p_end}

{p 4 4 2}
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 {helpb seed} is set to today's {helpb dates: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!):{p_end}

{p 8 4 2}
{cmd:. use mywide_4} {p_end}
{p 8 4 2}
{cmd:. li in 1/7, noobs nodisp clean} {p_end}

{space 8}{bf:StratID     blknum     blksiz        Rx1        Rx2        Rx3        Rx4}
{space 14}4        498          2    Placebo     Active          .          .
{space 14}4        499          2     Active    Placebo          .          .
{space 14}4        500          2    Placebo     Active          .          .
{space 14}4        501          4     Active    Placebo    Placebo     Active
{space 14}4        502          2    Placebo     Active          .          .
{space 14}4        503          2    Placebo     Active          .          .
{space 14}4        504          2     Active    Placebo          .          .
{p}

{p 4 4 2}
And we can easily recover the long form of the data: {p_end}

{p 8 4 2}
{cmd:. reshape long}{p_end}
{p 8 4 2}
{cmd:. sort blknum SeqInBlk}{p_end}
{p 8 4 2}
{cmd:. drop if Rx == .}{p_end}
{p 8 4 2}
{cmd:. order StratID}{p_end}
{p 8 4 2}
{cmd:. list in 1/10, noobs clean}{p_end}

{space 8}{bf:StratID     blknum   SeqInBlk     blksiz         Rx}
{space 14}4        498          1          2    Placebo
{space 14}4        498          2          2     Active
{space 14}4        499          1          2     Active
{space 14}4        499          2          2    Placebo
{space 14}4        500          1          2    Placebo
{space 14}4        500          2          2     Active
{space 14}4        501          1          4     Active
{space 14}4        501          2          4    Placebo
{space 14}4        501          3          4    Placebo
{space 14}4        501          4          4     Active
{p}


{p 2}
{bf:Example 4: unequal block size distribution and use of tables} {p_end}

{p 4 8 2}
{cmd:. ralloc blknum blksiz Rx, ns(4984) osiz(4) ntr(4) sav(mys) strat(3) tab}

{p 4 4 2}
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 {opt equal} was {it:not} 
specified). For this example, the following tables will appear on-screen:{p_end}

{space 8}{bf:Frequency of block sizes in stratum 1:} 

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

{space 8}{bf:Frequency of block sizes in stratum 2:}
{space 14}{it:output not shown}

{space 8}{bf:Frequency of block sizes in stratum 3:}
{space 14}{it:output not shown}

{space 8}{bf:Frequency of block sizes over ALL data:}

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

{p 4 4 2}
If one were to issue the command:{p_end}

{p 8 12 2}
{cmd:. tab blksiz Rx}{p_end}

{p 4 4 2}
a table showing the frequency of treatment allocations across all strata would be produced:{p_end}

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

{p 4 4 2}
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.{p_end}


{p 2}
{bf:Example 5: individual specification of allocations to each stratum} {p_end}

{p 4 4 2}
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".

{p 8 12 2}
{cmd:. use raltest6, clear}{p_end}
{p 8 4 2}
{cmd:. list, clean}{p_end} 

{space 14}{bf:centre    agegrp      freq}
{space 9}1.        1         1        50
{space 9}2.        1         2        80
{space 9}3.        2         1       140
{space 9}4.        2         2       100
{space 9}5.        3         1        70
{space 9}6.        3         2       100

{p 4 4 2}
Note that {cmd:ralloc} does not care about the order of variables in the data set, nor about the sort order of the 
observations, but it is easier to check the completeness of the schema if levels are coherently nested.

{p 4 4 2}
The command:

{p 8 11 2}
{cmd:. ralloc bID bsiz trt, sav(myrct) count(freq) using(raltest6) nsubj(80) seed(54109) multif}

{p 4 4 2}
will cause the following output:{p_end}

{p 8 10 2}
{it}Counts defined in variable freq in file{sf} raltest6 {it}will override the number of subjects specified 
in option nsubj(80){sf}{p_end}

{p 8 10 2}
{it}Number of strata read from file{sf} raltest6 {it}is 6{sf}{p_end}
{p 10 12 2}
{it}number of stratum variables is 2{sf}{p_end}

{p 8 10 2}
{it}stratum variable 1 is centre{sf}{p_end}
{p 10 12 2}
{it}number of levels in centre is 3{sf}{p_end}

{p 8 10 2}
{it}stratum variable 2 is agegrp{sf}{p_end}
{p 10 12 2}
{it}number of levels in agegrp is 2{sf}{p_end}

{p 8 10 2}
{it}the stratum design and allocation numbers are:{sf}{p_end}

{space 7}{bf:       centre  agegrp    freq}
{space 7}   r1       1       1      50
{space 7}   r2       1       2      80
{space 7}   r3       2       1     140
{space 7}   r4       2       2     100
{space 7}   r5       3       1      70
{space 7}   r6       3       2     100

{p 8 10 2}
{it}Allocations over all strata saved to file{sf} myrct{p_end}

{space 7}   ....saving data from stratum 1 to file myrct_1_1
{space 7}   ....saving data from stratum 2 to file myrct_1_2
{space 7}   ....saving data from stratum 3 to file myrct_2_1
{space 7}   ....saving data from stratum 4 to file myrct_2_2
{space 7}   ....saving data from stratum 5 to file myrct_3_1
{space 7}   ....saving data from stratum 6 to file myrct_3_2

{p 8 10 2}
{it}Data file{sf} myrct {it}(all allocations) is now in memory{sf}{p_end}
{p 8 10 2}
{it}Issue the -notes- command to review your specifications{sf}{p_end}


{p 4 4 2}
Here are the notes saved to one of the 6 stratum-specific files generated:{p_end}

{p 8 11 2}
{cmd:. use myrct_2_1}{p_end}
{p 8 11 2}
{cmd:. notes}{p_end} 
{p 8 10 2}
_dta:{p_end}
{p 10 15 2}
1.  command issued was: ralloc bID bsiz trt, sav(myrct) count(freq) using(raltest6) nsubj(80) 
seed(54109) multif {p_end}
{p 10 15 2}
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 {p_end}
{p 10 15 2}
3.  Seed used = 54109 {p_end}
{p 10 15 2}
4.  Stratum definitions and numbers of allocations were defined in file 'raltest6.dta' {p_end}
{p 10 15 2}
5.  Number of strata requested = 6 {p_end}
{p 10 15 2}
6.  This is a non-factorial, non-crossover trial with 2 treatments {p_end}
{p 10 15 2}
7.  See notes for parent file 'myrct.dta' {p_end}
{p 10 15 2}
8.  This is stratum 3 of 6 strata requested {p_end}
{p 10 15 2}
9.  ...level 2 of stratum variable -centre- {p_end}
{p 9 15 2}
10.  ...level 1 of stratum variable -agegrp- {p_end}

{p 4 4 2}If the {opt shape(wide)} option had been specified, additional notes would have been displayed: {p_end}

{p 9 15 2}
11.  Data saved in wide form: {p_end}
{p 9 15 2}
12.  ...recover 'SeqInBlk' by issuing {cmd:reshape long} command {p_end}
{p 9 15 2}
13.  ...then you may issue {cmd:drop if trt == .} without losing any allocations {p_end}


{p 2}
{bf:Example 6: factorial design} {p_end}

{p 4 4 2}
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.) {p_end}

{p 4 8 2}
{cmd:. ralloc blknum size Rx, sav(rctfact) factor(2*3) osiz(2) eq seed(4512) trtlab(BPzap Placebo GymSweat JogaBit normact) nsubj(300)} {p_end}

{p 4 4 2}
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:{p_end}

{p 8 12 2}
{cmd:. list in 1/10}{p_end}


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

{p 4 4 2}
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. {p_end}

{p 8 12 2}
{cmd:. tab Rx1 Rx2}{p_end}

{space 8}           |               Rx2
{space 8}       Rx1 |  GymSweat    JogaBit    normact |     Total
{space 8}-----------+---------------------------------+----------
{space 8}     BPzap |        50         50         50 |       150
{space 8}   Placebo |        50         50         50 |       150
{space 8}-----------+---------------------------------+----------
{space 8}     Total |       100        100        100 |       300

{p 4 4 2}
and we note the balance in allocations in each axis of the study.{p_end}


{p 2}
{bf:Example 7: 2x2 factorial with 1:2 allocation ratios in both axes} {p_end}

{p 4 4 2}
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.{p_end}

{p 4 8 2}
{cmd:. ralloc blknum size Rx, sav(rctfact2) factor(2*2) osiz(2) eq seed(1131) trtlab(BPzap Placebo GymSweat normact) fratio(2 2) nsubj(300)} {p_end}

{p 4 4 2}
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). {p_end}

{p 8 12 2}
{cmd:. tab Rx*} {p_end}

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


{p 2}
{bf:Example 8: cross-over trial} {p_end}

{p 4 4 2}
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. {p_end}

{p 4 8 2}
{cmd:. ralloc Bnum Bsize medic, saving(chronOA) ns(28) trtlab(HipLube aspirin) xover(switch) strata(2) osiz(1) init(4)}

{p 4 4 2}
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. {p_end}


{p 2}
{bf:Example 9: non-standard allocation ratios} {p_end}

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

{p 4 8 2}
{cmd:. ralloc Bnum Bsize treat, saving(mytrial) ntreat(10) nsubj(800) trtlab(A B B C C D E E E E)} {p_end}
{p 4 8 2}
{cmd:. decode treat, gen(final_treat)} {p_end}

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


{p 2}
{bf:Example 10: non-standard allocation ratios in a factorial design} {p_end}

{p 4 4 2}
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 {bf:fratio} option does not support this. {p_end}

{p 4 8 2}
{cmd:. ralloc Bnum Bsize treat, saving(mytrial) nsubj(800) factor(3*3) trtlab(A A B C D E)} {p_end}

{p 4 4 2}
and a crosstabulation of treat1 by treat2 yields:{p_end}

{space 8}           |              treat2
{space 8}    treat1 |         C          D          E |     Total
{space 8}-----------+---------------------------------+----------
{space 8}         A |        89         89         89 |       267 
{space 8}         A |        89         89         89 |       267 
{space 8}         B |        89         89         89 |       267 
{space 8}-----------+---------------------------------+----------
{space 8}     Total |       267        267        267 |       801 

{p 4 8 2}
{cmd:. decode treat, gen(treat1_new)} {p_end}

{p 4 4 2}
and a crosstabulation of treat1_new by treat2 yields, as desired:{p_end}

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

{p 4 4 2}
Note that we specified {bf:factor(3*3)} not {bf:factor(2*3)} and tidied up afterwards. {p_end}


{p 2}
{bf:Example 11: a 3-way factorial design} {p_end}

{p 4 8 2}
{cmd:. ralloc b s t, sav(temp) nsubj(1000) fact(2*3*3) osize(1)} {p_end}
{p 4 8 2}
{cmd:. table t3 t2 t1, row col scol} {p_end}

{space 8}---------------------------------------------------------------------------------
{space 8}      |                                 t1 and t2                                
{space 8}      | ---------- A ----------  ---------- B ----------  -------- Total --------
{space 8}   t3 |     C     D     E Total      C     D     E Total      C     D     E Total
{space 8}------+--------------------------------------------------------------------------
{space 8}    F |    56    56    56   168     56    56    56   168    112   112   112   336
{space 8}    G |    56    56    56   168     56    56    56   168    112   112   112   336
{space 8}    H |    56    56    56   168     56    56    56   168    112   112   112   336
{space 8}      | 
{space 8}Total |   168   168   168   504    168   168   168   504    336   336   336 1,008
{space 8}---------------------------------------------------------------------------------

{p 4 8 2}
{cmd:. list in 1/20, sepby(b)} {p_end}

{space 8}  +--------------------------------------------+
{space 8}  | StratID   b    s   SeqInBlk   t1   t2   t3 |
{space 8}  |--------------------------------------------|
{space 8}  |       1   1   18          1    B    E    F |
{space 8}  |       1   1   18          2    B    D    G |
{space 8}  |       1   1   18          3    A    C    F |
{space 8}  |       1   1   18          4    B    C    F |
{space 8}  |       1   1   18          5    A    D    H |
{space 8}  |       1   1   18          6    A    C    G |
{space 8}  |       1   1   18          7    B    D    H |
{space 8}  |       1   1   18          8    B    E    H |
{space 8}  |       1   1   18          9    A    D    G |
{space 8}  |       1   1   18         10    B    D    F |
{space 8}  |       1   1   18         11    B    C    G |
{space 8}  |       1   1   18         12    A    C    H |
{space 8}  |       1   1   18         13    B    C    H |
{space 8}  |       1   1   18         14    B    E    G |
{space 8}  |       1   1   18         15    A    E    H |
{space 8}  |       1   1   18         16    A    E    G |
{space 8}  |       1   1   18         17    A    D    F |
{space 8}  |       1   1   18         18    A    E    F |
{space 8}  |--------------------------------------------|
{space 8}  |       1   2   18          1    B    C    G |
{space 8}  |       1   2   18          2    B    E    H |
{space 8}  +--------------------------------------------+



{title:Acknowledgements}

{p 4 4 2}
I thank Liddy Griffith, Operations Manager at the Data Management & Analysis Centre, Faculty of Health Sciences, 
University of Adelaide, for helpful comments. Suggestions for improvements to the program were made by participants 
at the 2nd Australian and New Zealand Stata Users Group meeting in Melbourne in September 2006.


{title:Reference}

{p 4 4 2}
Jones B and Kenward MG. Design and Analysis of Crossover Trials. London. Chapman and Hall 1989.


{title: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


{title:See also}

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