Skip to contents

Integration Point: Response - Time-to-Event Outcome

Gabriel Potvin

October 16, 2025

IntegrationPointResponseTimeToEvent.Rmd

←\leftarrow Go back to the Integration Point: Response 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.
SurvMethod Integer Selected input method for survival analysis from the East Horizon dropdown list:
– 1: Hazard rate.
– 2: Cumulative % survival rates.
– 3: Median survival times.
NumPrd Integer Number of periods in the trial. Fixed to 1 for Study Objective = Multiple Arm Confirmatory.
PrdTime Matrix of Numeric 2D array of size NumPrd x NumArm, indicating the times used to specify survival parameters. Equals to NA for the control arm. Depends on SurvMethod:
– If SurvMethod = 1: Starting times of hazard pieces.
– If SurvMethod = 2: Times at which the cumulative % survivals are specified.
– If SurvMethod = 3: Defaults to 0.
SurvParam Matrix of List 2D array of size NumPrd x NumArm, indicating the survival parameters. Depends on SurvMethod:
– If SurvMethod = 1: Specifies hazard rates per arm per period. Size: NumPrd rows ×\timesNumArm columns, where SurvParam[i, j] represents the hazard rate for the jth arm in the ith period.
– If SurvMethod = 2: Specifies cumulative % survival rates per arm per period. Size: NumPrd rows ×\timesNumArm columns, where SurvParam[i, j] represents the cumulative % survival for the jth arm in the ith period.
– If SurvMethod = 3: Contains median survival times for each arm. Size: 1 row ×\times 2 columns, where column 1 is control and column 2 is experimental.
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 SurvivalTime and ErrorCode.

Expected Members of the Output List

Members Type Description
SurvivalTime Vector of Numeric Vector of length NumSub, containing the generated time to response values for each subject.
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 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.

A detailed template with step-by-step explanations is available here: SimulatePatientOutcome.TimeToEvent.R

GenerateResponse <- function( NumSub, NumArm, TreatmentID, SurvMethod, NumPrd, PrdTime, SurvParam, UserParam = NULL )
{
  nError            <- 0 # Error handling (no error)
  vSurvTime         <- rep( 0, NumSub ) # Initializing survival times array to 0    
  
  # Write the actual code here.
  # Store the generated survival time values in a vector called vSurvTime.

  return( list( SurvivalTime = as.double( vSurvTime ), ErrorCode = as.integer( nError ) ) )
}

Examples

Explore the following examples for more context:

  1. 2 Arm, Time-To-Event Outcome - Patient Simulation
  2. Multiple Arm, Time-To-Event Outcome - Patient Simulation