adestr

This package implements methods to evaluate the performance characteristics of various point and interval estimators for adaptive two-stage designs with prespecified sample-size recalculation rules. Further, it allows for evaluation of these estimators on real datasets, and it implements methods to calculate p-values.

Currently, it works for designs objects which were produced by the R-package adoptr, which calculates optimal design parameters adaptive two-stage designs.

An introductory vignette covering common usecases is given at https://jan-imbi.github.io/adestr/articles/Introduction.html.

This package comes suite of unit tests. The code of the test cases can be viewed here: https://github.com/jan-imbi/adestr/tree/master/tests/testthat. The authors assume no responsibility for the correctness of the code or results produced by its usage. Use at your own risk.

You may also be interested in the reference implementation looking at the https://github.com/jan-imbi/adestr/blob/master/R/reference_implementation.R. It uses the same notation as in our paper (doi.org/10.1002/sim.10020) and may therefore be easier to understand at first.

Installation

You can install the development version of adestr by typing

remotes::install_github("https://github.com/jan-imbi/adestr")

into your R console.

Small introductory example

Here is a quick example showing the capabilities of adestr. First, load adestr:

library(adestr)
#> Loading required package: adoptr

Then, you can evaluate the performance of an estimator like this:

evaluate_estimator(
 score = MSE(),
 estimator = SampleMean(),
 data_distribution = Normal(two_armed = TRUE),
 design = get_example_design(),
 mu = c(0, 0.3, 0.6),
 sigma = 1
)
#> Design:                               TwoStageDesign<n1=28;0.8<=x1<=2.3:n2=9-40>
#> Data Distribution:                                             Normal<two-armed>
#> Estimator:                                                           Sample mean
#> Assumed sigma:                                                                 1
#> Assumed mu:                                                          0.0 0.3 0.6
#> Results:
#>  Expectation:                                   -0.0352411  0.2816994  0.6355803
#>  Bias:                                       -0.03524110 -0.01830056  0.03558030
#>  Variance:                                      0.05558372 0.07330105 0.06590990
#>  MSE:                                           0.05682565 0.07363596 0.06717585

evaluate_estimator(
 score = MSE(),
 estimator = SampleMean(),
 data_distribution = Normal(two_armed = TRUE),
 design = get_example_design(),
 mu = seq(-0.7, 1.5, .05),
 sigma = 1
) |> 
  plot()

You can analyze a dataset like this:

set.seed(321)
dat <- data.frame(
 endpoint = c(rnorm(28, .2, 1), rnorm(28, 0, 1),
              rnorm(23, .2, 1), rnorm(23, 0, 1)),
 group = factor(rep(c("ctl", "trt", "ctl", "trt"),
                    c(28,28,23,23))),
 stage = rep(c(1L, 2L), c(56, 46))
)
analyze(
 data = dat,
 statistics = get_example_statistics(),
 data_distribution = Normal(two_armed = TRUE),
 sigma = 1,
 design = get_example_design()
)
#> Design:                               TwoStageDesign<n1=28;0.8<=x1<=2.3:n2=9-40>
#> Data Distribution:                                             Normal<two-armed>
#> Observed number of stages:                                                     2
#> Observed n1 (group 1)                                                         28
#> Observed n1 (group 2)                                                         28
#> Observed n1 (total)                                                           56
#> Z1                                                                          1.75
#> Interim decision:                                       continue to second stage
#> Calculated n2(Z1) (per group)                                           23.49151
#> Calculated c2(Z1)                                                           1.14
#> Observed n2 (group 1)                                                         23
#> Observed n2 (group 2)                                                         23
#> Observed n2 (in total)                                                        46
#> Z2                                                                          2.12
#> Final test decision:                                                 reject null
#> 
#> Stage 2 results:
#>  Sample mean:                                                          0.5389012
#>  Pseudo Rao-Blackwellized:                                             0.3632916
#>  Median unbiased (LR test ordering):                                   0.5069941
#>  Bias reduced MLE (iterations=1):                                      0.5253942
#>  SWCF ordering CI:                                       [0.06264641, 0.7429735]
#>  LR test ordering CI:                                       [0.2509094, 0.81829]
#>  SWCF ordering p-value:                                               0.01097483
#>  LR test ordering p-value:                                          6.653031e-05

Please refer to https://jan-imbi.github.io/adestr/articles/Introduction.html for a more detailed introduction.