Allocate treatment to subjects

The Allocate component is responsible for allocating simulated subjects to a treatment group.

Usage

allocateTreatments(
  trts,
  subjects,
  prop = NULL,
  ordered = FALSE,
  seed = .deriveFromMasterSeed(),
  idCol = getEctdColName("Subject"),
  trtCol = getEctdColName("Trt")
)

Arguments

trts

(Required) Maximum number of treatments to which subjects can be allocated. Subjects will be allocated to treatments "1:trts"

subjects

(Required) Number of subjects to be allocated to each treatment group

prop

(Optional) Proportion of subjects in each group. By default, equal proportions of subjects are assigned to each treatment arm

ordered

(Optional) Should treatments be allocated in order of subject number (ie. first N subjects gets treatment 1) as opposed to random assignment. Default is FALSE (random assignment)

seed

(Optional) Random seed to allocate interims. Based on the current master seed by default

idCol

(Optional) Subject variable name. "SUBJ" by default

trtCol

(Optional) Treatment variable name. "TRT" by default

Value

A data frame with subjects and treatment allocations. This data frame will contain 2 variables: SUBJThe Subjects identifier TRTThe Treatment numeric that the subject is allocated to ...

Details

Subjects numbered "1" to "sum(subjects)" are allocated to a single treatment or treatment sequence. The possible treatments are numbered "1" to "trts".

If "subjects" is a single number, the proportion argument is used to determine the proportion to be allocated to each treatment. By default, subjects are allocated randomly to each treatment group with probability "1/trts".

If "subjects" is a vector with length "trts", this explicity defines the number of subjects to be allocate to each treatment group.

If "ordered" is TRUE, the allocation is done in order (eg. subject 1 gets treatment 1). This can be useful in simulations to quickly verify that the correct number or proportion of subjects is allocated to each treatment. If "FALSE", random allocation is performed.

Author

Rich Pugh

Examples

  # allocate 6 subjects randomly to 3 treatment groups
  allocateTreatments(trts = 3, subjects = 6)
#> Warning: Not all the treatments have been allocated
#>   SUBJ TRT
#> 1    1   2
#> 2    2   1
#> 3    3   2
#> 4    4   2
#> 5    5   2
#> 6    6   1

  # allocate 6 subjects randomly to 3 treatment groups
  #  and present in treatment order
  allocateTreatments(trts = 3, subjects = 6, ordered = TRUE)
#>   SUBJ TRT
#> 1    1   1
#> 2    2   1
#> 3    3   2
#> 4    4   3
#> 5    5   3
#> 6    6   3

  # allocate 2 subjects to group 1, 2 to group 2, 3 to group 3
  # First two subjects will be allocated to TRT 1
  allocateTreatments(trts = 3, subjects = c(2, 2, 3), ordered = TRUE)
#>   SUBJ TRT
#> 1    1   1
#> 2    2   1
#> 3    3   2
#> 4    4   2
#> 5    5   3
#> 6    6   3
#> 7    7   3

  # allocation according to proportions
  # 6 subjects to allocate in total in 2 groups
  # 20% will be in group 1, 80% will be in group 2
  allocateTreatments(trts = 2, subjects = 6, prop = c(0.2, 0.8))
#> Warning: Not all the treatments have been allocated
#>   SUBJ TRT
#> 1    1   2
#> 2    2   2
#> 3    3   2
#> 4    4   2
#> 5    5   2
#> 6    6   2

  # allocation according to proportions
  # 6 subjects to allocate in total in 2 groups
  # 20% will be in group 1, 80% will be in group 2
  # TRT 1 will be allocated first
  allocateTreatments(trts = 2,
                     subjects = 6,
                     prop = c(0.2, 0.8),
                     ordered = TRUE)
#> Warning: Not all the treatments have been allocated
#>   SUBJ TRT
#> 1    1   2
#> 2    2   2
#> 3    3   2
#> 4    4   2
#> 5    5   2
#> 6    6   2