Integration Point: Analysis - Binary Outcome, Two Arm, Group Sequential Design
Gabriel Potvin
January 16, 2025
IntegrationPointAnalysisBinaryTwoArmGroupSequential.RmdGo back to the Integration Point: Analysis - Binary Outcome, Two 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$LowerAlpha | Numeric | Lower Type I Error (for two-sided tests). Not available in East Horizon Explore. |
| DesignParam$UpperAlpha | Numeric | Upper Type I Error (for two-sided tests). Not available in East Horizon Explore. |
| DesignParam$TrialType | Integer | Trial Type: – 0: Superiority.– 1:
Non-inferiority.– 2: Equivalence (not available in East
Horizon Explore).– 3: Super-superiority. |
| DesignParam$TestType | Integer | Test Type: – 0: One-sided.– 1:
Two-sided symmetric (not available in East Horizon Explore).– 2: Two-sided asymmetric (not available in East Horizon
Explore). |
| DesignParam$TailType | Integer | Nature of critical region: – 0: Left-tailed.– 1: Right-tailed. |
| DesignParam$AllocInfo | 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$TrtEffNull | Numeric | Treatment effect under null on natural scale. Applicable for
DesignParam$TrialType = 1 (non-inferiority trials) only.
Set to 0 for DesignParam$TrialType = 0 (superiority). |
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: 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, Delta, CtrlCompleters,
TrmtCompleters, and CtrlPi (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 | Integer | Boundary crossing decision: – 0: No boundary
crossed.– 1: Lower efficacy boundary crossed.– 2: Upper efficacy boundary crossed.– 3:
Futility boundary crossed.– 4: Equivalence boundary
crossed (not available in East Horizon Explore).You should 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. |
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 | Numeric | Value of appropriate test statistic on Wald ﴾Z﴿ scale. |
| Delta | Numeric | Estimate of Delta. Required if
LookInfo$FutBdryScale = 2 or 3 (futility boundary scale is
Delta or conditional power). |
| CtrlCompleters | Numeric | Number of completers for control arm. Required if
LookInfo$FutBdryScale = 3 (futility boundary scale is
conditional power). Not available in East Horizon Explore. |
| TrmtCompleters | Numeric | Number of completers for treatment arm. Required if
LookInfo$FutBdryScale = 3 (futility boundary scale is
conditional power). Not available in East Horizon Explore. |
| CtrlPi | Numeric | Proportion for control arm. Required if
LookInfo$FutBdryScale = 3 (futility boundary scale is
conditional power). Not available in East Horizon Explore. |
| 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,
TestStatwill be used to check for efficacy. - If
LookInfo$FutBdryScale = 0(futility boundary scale is Z scale),TestStatwill be used to check for both efficacy and futility. - If
LookInfo$FutBdryScale = 2(futility boundary scale is Delta scale),TestStatwill be used to check for efficacy andDeltawill be used to check for futility. - If
LookInfo$FutBdryScale = 3(futility boundary scale is conditional power scale),TestStatwill be used to check for efficacy andDelta,CtrlCompleters,TrmtCompleters, andCtrlPiwill 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)
# This is an example using GetDecisionString and GetDecision.
# 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'.
# 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
strDecision <- CyneRgy::GetDecisionString( LookInfo, nLookIndex, nQtyOfLooks,
bIAEfficacyCondition = bIAEfficacyCheck,
bIAFutilityCondition = bIAFutilityCheck,
bFAEfficacyCondition = bFAEfficacyCheck )
nDecision <- CyneRgy::GetDecision( strDecision, DesignParam, LookInfo )
return( list ( Decision = as.integer( nDecision ), ErrorCode = as.integer( nError ) ) )
}Minimal Template for Option 2 (TestStat)
ComputeTestStat <- function( SimData, DesignParam, LookInfo = NULL, UserParam = NULL )
{
nError <- 0 # Error handling (no error)
dTestStatistic <- 0
dDelta <- 0 # Use if futility boundary scale is Delta or conditional power
dCtrlCompleters <- 0 # Use if futility boundary scale is conditional power
dTrmtCompleters <- 0 # Use if futility boundary scale is conditional power
dCtrlPi <- 0 # Use if futility boundary scale is conditional power
# Write the actual code here.
# Store the computed test statistic in dTestStatistic.
# Compute dDelta, dCtrlCompleters, dTrmtCompleters, dCtrlPi if needed.
return( list( TestStat = as.double( dTestStatistic ),
Delta = as.double( dDelta ), # Include if futility boundary scale is Delta or conditional power
CtrlCompleters = as.double( dCtrlCompleters ), # Include if futility boundary scale is conditional power
TrmtCompleters = as.double( dTrmtCompleters ), # Include if futility boundary scale is conditional power
CtrlPi = as.double( dCtrlPi ), # Include if futility boundary scale is conditional power
ErrorCode = as.integer( nError ) ) )
}