Using R for randomisation

R statistical programming language can be used to define the randomisation method, giving users complete flexibility and the ability to use bespoke or novel methods for their trials. Randomisation data is passed into an isolated, short-lived container running R, and the chosen treatment group is returned to the randomisation system. Metadata can also be exchanged with the R function to allow state to be preserved between calls.

Configuration

To use the method, first it has to be selected in the Randomisation configuration section of the CRF builder for your application. Once the application is built, an authorised user must create and activate an R randomisation function (using the Manage randomisation functions button on the R page). When this is done, the system is ready to randomise.

Function syntax is checked when saving. If an issue is detected, a Syntax error message is shown for the function. Users can hover over or click on the message to view the error details. A function can not be activated if it has errors.

R function

At the very minimum, each randomisation function receives data from the participant's randomisation form and metadata from the previous function execution (if any).

Three global variables are available in the randomisation function:

• randomisation  A named list containing data from the randomisation form of the participant being randomised. The R code function will show the available data items as comments at the top of the file.
• metadata  Any data structure returned from previous randomisation(s). This can be used to preserve state between function calls, such as the random number sequence state or running totals.
• auxiliary_data  Named list containing any additional data needed for randomisation, if configured in your trial. For instance, this can be used to pass site information or outcome data into the function.

The function's result must consist of a named list containing:

• group  A string representing the randomised group
• metadata  A variable of any type, which will be stored and provided to the next randomisation; your function is in full control over this variable. You can set this to NULL   if no metadata is needed.

The function does not need to explicitly return a value. The very last statement is treated as the result.

Simple randomisation example

Simple randomisation function with 50% probability to randomise to A or B:

group <- sample(c("A", "B"), size = 1, prob = c(0.5, 0.5))

list(
  group = group,
  metadata = NULL
)

See more R code examples.

Metadata

Metadata provides a mechanism to preserve state between randomisations. Each function receives the metadata variable and should return it in the response. The same metadata is passed into the active R randomisation function (and will include metadata from any previously used function), so ensure data is isolated between the functions if necessary (e.g. by using named list with top level keys that are different for different functions). Metadata is displayed in the R randomisation log so can be inspected in the web UI.

Auxiliary data

Sometimes more information is required to randomise (e.g. outcome data for RAR randomisation).

Red Pill allows configuration of additional data to be provided to the randomisation function such as:

• CRF form data
• historical randomisation data
• data pulled from an external source

This data is available in the randomisation function as the auxiliary_data variable (a named list). The format of the variable is determined by the auxiliary data configuration agreed with and configured by Sealed Envelope support.

Example

You request data from the outcome form and historical randomisations to be included in auxiliary data. Your randomisation function will receive the following auxiliary_data variable:

auxiliary_data = list(
  outcomes = data.frame(
    id = c(1, 2, 3),
    subjectId = c(1, 2, 3),
    Outcome = c("Success", "No success", "Success")
  ),
  randomisation_data <- data.frame(
    id = c(1, 2, 3),
    subjectId = c(1, 2, 3),
    dateRandomised = c("2025-09-03 07:47:30", "2025-09-03 07:47:31", "2025-09-03 07:47:32"),
    "group" = c("A", "B", "B"),
    manual = c("No", "No", "No"),
    dateManual = c(NA, NA, NA),
    timeManual = c(NA, NA, NA),
    timezoneManual = c(NA, NA, NA),
    error = c(FALSE, FALSE, FALSE),
    reasonError = c(NA, NA, NA),
    dateError = c(NA, NA, NA)
  )
)

The data can by cross-referenced using subjectId column.

Packages

The R environment is based on R version 4.5 and the following packages are installed:

• jsonlite and dependencies
• randomizeR and dependencies
• Base R, CRAN recommended packages and those listed here.

Note that the container R code runs in has no outside internet access so it is not possible to install new packages yourself. If you need a particular package for your R code then please contact Sealed Envelope support.

Randomising

The randomisation process is the same as with other methods. The user fills in a randomisation form, which triggers randomisation. The R code is evaluated in an isolated container and must return the randomisation result. Returned metadata is stored and provided for the next function execution.

If the R function fails for any reason, it will cause an error on the randomisation page and the form will not be saved.

Randomisation log

The randomisation log shows the data sent to the active R function and the returned result. It will also display any messages that have been defined in the R code.

Changing the R function mid-trial

A new R function can be specified and activated at any time. R functions can be duplicated from existing entries and updated. These are marked 'Draft' until the 'Use this function' menu option is chosen. Once a function has been used to randomise it is marked 'Used' and becomes immutable.

The active function can be deactivated at any time. Randomisation cannot take place until another function is activated.

Any new R-code function should be thoroughly tested before being made active in a live trial. Special attention should be paid to how the new function will work within the context of the existing randomisations and metadata.

All changes to the R function are shown in the audit trail.

The R logo is © 2016 The R Foundation and is used under the CC-BY-SA 4.0 license.