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] '3.5.1'

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))

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

Fisher’s combination test design, binding futility, one-sided overall significance level 2.5%, undefined endpoint.

Stage 1 2 3 4
Information rate 20% 50% 80% 100%
Efficacy boundary (p product scale) 0.01366638 0.00089215 0.00009643 0.00002151
Stage levels (one-sided) 0.0137 0.0137 0.0137 0.0137
Futility boundary (separate p-value scale) 0.400 0.400 0.400
Cumulative alpha spent 0.0137 0.0206 0.0237 0.0250
kable(summary(powerResults))

Power calculation for a continuous endpoint

Sequential analysis with a maximum of 4 looks (group sequential design), overall significance level 5% (one-sided). 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
Information rate 25% 50% 75% 100%
Efficacy boundary (z-value scale) 3.069 2.326 1.978 1.763
Overall power, alt. = 0 0.0011 0.0105 0.0282 0.0500
Overall power, alt. = 0.2 0.0050 0.0537 0.1431 0.2471
Overall power, alt. = 0.4 0.0189 0.1810 0.4137 0.6140
Overall power, alt. = 0.6 0.0571 0.4163 0.7370 0.8979
Overall power, alt. = 0.8 0.1394 0.6877 0.9317 0.9879
Overall 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
Cumulative alpha spent 0.0011 0.0105 0.0282 0.0500
One-sided local significance level 0.0011 0.0100 0.0240 0.0390
Efficacy boundary (t) 1.382 0.681 0.465 0.356
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:

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

Analysis results for a continuous endpoint

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

Stage 1 2 3 4
Fixed weight 0.25 0.5 0.75 1
Efficacy boundary (z-value scale) 3.069 2.326 1.978 1.763
Cumulative alpha spent 0.0011 0.0105 0.0282 0.0500
Stage level 0.0011 0.0100 0.0240 0.0390
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

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 3.5.1, R version 4.3.2 (2023-10-31 ucrt), platform: x86_64-w64-mingw32

To cite R in publications use:

R Core Team (2023). 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 3.5.1, https://www.rpact.com, https://github.com/rpact-com/rpact, https://rpact-com.github.io/rpact/, https://www.rpact.org.