How to use R Generics with rpact

Utilities
This document provides examples that illustrate the usage of R generic functions (short: R generics) with rpact, e.g., as.data.frame or summary.
Author

Friedrich Pahlke Gernot Wassmer

Published

September 26, 2024

Creating examples of selected rpact result objects

First, load the rpact package

library(rpact)
packageVersion("rpact") # version should be version 3.0 or later
[1] '4.1.0'

In the following we define different (typical) examples of rpact applications. The results are rpact objects which refer to examples for design specifications, power and sample size calculations, simulation results and the results of a data analysis with defined design and datasets.

designGroupSequential <- getDesignGroupSequential(
    alpha = 0.05, 
    kMax = 4,
    sided = 1, 
    typeOfDesign = "WT", 
    deltaWT = 0.1
)

designFisher <- getDesignFisher(
    kMax = 4, 
    alpha = 0.025,
    informationRates = c(0.2, 0.5, 0.8, 1), 
    alpha0Vec = rep(0.4, 3)
)

designCharacteristics <- getDesignCharacteristics(
    designGroupSequential
)

powerAndASN <- getPowerAndAverageSampleNumber(
    designGroupSequential, 
    theta = 0.5, 
    nMax = 40
)

sampleSizeResults <- getSampleSizeMeans(
  designGroupSequential
)

powerResults <- getPowerMeans(
    designGroupSequential, 
    maxNumberOfSubjects = 100
)

designSet <- getDesignSet(
    design = designGroupSequential, 
    deltaWT = c(0.3, 0.4)
)

dataset <- getDataset(
    n1 = c(22, 11, 22, 11),
    n2 = c(22, 13, 22, 13),
    means1 = c(1, 1.1, 1, 1),
    means2 = c(1.4, 1.5, 3, 2.5),
    stDevs1 = c(1, 2, 2, 1.3),
    stDevs2 = c(1, 2, 2, 1.3)
)

analysisResults <- getAnalysisResults(
  designGroupSequential, 
  dataset
)

How to use R generic functions with rpact objects

This section describes how the defined objects can be used and displayed. It is important to understand this is the way how typically R objects can be handled with. Particularly, we tried to make the summary() output (except for the technical developer summaries) “ready to use”, e.g., for a design report.

Get field names of the object

designGroupSequential |> names()
 [1] "kMax"                   "alpha"                  "stages"                
 [4] "informationRates"       "userAlphaSpending"      "criticalValues"        
 [7] "stageLevels"            "alphaSpent"             "bindingFutility"       
[10] "directionUpper"         "tolerance"              "typeOfDesign"          
[13] "beta"                   "deltaWT"                "deltaPT1"              
[16] "deltaPT0"               "futilityBounds"         "gammaA"                
[19] "gammaB"                 "optimizationCriterion"  "sided"                 
[22] "betaSpent"              "typeBetaSpending"       "userBetaSpending"      
[25] "power"                  "twoSidedPower"          "constantBoundsHP"      
[28] "betaAdjustment"         "delayedInformation"     "decisionCriticalValues"
[31] "reversalProbabilities"

Access data of a field

designGroupSequential$criticalValues
[1] 3.069028 2.325888 1.977663 1.762694
designGroupSequential[["criticalValues"]]
[1] 3.069028 2.325888 1.977663 1.762694

Show a summary of the object

designFisher |> summary()

Sequential analysis with a maximum of 4 looks (Fisher’s combination test design)

Constant levels design, binding futility, one-sided overall significance level 2.5%, undefined endpoint.

Stage 1 2 3 4
Fixed weight 1 1.225 1.225 1
Cumulative alpha spent 0.0137 0.0206 0.0237 0.0250
Stage levels (one-sided) 0.0137 0.0137 0.0137 0.0137
Efficacy boundary (p product scale) 0.01366638 0.00089215 0.00009643 0.00002151
Futility boundary (separate p-value scale) 0.4000 0.4000 0.4000 
powerResults |> summary()

Power calculation for a continuous endpoint

Sequential analysis with a maximum of 4 looks (group sequential design), one-sided overall significance level 5%. The results were calculated for a two-sample t-test, H0: mu(1) - mu(2) = 0, power directed towards larger values, H1: effect as specified, standard deviation = 1, maximum number of subjects = 100.

