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
Published

February 16, 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.0.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

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

kable(summary(designFisher))
Warning in is.na(parameterValues): is.na() auf Nicht-(Liste oder Vektor) des
Typs 'environment' angewendet
object NA NA NA NA NA NA NA NA NA NA NA NA
equalAlpha 4 1 0.2 0.025 0.4 TRUE 1 0 0.0136664 0.0136664 0.0136664 FALSE
equalAlpha 4 2 0.5 0.025 0.4 TRUE 1 0 0.0205509 0.0008922 0.0136664 FALSE
equalAlpha 4 3 0.8 0.025 0.4 TRUE 1 0 0.0237206 0.0000964 0.0136664 FALSE
equalAlpha 4 4 1.0 0.025 NA TRUE 1 0 0.0250000 0.0000215 0.0136664 FALSE
kable(summary(powerResults))
Warning in is.na(parameterValues): is.na() auf Nicht-(Liste oder Vektor) des
Typs 'environment' angewendet
object NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA
1 0.0 FALSE 0 FALSE 1 2 1 TRUE 0.0 100 25 0.0500000 0.0010738 0.0282060 99.00483 1.3822841
1 0.2 FALSE 0 FALSE 1 2 1 TRUE 0.2 100 25 0.2470591 0.0050487 0.1431061 94.95447 1.3822841
1 0.4 FALSE 0 FALSE 1 2 1 TRUE 0.4 100 25 0.6139591 0.0189495 0.4136885 84.65788 1.3822841
1 0.6 FALSE 0 FALSE 1 2 1 TRUE 0.6 100 25 0.8979191 0.0571183 0.7370338 69.73819 1.3822841
1 0.8 FALSE 0 FALSE 1 2 1 TRUE 0.8 100 25 0.9878959 0.1394173 0.9317317 56.02829 1.3822841
1 1.0 FALSE 0 FALSE 1 2 1 TRUE 1.0 100 25 0.9994029 0.2787807 0.9904819 46.19160 1.3822841
2 0.0 FALSE 0 FALSE 1 2 1 TRUE 0.0 100 50 0.0500000 0.0094531 0.0282060 99.00483 0.6805418
2 0.2 FALSE 0 FALSE 1 2 1 TRUE 0.2 100 50 0.2470591 0.0486179 0.1431061 94.95447 0.6805418
2 0.4 FALSE 0 FALSE 1 2 1 TRUE 0.4 100 50 0.6139591 0.1620976 0.4136885 84.65788 0.6805418
2 0.6 FALSE 0 FALSE 1 2 1 TRUE 0.6 100 50 0.8979191 0.3592021 0.7370338 69.73819 0.6805418
2 0.8 FALSE 0 FALSE 1 2 1 TRUE 0.8 100 50 0.9878959 0.5483022 0.9317317 56.02829 0.6805418
2 1.0 FALSE 0 FALSE 1 2 1 TRUE 1.0 100 50 0.9994029 0.6042925 0.9904819 46.19160 0.6805418
3 0.0 FALSE 0 FALSE 1 2 1 TRUE 0.0 100 75 0.0500000 0.0176791 0.0282060 99.00483 0.4645319
3 0.2 FALSE 0 FALSE 1 2 1 TRUE 0.2 100 75 0.2470591 0.0894395 0.1431061 94.95447 0.4645319
3 0.4 FALSE 0 FALSE 1 2 1 TRUE 0.4 100 75 0.6139591 0.2326414 0.4136885 84.65788 0.4645319
3 0.6 FALSE 0 FALSE 1 2 1 TRUE 0.6 100 75 0.8979191 0.3207134 0.7370338 69.73819 0.4645319
3 0.8 FALSE 0 FALSE 1 2 1 TRUE 0.8 100 75 0.9878959 0.2440122 0.9317317 56.02829 0.4645319
3 1.0 FALSE 0 FALSE 1 2 1 TRUE 1.0 100 75 0.9994029 0.1074086 0.9904819 46.19160 0.4645319
4 0.0 FALSE 0 FALSE 1 2 1 TRUE 0.0 100 100 0.0500000 0.0217940 0.0282060 99.00483 0.3562713
4 0.2 FALSE 0 FALSE 1 2 1 TRUE 0.2 100 100 0.2470591 0.1039530 0.1431061 94.95447 0.3562713
4 0.4 FALSE 0 FALSE 1 2 1 TRUE 0.4 100 100 0.6139591 0.2002706 0.4136885 84.65788 0.3562713
4 0.6 FALSE 0 FALSE 1 2 1 TRUE 0.6 100 100 0.8979191 0.1608853 0.7370338 69.73819 0.3562713
4 0.8 FALSE 0 FALSE 1 2 1 TRUE 0.8 100 100 0.9878959 0.0561643 0.9317317 56.02829 0.3562713
4 1.0 FALSE 0 FALSE 1 2 1 TRUE 1.0 100 100 0.9994029 0.0089210 0.9904819 46.19160 0.3562713
kable(summary(analysisResults))
Warning in is.na(parameterValues): is.na() auf Nicht-(Liste oder Vektor) des
Typs 'environment' angewendet
object NA NA NA NA NA NA NA NA NA NA NA NA
FALSE TRUE TRUE 1.662998 continue 0.0028101 -1.386144 0.5861439 0.499999 NA NA NA NA
FALSE TRUE TRUE 1.662998 continue 0.0001227 -1.216028 0.4084087 0.499999 NA NA NA NA
FALSE TRUE TRUE 1.662998 continue 0.0000000 -1.676258 -0.3644440 0.499999 NA NA NA NA
FALSE TRUE TRUE 1.662998 accept NA -1.615872 -0.6022231 0.499999 0.9999205 -1.546886 -0.608249 -1.077568

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

as.data.frame(designGroupSequential)
  typeOfDesign kMax stages informationRates alpha beta twoSidedPower deltaWT
1           WT    4      1             0.25  0.05  0.2         FALSE     0.1
2           WT    4      2             0.50  0.05  0.2         FALSE     0.1
3           WT    4      3             0.75  0.05  0.2         FALSE     0.1
4           WT    4      4             1.00  0.05  0.2         FALSE     0.1
  sided  tolerance  alphaSpent criticalValues stageLevels
1     1 0.00000001 0.001073781       3.069028 0.001073781
2     1 0.00000001 0.010526914       2.325888 0.010012250
3     1 0.00000001 0.028205994       1.977663 0.023983344
4     1 0.00000001 0.050000000       1.762694 0.038976069
as.data.frame(dataset)
  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’

as.data.frame(designFisher, 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
as.data.frame(designCharacteristics, 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
as.data.frame(powerAndASN, 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

as.matrix(designGroupSequential)
 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 Two-sided power Delta (Wang & Tsiatis) Test Tolerance   
 "0.2"              "FALSE"         "0.1"                  "1"  "0.00000001"
 "0.2"              "FALSE"         "0.1"                  "1"  "0.00000001"
 "0.2"              "FALSE"         "0.1"                  "1"  "0.00000001"
 "0.2"              "FALSE"         "0.1"                  "1"  "0.00000001"
 Cumulative alpha spending Critical value Stage level  
 "0.001073781"             "3.069028"     "0.001073781"
 "0.010526914"             "2.325888"     "0.010012250"
 "0.028205994"             "1.977663"     "0.023983344"
 "0.050000000"             "1.762694"     "0.038976069"

System: rpact 4.0.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.0.0, https://www.rpact.com, https://github.com/rpact-com/rpact, https://rpact-com.github.io/rpact/, https://www.rpact.org.