Integration Point: Dropout - Time-to-Event Outcome
Gabriel Potvin
January 16, 2025
IntegrationPointDropoutTimeToEvent.RmdGo 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 and
outcome.
| Variable | Type | Description |
|---|---|---|
| NumSub | Integer | Number of subjects in the trial. |
| NumArm | Integer | Number of arms in the trial ﴾including placebo/control, and experimental﴿. |
| 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. |
| DropMethod | Integer | Selected input method for dropout parameters from the East Horizon
dropdown list: – 1: Dropout hazard rate.– 2: Probability of dropout. |
| NumPrd | Integer | Number of dropout periods in the trial. Equals to 1 if
DropMethod = 2. |
| PrdTime | Vector of Numeric | Vector or length NumPrd, indicating the times for
dropout parameters. Depends on DropMethod:– If DropMethod = 1: Starting times of dropout periods.– If DropMethod = 2: Times at which the probabilities of dropout
are specified. |
| DropParam | Matrix | Size: NumPrd rows
NumArm columns. Dropout parameters dependent on
DropMethod:– If DropMethod = 1: Specifies
dropout hazard rates per arm per period. DropParam[i, j]
represents the hazard rate for the jth arm in the
ith period.– If SurvMethod = 2: Specifies
cumulative probabilities of dropout per arm per period.
SurvParam[i, j] represents the probability of dropout for
the jth arm in the ith period. |
| 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 DropOutTime and
ErrorCode. |
Expected Members of the Output List
| Members | Type | Description |
|---|---|---|
| DropOutTime | Vector of Numeric | Vector of length NumSub, containing the generated
dropout times for each subject. A value of Inf indicates
that the subject does not drop out. |
| 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. |
Minimal Template
Your R script could contain a function such as this one, with a name
of your choice. All input variables must be declared, even if they are
not used in the script. 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.
GenDropTimes <- function( NumSub, NumArm, TreatmentID, DropMethod, NumPrd, PrdTime, DropParam, UserParam = NULL )
{
nError <- 0 # Error handling (no error)
vDropoutTime <- rep( Inf, NumSub ) # Initializing dropout times vector to Inf (all patients are completers)
# Write the actual code here.
# Store the generated dropout times in a vector called vDropoutTime
return( list( DropOutTime = as.double( vDropoutTime ), ErrorCode = as.integer( nError ) ) )
}A detailed template with step-by-step explanations is available here: Dropout.Survival.R