Skip to contents

\leftarrow Go back to the Integration Point: Analysis - Binary Outcome, Multiple Arm 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
SimData Data Frame Subject data generated in current simulation, one row per subject. To access these variables in your R code, use the syntax: SimData$NameOfTheVariable, replacing NameOfTheVariable with the appropriate variable name. Refer to the table below for more information.
DesignParam List Input parameters which may be needed to compute test statistic and perform test. To access these variables in your R code, use the syntax: DesignParam$NameOfTheVariable, replacing NameOfTheVariable with the appropriate variable name. Refer to the table below for more information.
LookInfo List Input parameters related to multiple looks which may be needed to compute test statistic and perform test. To access these variables in your R code, use the syntax: LookInfo$NameOfTheVariable, replacing NameOfTheVariable with the appropriate variable name. Refer to the table below for more information.
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.

Variables of SimData

The variables in SimData are generated during data generation, and depend on the current simulation. Some common and useful variables are:

Variable Type Description
SimData$ArrivalTime Vector of Numeric Vector of length equal to the number of subjects, containing the generated arrival times for all subjects.
SimData$TreatmentID Vector of Integer Vector of length equal to the number of subjects, containing the allocation indices for all subjects:
0: Control arm.
1: First experimental arm.
– etc.
SimData$Response Vector of Numeric Vector of length equal to the number of subjects, containing the generated responses for all subjects.
SimData$CensorIndOrg Vector of Integer Vector of length equal to the number of subjects, containing the generated censor indicator values for all subjects:
0: Dropout.
1: Completer.

Variables of DesignParam

Variable Type Description
DesignParam$Alpha Numeric Type I Error (for one-sided tests).
DesignParam$TrialType Integer Trial Type:
0: Superiority.
DesignParam$TestType Integer Test Type:
0: One-sided.
DesignParam$TailType Integer Nature of critical region:
0: Left-tailed.
1: Right-tailed.
DesignParam$InitialAllocInfo Vector of Numeric Vector of length equal to the number of treatment arms, containing the ratios of the treatment group sample sizes to control group sample size.
DesignParam$SampleSize Integer Sample size of the trial.
DesignParam$MaxCompleters Integer Maximum number of completers.
DesignParam$RespLag Numeric Follow-up duration.
DesignParam$MultAdjMethod Integer Multiple comparison procedure:
0: Bonferroni.
1: Sidak (not available in East Horizon Explore).
2: Weighted Bonferroni<.br>– 3: Holm’s Step Down (not available in East Horizon Explore).
4: Hochberg’s Step Up.
5: Hommel’s Step Up (not available in East Horizon Explore).
6: Fixed Sequence.
7: Fallback.
8: Dunnett’s Single Step.
9: Dunnett’s Step Down (not available in East Horizon Explore).
10: Dunnett’s Step Up (not available in East Horizon Explore).
DesignParam$NumTreatments Integer Number of treatment arms.
DesignParam$AlphaProp Vector of Numeric Vector of length DesignParam$NumTreatments, containing the proportion of Alpha for each treatment arm.
DesignParam$TestSeq Vector of Integer Vector of length DesignParam$NumTreatments, containing the test sequence for each comparison (each treatment arm).

Variables of LookInfo