Stage 1 2 3 4
Planned information rate 25% 50% 75% 100%
Cumulative alpha spent 0.0011 0.0105 0.0282 0.0500
Stage levels (one-sided) 0.0011 0.0100 0.0240 0.0390
Efficacy boundary (z-value scale) 3.069 2.326 1.978 1.763
Efficacy boundary (t) 1.382 0.681 0.465 0.356
Cumulative power, alt. = 0 0.0011 0.0105 0.0282 0.0500
Cumulative power, alt. = 0.2 0.0050 0.0537 0.1431 0.2471
Cumulative power, alt. = 0.4 0.0189 0.1810 0.4137 0.6140
Cumulative power, alt. = 0.6 0.0571 0.4163 0.7370 0.8979
Cumulative power, alt. = 0.8 0.1394 0.6877 0.9317 0.9879
Cumulative power, alt. = 1 0.2788 0.8831 0.9905 0.9994
Number of subjects 25.0 50.0 75.0 100.0
Expected number of subjects under H1, alt. = 0 99.0
Expected number of subjects under H1, alt. = 0.2 95.0
Expected number of subjects under H1, alt. = 0.4 84.7
Expected number of subjects under H1, alt. = 0.6 69.7
Expected number of subjects under H1, alt. = 0.8 56.0
Expected number of subjects under H1, alt. = 1 46.2
Exit probability for efficacy (under H0) 0.0011 0.0095 0.0177
Exit probability for efficacy (under H1), alt. = 0 0.0011 0.0095 0.0177
Exit probability for efficacy (under H1), alt. = 0.2 0.0050 0.0486 0.0894
Exit probability for efficacy (under H1), alt. = 0.4 0.0189 0.1621 0.2326
Exit probability for efficacy (under H1), alt. = 0.6 0.0571 0.3592 0.3207
Exit probability for efficacy (under H1), alt. = 0.8 0.1394 0.5483 0.2440
Exit probability for efficacy (under H1), alt. = 1 0.2788 0.6043 0.1074

Legend:

  • (t): treatment effect scale
  • alt.: alternative
analysisResults |> summary()

Analysis results for a continuous endpoint

Sequential analysis with 4 looks (group sequential design), one-sided overall significance level 5%. The results were calculated using a two-sample t-test, equal variances option. H0: mu(1) - mu(2) = 0 against H1: mu(1) - mu(2) > 0.

Stage 1 2 3 4
Planned information rate 25% 50% 75% 100%
Cumulative alpha spent 0.0011 0.0105 0.0282 0.0500
Stage levels (one-sided) 0.0011 0.0100 0.0240 0.0390
Efficacy boundary (z-value scale) 3.069 2.326 1.978 1.763
Cumulative effect size -0.400 -0.404 -1.020 -1.109
Cumulative (pooled) standard deviation 1.000 1.404 1.735 1.663
Overall test statistic -1.327 -1.185 -3.111 -3.887
Overall p-value 0.9041 0.8799 0.9988 0.9999
Test action continue continue continue accept
Conditional rejection probability 0.0028 0.0001 0
90% repeated confidence interval [-1.386; 0.586] [-1.216; 0.408] [-1.676; -0.364] [-1.616; -0.602]
Repeated p-value >0.5 >0.5 >0.5 >0.5
Final p-value 0.9999
Final confidence interval [-1.547; -0.608]
Median unbiased estimate -1.078

Coerce object to data.frame: as.data.frame

designGroupSequential |> as.data.frame()
  typeOfDesign kMax stages informationRates alpha beta deltaWT futilityBounds
1           WT    4      1             0.25  0.05  0.2     0.1           -Inf
2           WT    4      2             0.50  0.05  0.2     0.1           -Inf
3           WT    4      3             0.75  0.05  0.2     0.1           -Inf
4           WT    4      4             1.00  0.05  0.2     0.1             NA
  bindingFutility sided  tolerance  alphaSpent criticalValues stageLevels
1           FALSE     1 0.00000001 0.001073781       3.069028 0.001073781
2           FALSE     1 0.00000001 0.010526914       2.325888 0.010012250
3           FALSE     1 0.00000001 0.028205994       1.977663 0.023983344
4           FALSE     1 0.00000001 0.050000000       1.762694 0.038976069
dataset |> as.data.frame()
  stages groups sampleSizes means stDevs overallSampleSizes overallMeans
1      1      1          22   1.0    1.0                 22     1.000000
2      1      2          22   1.4    1.0                 22     1.400000
3      2      1          11   1.1    2.0                 33     1.033333
4      2      2          13   1.5    2.0                 35     1.437143
5      3      1          22   1.0    2.0                 55     1.020000
6      3      2          22   3.0    2.0                 57     2.040351
7      4      1          11   1.0    1.3                 66     1.016667
8      4      2          13   2.5    1.3                 70     2.125714
  overallStDevs
1      1.000000
2      1.000000
3      1.381500
4      1.425418
5      1.639151
6      1.822857
7      1.578664
8      1.738706

