allocationTable: Generate Allocation Tables for the Randomization Module

Description

Generate allocation table for the REDCap randomization module. Randomization may be stratified by other (categorical) variables in the data set as well as by data access group. Additionally, randomization may be blocked to ensure balanced groups throughout the allocation

Usage

allocationTable(
  rcon,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = NULL,
  ...
)
# S3 method for redcapApiConnection
allocationTable(
  rcon,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = c(1, 1),
  ...
)
makeChoices(random_levels, block.size, weights)
allocationTable_offline(
  meta_data,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = c(1, 1),
  ...
)

Arguments

rcon: A REDCap connection object as generated by redcapConnection
random: The field name to be randomized.
strata: Field names by which to stratify the randomization.
group: A field name giving a group by which randomization should be stratified. This could also be listed in strata, but the argument is provided to remain consistent with the REDCap user interface.
dag.id: Data Access Group IDs. See the package wiki for instructions on how to get the ID's. (They cannot currently be accessed via the API)
replicates: The number of randomizations to perform within each stratum
block.size: Block size for the randomization. Blocking is recommended to ensure balanced groups throughout the randomization. This may be a vector to indicate variable block sizes throughout the randomization.
block.size.shift: A vector the same length as block.size where the first element is 0. This controls when the block size changes as a proportion of the total sample size. When block.size=c(8, 4, 2) and block.size.shift = c(0, .5, .9), the first half of the randomization is performed in blocks of 8, then the next 40 percent of the randomization is performed in blocks of 4, with the last 10 percent performed in blocks of 2.
seed.dev: At least one value is required. If only one value is given, it will be converted to a vector with length equal to the number of strata. Values will be incremented by 100 to provide independent randomizations. This may also have length equal to the number of strata.
seed.prod: Same as seed.prod, but used to seed the production allocation. No pairwise elements of seed.dev and seed.prod may be equal. This guarantees that the two randomization schemes are unique.
weights: An optional vector giving the sampling weights for each of the randomization groups. There must be one number for each level of the randomization variable. If named, the names must match the group labels. If unnamed, the group labels will be assigned in the same order they appear in the data dictionary. The weights will be normalized, so they do not need to sum to 1.0. In other words, weights=c(3, 1) can indicate a 3:1 sampling ratio.
...: Arguments to be passed to other methods
random_levels: A vector of the randomization group level names. Determined from the data dictionary.
meta_data: A text string giving the location of the data dictionary downloaded from REDCap.

Author

Benjamin Nutter

Details

Each element in block.size must be a multiple of the number of groups in the randomized variable.

The 'offline' version of the function operates on the data dictionary file downloaded from REDCap. This is made available for instances where the API can not be accessed for some reason (such as waiting for API approval from the REDCap administrator).

The value of replicates controls how many allocations are generated. It is possible to get slightly more replicates than requested if your blocking design cannot exactly match replicates. For example, if you as for 30 replicates in blocks of 8, a warning will be printed and you will receive 32 replicates in the randomization table.

References

More instruction on using redcapAPI to produce allocation tables is on the package wiki: https://github.com/vubiostat/redcapAPI/wiki/Randomization-Module

Please refer to your institution's API documentation.

Additional details on API parameters are found on the package wiki at https://github.com/vubiostat/redcapAPI/wiki/REDCap-API-Parameters