Variable Type Description
LookInfo$NumLooks Integer Number of looks.
LookInfo$CurrLookIndex Integer Current index look, starting from 1.
LookInfo$InfoFrac Vector of Numeric Vector of length LookInfo$NumLooks, containing the information fraction for each look.
LookInfo$CumAlpha Vector of Numeric Vector of length LookInfo$NumLooks, containing the cumulative alpha spent (for one-sided tests) for each look.
LookInfo$CumAlphaLower Vector of Numeric Vector of length LookInfo$NumLooks, containing the lower cumulative alpha spent (for two-sided tests) for each look. Not available in East Horizon Explore.
LookInfo$CumAlphaUpper Vector of Numeric Vector of length LookInfo$NumLooks, containing the upper cumulative alpha spent (for two-sided tests) for each look. Not available in East Horizon Explore.
LookInfo$CumCompleters Vector of Integer Vector of length LookInfo$NumLooks, containing the cumulative number of completers for each look.
LookInfo$RejType Integer Rejection type:
0: One-sided efficacy upper
1: One-sided futility upper.
2: One-sided efficacy lower.
3: One-sided futility lower.
4: One-sided efficacy upper, futility lower.
5: One-sided efficacy lower, futility upper.
6: Two-sided efficacy only (not available in East Horizon Explore).
7: Two-sided futility only (not available in East Horizon Explore).
8: Two-sided efficacy, futility (not available in East Horizon Explore).
9: Equivalence (not available in East Horizon Explore).
LookInfo$EffBdryScale Integer Efficacy boundary scale:
0: Z scale.
1: Adjusted p-value scale (not available in East Horizon Explore).
LookInfo$EffBdry Vector of Numeric Vector of length LookInfo$NumLooks, containing the efficacy boundary values (for one-sided tests) for each look.
LookInfo$EffBdryLower Vector of Numeric Vector of length LookInfo$NumLooks, containing the lower efficacy boundary values (for two-sided tests) for each look. Not available in East Horizon Explore.
LookInfo$EffBdryUpper Vector of Numeric Vector of length LookInfo$NumLooks, containing the upper efficacy boundary values (for two-sided tests) for each look. Not available in East Horizon Explore.
LookInfo$FutBdryScale Integer Futility boundary scale:
0: Z scale.
1: p-value scale (not available in East Horizon Explore).
2: Delta scale.
3: Conditional power scale (not available in East Horizon Explore).
LookInfo$FutBdry Vector of Numeric Vector of length LookInfo$NumLooks, containing the futility boundary values (for one-sided tests) for each look.
LookInfo$FutBdryLower Vector of Numeric Vector of length LookInfo$NumLooks, containing the lower futility boundary values (for two-sided tests) for each look. Not available in East Horizon Explore.
LookInfo$FutBdryUpper Vector of Numeric Vector of length LookInfo$NumLooks, containing the upper futility boundary values (for two-sided tests) for each look. Not available in East Horizon Explore.

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 ErrorCode and one of the following: Decision, or a combination of TestStat, AdjPVal, RawPVal and Delta (see below for more information).

The output list can take one of these two forms.

Option 1 (Decision): Expected Members of the Output List

Members Type Description
Decision Vector of Integer Vector of length DesignParam$NumTreatments, containing the boundary crossing decision for each treatment arm:
0: No boundary crossed.
1: Lower efficacy boundary crossed.
2: Upper efficacy boundary crossed.
4: Equivalence boundary crossed (not available in East Horizon Explore).
You can use the functions CyneRgy::GetDecisionString and CyneRgy::GetDecision to get the decision value. See the template below for the correct usage.
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.
  • Decision should take care of multiple comparison procedures adjustment appropriately.
  • When there is no efficacy boundary to be crossed, the return code of 0 stands for futility in the final look. Similarly, when there is no futility boundary to be crossed, the return code of 0 stands for efficacy in the final look. Use the functions CyneRgy::GetDecisionString and CyneRgy::GetDecision to get decision values in a simple way.

Option 2 (TestStat): Expected Members of the Output List

Members Type Description
TestStat Vector of Numeric Vector of length DesignParam$NumTreatments, containing the value of appropriate test statistic on Wald ﴾Z﴿ scale for each treatment arm.
Delta Numeric Estimate of Delta. Required if LookInfo$FutBdryScale = 2 (futility boundary scale is Delta).
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.
  • If the design does not have any futility boundary, TestStat will be used to check for efficacy.
  • If LookInfo$FutBdryScale = 1 (futility boundary scale is adjusted p-value scale), TestStat will be used to check for both efficacy and futility.
  • If LookInfo$FutBdryScale = 2 (futility boundary scale is Delta scale), TestStat will be used to check for efficacy and Delta will be used to check for futility.

Option 3 (AdjPVal): Expected Members of the Output List

Members Type Description
AdjPVal Vector of Numeric Vector of length DesignParam$NumTreatments, containing the p-values computed from test statistics and adjusted for multiple comparison procedures for each treatment arm.
Delta Numeric Estimate of Delta. Required if LookInfo$FutBdryScale = 2 (futility boundary scale is Delta).
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.
  • If the design does not have any futility boundary, AdjPVal will be used to check for efficacy.
  • If LookInfo$FutBdryScale = 1 (futility boundary scale is adjusted p-value scale), AdjPVal will be used to check for both efficacy and futility.
  • If LookInfo$FutBdryScale = 2 (futility boundary scale is Delta scale), AdjPVal will be used to check for efficacy and Delta will be used to check for futility.

Option 4 (RawPVal): Expected Members of the Output List

Members Type Description
RawPVal Vector of Numeric Vector of length DesignParam$NumTreatments, containing the p-values computed from test statistics for each treatment arm.
Delta Numeric Estimate of Delta. Required if LookInfo$FutBdryScale = 2 (futility boundary scale is Delta).
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.
  • If the design does not have any futility boundary, RawPVal will be used to check for efficacy.
  • If LookInfo$FutBdryScale = 1 (futility boundary scale is adjusted p-value scale), this option cannot be used.
  • If LookInfo$FutBdryScale = 2 (futility boundary scale is Delta scale), RawPVal will be used to check for efficacy and Delta will be used to check for futility.

