Skip to contents

Integration Point: Dropout - Binary Outcome

Gabriel Potvin

October 16, 2025

IntegrationPointDropoutBinary.Rmd

←\leftarrow Go back to the Integration Point: Dropout page

Input Variables

When creating a custom R script, you can optionally use specific variables provided by East Horizon’s engine itself. These variables are automatically available and do not need to be set by the user, except for the UserParam variable. Refer to the table below for the variables that are available for this integration point, outcome, and study objective.

Variable Type Description
NumSub Integer Number of subjects in the trial.
NumArm Integer Number of arms in the trial ﴾including placebo/control, and experimental﴿. Only applicable when Study Objective = Multiple Arm Confirmatory and for Vaccine Efficacy (Better Response = Smaller Value, Test = 1 - Ratio of Proportions). For Vaccine Efficacy, it is set to 2.
ProbDrop Numeric or Vector of Numeric - For Study Objective = Two Arm Confirmatory: Numeric probability of dropout, assumed to be the same across the two arms. If you need different probabilities, you can use a custom UserParam.
- For Study Objective = Multiple Arm Confirmatory: Vector of length NumArm, indicating the probability of dropout for each arm. The first element corresponds to the control group, followed by the probabilities for each experimental arm in sequence.
TreatmentID Vector of Integer Vector of length NumSub, indicating the allocation of subjects to arms. Index 0 represents placebo/control. For example, [0, 0, 1] indicates three subjects: two in the control group and one experimental. Only applicable when Study Objective = Multiple Arm Confirmatory.
FollowUpDur Numeric Follow-up duration, acts as By Time for response proportions. Only applicable for Vaccine Efficacy (Better Response = Smaller Value, Test = 1 - Ratio of Proportions).
UserParam List Contains all user-defined parameters specified in the East Horizon interface (refer to the Instructions section). To access these parameters in your R code, use the syntax: UserParam$NameOfTheVariable, replacing NameOfTheVariable with the appropriate parameter name.

Expected Output Variable

East Horizon expects an output of a specific type. Refer to the table below for the expected output for this integration point:

Type Description
List A named list containing CensorInd and ErrorCode.

Expected Members of the Output List

Members Type Description
CensorInd Vector of Integer Vector of length NumSub, containing the generated censor indicator values for all subjects. Only applicable for standard binary outcome (Better Response = Larger Value, Test = Difference of Proportions or Custom). Possible values:
– 0: Dropout
– 1: Completer.
DropOutTime Vector of Numeric Vector of length NumSub, containing the generated dropout times for all subjects. Only applicable for Vaccine Efficacy (Better Response = Smaller Value, Test = 1 - Ratio of Proportions).
ErrorCode Integer Optional. Can be used to handle errors in your script:
– 0: No error.
– Positive Integer: Nonfatal error, the current simulation will be aborted, but the next simulation will proceed.
– Negative Integer: Fatal error, no further simulations will be attempted.

Note: Additional custom variables can be included as members of the output list. All outputs will automatically be available as input variables for analysis or treatment selection endpoints in the SimData variable as described here: Variables of SimData.

Minimal Template

Your R script could contain a function such as this one, with a name of your choice. All applicable input variables must be declared, even if they are not used in the script. Input variables that are not applicable (depending on the study objective, and on standard binary outcome vs. Vaccine Efficacy) must not be declared. We recommend always declaring UserParam as a default NULL value in the function arguments, as this will ensure that the same function will work regardless of whether the user has specified any custom parameters in East Horizon.

Detailed templates with step-by-step explanations are available here: Dropout.BinaryAndContinuous.R for 2-Arm and Dropout.BinaryAndContinuous.MAMS.R for Multiple Arm.

For standard binary outcome (Better Response = Larger Value, Test = Difference of Proportions or Custom)

For Study Objective = Two Arm Confirmatory 

GenCensorInd <- function( NumSub, ProbDrop, UserParam = NULL )
{
  nError                <- 0 # Error handling (no error)
  vCensoringIndicator   <- rep( 1, NumSub ) # Initializing vector to 1 (all patients are completers)    
  
  # Write the actual code here.
  # Store the generated censor indicator values in a vector called vCensoringIndicator

  return( list( CensorInd = as.integer( vPatientOutcome ), ErrorCode = as.integer( nError ) ) )
}

For Study Objective = Multiple Arm Confirmatory 

GenCensorInd <- function( NumSub, NumArm, ProbDrop, TreatmentID, UserParam = NULL )
{
  nError                <- 0 # Error handling (no error)
  vCensoringIndicator   <- rep( 1, NumSub ) # Initializing vector to 1 (all patients are completers)    
  
  # Write the actual code here.
  # Store the generated censor indicator values in a vector called vCensoringIndicator

  return( list( CensorInd = as.integer( vPatientOutcome ), ErrorCode = as.integer( nError ) ) )
}

For Vaccine Efficacy (Better Response = Smaller Value, Test = 1 - Ratio of Proportions) 

GenDropout <- function( NumSub, NumArm, TreatmentID, FollowUpDur, ProbDrop, UserParam = NULL )
{
  nError                <- 0 # Error handling (no error)
  vDropoutTimes         <- rep( 0, NumSub ) # Initializing vector of dropout times to 0 
  
  # Write the actual code here.
  # Store the generated dropout times values in a vector called vDropoutTimes

  return( list( DropOutTime = as.double( vDropoutTimes ), ErrorCode = as.integer( nError ) ) )
}

Examples

Explore the following examples for more context:

  1. 2-Arm, Single Endpoint - Simulate Patient Dropout
  2. Multiple Arm, Continuous or Binary Outcome - Simulate Patient Dropout