redcapAPI (version 2.8.0)

allocationTable: Generate Allocation Tables for the Randomization Module

Description

These methods enable the user to generate allocation tables 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),
  ...
)
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),
  ...
)

Value

Returns a list with the elements

dev_allocation	data.frame with the randomization allocations for the development environment.
prod_allocation	data.frame with the randomization allocations for the production environment.
dev_seed	The random seed values for the development environment.
prod_seed	The random seed values for the production environment.
blocks	Blocking scheme used to generate the randomization.
weights	Weighting scheme for the randomization.

Arguments

rcon

A redcapConnection object.

random

character(1). The field name to be randomized.

strata

character. Field names by which to stratify the randomization.

group

character(1). 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

integerish. Data Access Group IDs.

replicates

integerish(1). The number of randomizations to perform within each stratum

block.size

integerish. 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

numeric on the interval [0, 1]. 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 ten percent performed in blocks of 2.

seed.dev

integerish. 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

integerish. Same as seed.dev, 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 pass to other methods

meta_data

character(1). For the offline method, a text string giving the location of the data dictionary downloaded from REDCap.

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 cannot 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 the users asks for 30 replicates in blocks of 8, a warning will be printed and 32 replicates will be returned in the randomization table.

Examples

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
allocationTable(rcon, 
                random = "treatment_assignment", 
                strata = c("demographic_group", "hospital_group"), 
                replicates = 12, 
                block.size = 4, 
                seed.dev = 12345, 
                seed.prod = 54321)
}