Minimal Templates

Your R script could contain a function such as these ones, 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: Analyze.Binary.R.

Minimal Template for Option 1 (Decision)

PerformDecision <- function( SimData, DesignParam, LookInfo = NULL, UserParam = NULL )
{
    library( CyneRgy )
    nError              <- 0 # Error handling (no error)
    NumTreatments       <- DesignParam$NumTreatments
    vDecision           <- rep( 0, NumTreatments )  # Initializing decision vector to 0
    
    # This is an example using GetDecisionString and GetDecision.
    # Decision should take care of multiple comparison procedures adjustment appropriately.
    # Write the actual code here.
    
    # These variables are from LookInfo because it is a group sequential design.
    nQtyOfLooks          <- LookInfo$NumLooks
    nLookIndex           <- LookInfo$CurrLookIndex
    nQtyOfPatsInAnalysis <- LookInfo$CumCompleters[ nLookIndex ]
    RejType              <- LookInfo$RejType
    TailType             <- DesignParam$TailType
    
    for( i in 1:NumTreatments )
    {
        # Write the actual code here.
        # It is a group sequential design, so interim looks and futility check are possible.
        bIAEfficacyCheck <- TRUE # If TRUE, declares efficacy at the interim look.
        bIAFutilityCheck <- FALSE # If TRUE, declares futility at the interim look.
        bFAEfficacyCheck <- TRUE # If TRUE, declares efficacy at the final look.
        # Usually, the Check variables would be conditional statements such as 'dTValue > dBoundary'.
        # This would be different for each treatment arm.
    
        strDecision <- CyneRgy::GetDecisionString( LookInfo, nLookIndex, nQtyOfLooks,
                                               bIAEfficacyCondition = bIAEfficacyCheck,
                                               bIAFutilityCondition = bIAFutilityCheck,
                                               bFAEfficacyCondition = bFAEfficacyCheck )

        nDecision <- CyneRgy::GetDecision( strDecision, DesignParam, LookInfo )
        vDecision[ i ] = nDecision
    }
    
    
    return( list( Decision = as.integer( vDecision ), ErrorCode = as.integer( nError ) ) )
}

Minimal Template for Option 2 (TestStat)

ComputeTestStat <- function( SimData, DesignParam, LookInfo = NULL, UserParam = NULL )
{
    nError              <- 0 # Error handling (no error)
    NumTreatments       <- DesignParam$NumTreatments
    vTestStatistic      <- rep( 0, NumTreatments )  # Initializing test statistic vector to 0   
    dDelta              <- 0 # Use if futility boundary scale is Delta
    
    # Write the actual code here.
    # Store the computed test statistic for each treatment arm in vTestStatistic.
    
    return( list( TestStat = as.double( vTestStatistic ),
                  Delta = as.double( dDelta ), # Include if futility boundary scale is Delta
                  ErrorCode = as.integer( nError ) ) )
}

Minimal Template for Option 3 (AdjPVal)

ComputeTestStat <- function( SimData, DesignParam, LookInfo = NULL, UserParam = NULL )
{
    nError              <- 0 # Error handling (no error)
    NumTreatments       <- DesignParam$NumTreatments
    vAdjPVal            <- rep( 0, NumTreatments )  # Initializing p-value vector to 0  
    dDelta              <- 0 # Use if futility boundary scale is Delta
    
    # Write the actual code here.
    # Store the computed adjusted p-value for each treatment arm in vAdjPVal.
    
    return( list( AdjPVal = as.double( vTestStatistic ),
                  Delta = as.double( dDelta ), # Include if futility boundary scale is Delta
                  ErrorCode = as.integer( nError ) ) )
}

Minimal Template for Option 4 (RawPVal)

ComputeTestStat <- function( SimData, DesignParam, LookInfo = NULL, UserParam = NULL )
{
    nError              <- 0 # Error handling (no error)
    NumTreatments       <- DesignParam$NumTreatments
    vRawPVal            <- rep( 0, NumTreatments )  # Initializing p-value vector to 0
    dDelta              <- 0 # Use if futility boundary scale is Delta
    
    # Write the actual code here.
    # Store the computed p-value for each treatment arm in vRawPVal.
    
    return( list( RawPVal = as.double( vTestStatistic ),
                  Delta = as.double( dDelta ), # Include if futility boundary scale is Delta
                  ErrorCode = as.integer( nError ) ) )
}

Examples

Explore the following examples for more context:

  1. 2-Arm, Binary Outcome - Analysis
    • This example focuses on a Two-Arm Confirmatory study objective but can still provide valuable insights.