Coerce object to data.frame: as.data.frame with argument ‘niceColumnNamesEnabled = TRUE’

designFisher |> as.data.frame(niceColumnNamesEnabled = TRUE)
      Method Maximum # stages Stage Information rate Significance level Alpha_0
1 equalAlpha                4     1              0.2              0.025     0.4
2 equalAlpha                4     2              0.5              0.025     0.4
3 equalAlpha                4     3              0.8              0.025     0.4
4 equalAlpha                4     4              1.0              0.025      NA
  Binding futility Test        Tolerance Cumulative alpha spending
1             TRUE    1 0.00000000000001                0.01366638
2             TRUE    1 0.00000000000001                0.02055086
3             TRUE    1 0.00000000000001                0.02372061
4             TRUE    1 0.00000000000001                0.02500000
  Critical value Stage level Non stochastic curtailment
1  0.01366637982  0.01366638                      FALSE
2  0.00089215382  0.01366638                      FALSE
3  0.00009643023  0.01366638                      FALSE
4  0.00002151406  0.01366638                      FALSE
designCharacteristics |> as.data.frame(niceColumnNamesEnabled = TRUE)
  Inflation factor Stage Information      Power Rejection probability under H1
1          1.04846     1    1.620541 0.03624538                     0.03624538
2          1.04846     2    3.241081 0.30264612                     0.26640074
3          1.04846     3    4.861622 0.60337036                     0.30072424
4          1.04846     4    6.482163 0.80000000                     0.19662964
  Futility probability under H1 Ratio expected vs fixed sample size under H1
1                             0                                    0.8014789
2                             0                                    0.8014789
3                             0                                    0.8014789
4                            NA                                    0.8014789
  Ratio expected vs fixed sample size under a value between H0 and H1
1                                                           0.9724133
2                                                           0.9724133
3                                                           0.9724133
4                                                           0.9724133
  Ratio expected vs fixed sample size under H0
1                                     1.038026
2                                     1.038026
3                                     1.038026
4                                     1.038026
powerAndASN |> as.data.frame(niceColumnNamesEnabled = TRUE)
  Stage Effect Average sample size (ASN)     Power Early stop Overall reject
1     1    0.5                   26.7863 0.9266075 0.06839003      0.9266075
2     2    0.5                   26.7863 0.9266075 0.39887080      0.9266075
3     3    0.5                   26.7863 0.9266075 0.31845861      0.9266075
4     4    0.5                   26.7863 0.9266075         NA      0.9266075
  Reject per stage  Overall futility Futility stop per stage
1       0.06839003 0.000000002898419      0.0000000009865876
2       0.39887080 0.000000002898419      0.0000000009758407
3       0.31845861 0.000000002898419      0.0000000009359906
4       0.14088808 0.000000002898419                      NA

Coerce object to matrix: as.matrix

designGroupSequential |> as.matrix()
 Stage Type of design Maximum # stages Information rate Significance level
 "1"   "WT"           "4"              "0.25"           "0.05"            
 "2"   "WT"           "4"              "0.50"           "0.05"            
 "3"   "WT"           "4"              "0.75"           "0.05"            
 "4"   "WT"           "4"              "1.00"           "0.05"            
 Type II error rate Delta (Wang & Tsiatis) Futility bound (non-binding)
 "0.2"              "0.1"                  "-Inf"                      
 "0.2"              "0.1"                  "-Inf"                      
 "0.2"              "0.1"                  "-Inf"                      
 "0.2"              "0.1"                  NA                          
 Binding futility Test Tolerance    Cumulative alpha spending Critical value
 "FALSE"          "1"  "0.00000001" "0.001073781"             "3.069028"    
 "FALSE"          "1"  "0.00000001" "0.010526914"             "2.325888"    
 "FALSE"          "1"  "0.00000001" "0.028205994"             "1.977663"    
 "FALSE"          "1"  "0.00000001" "0.050000000"             "1.762694"    
 Stage level  
 "0.001073781"
 "0.010012250"
 "0.023983344"
 "0.038976069"

System: rpact 4.1.0, R version 4.3.3 (2024-02-29 ucrt), platform: x86_64-w64-mingw32

To cite R in publications use:

R Core Team (2024). R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria. https://www.R-project.org/.

To cite package ‘rpact’ in publications use:

Wassmer G, Pahlke F (2024). rpact: Confirmatory Adaptive Clinical Trial Design and Analysis. R package version 4.1.0, https://www.rpact.com, https://github.com/rpact-com/rpact, https://rpact-com.github.io/rpact/, https://www.rpact.org.