CRAN ready

jan-imbi · Apr 3, 2023 · 9468012 · 9468012
1 parent b44bb83
commit 9468012
Show file tree

Hide file tree

Showing 14 changed files with 152 additions and 53 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,9 +1,8 @@
 Package: OptimalGoldstandardDesigns
 Type: Package
 Title: Design parameter optimization for gold-standard non-inferiority trials
-Version: 0.2.0
-Author: Jan Meis
-Maintainer: Jan Meis <meis@imbi.uni-heidelberg.de>
+Version: 1.0.0
+Authors@R: c(person("Jan", "Meis", role = c("aut", "cre"), email="meis@imbi.uni-heidelberg.de", comment = c(ORCID = "0000-0001-5407-7220")))
 Description: This package contains methods to calculate optimal design parameters
     for one- and two-stage three-arm group-sequential gold-standard
     non-inferiority trial designs
@@ -30,6 +29,7 @@ Suggests:
     future.apply
 Config/testthat/edition: 3
 RoxygenNote: 7.2.3
+Roxygen: list(markdown = TRUE)
 Collate: 
     'pmv_upper_smaller_slower_fix.R'
     'conditional_probability_functions.R'

diff --git a/R/conditional_probability_functions.R b/R/conditional_probability_functions.R
@@ -1,6 +1,6 @@
 #' Calculate the conditional mean of a multivariate normal distribution
 #'
-#' See e.g. chapter 8.1.2 in The Matrix Cookbook [1].
+#' See e.g. Chapter 8.1.2 in [The Matrix Cookbook](https://www.math.uwaterloo.ca/~hwolkowi/matrixcookbook.pdf).
 #'
 #' @template x_a
 #' @template mu_a
@@ -21,7 +21,7 @@ conditional_mean <- function(x_a, mu_a, mu_b, Sigma) {
 
 #' Calculate the conditional mean of a multivariate normal distribution
 #'
-#' See e.g. chapter 8.1.2 in The Matrix Cookbook [1].
+#' See e.g. Chapter 8.1.2 in [The Matrix Cookbook](https://www.math.uwaterloo.ca/~hwolkowi/matrixcookbook.pdf).
 #'
 #' @template x_a
 #' @template mu_a

diff --git a/R/global_constants.R b/R/global_constants.R
@@ -44,4 +44,4 @@ projection[["TP12_TC12"]] <- rbind(
   projection_components[[1]][["TC"]],
   projection_components[[2]][["TC"]]
 )
-.skip_slow_test <- TRUE
+# .skip_slow_test <- TRUE
diff --git a/R/optimization_methods.R b/R/optimization_methods.R
@@ -19,7 +19,7 @@
 #' @template varC
 #' @param binding_futility (logical) controls if futility boundaries are binding.
 #' @param always_both_futility_tests (logical) if true, both futility tests are performed after the first stage. If false,
-#' a 'completely sequential' testing procedure is employed (see Appendix of paper).
+#' a 'completely sequential' testing procedure is employed (see [Appendix of paper](https://doi.org/10.1002/sim.9630)).
 #' @template round_n
 #' @template lambda
 #' @template kappa
@@ -39,12 +39,9 @@
 #' @importFrom nloptr nloptr
 #' @importFrom mvtnorm Miwa
 #' @details
-#' TODO: Documentation is still work in progross...
-#'
 #' This function calculates optimal design parameters for a two-stage three-arm gold-standard
-#' non-inferiority trial. Run \code{vignette("mathematical_details", package = "OptimalGoldstandardDesigns")}
-#' to see details about the test statistics and testing procedure corresponding to this design.
-#'
+#' non-inferiority trial. Run \code{vignette("Introduction", package = "OptimalGoldstandardDesigns")}
+#' to see some examples related to the associated paper [(Meis et al., 2023)](https://doi.org/10.1002/sim.9630).
 #'
 #' Parameters which can be optimized are the allocation ratios for all groups and stages and the
 #' futility and efficacy boundaries of the first stage. The allocation ratios are
@@ -64,7 +61,11 @@
 #'
 #'
 #' The design is optimized with respect to the objective criterion given by the parameter
-#' \code{objective}. By default, ...
+#' \code{objective}. The default objective function is described in the
+#' Subsection *Optimizing group sequential gold-standard designs* in Section 2
+#' of [the associated paper](https://doi.org/10.1002/sim.9630). Additionally,
+#' this objective includes a term to penalize the maximum sample size of a trial,
+#' which can be controlled by the parameter `nu` (default is `nu=0`).
 #'
 #' Designs are calculated to fulfill the following constraints: the family-wise type I error
 #' rate is controlled at \code{alpha} under any combination of the two null hypotheses
@@ -83,7 +84,23 @@
 #'
 #'
 #' @examples
-#' D <- optimize_design_twostage(nloptr_opts = list(maxeval = 1, algorithm = "NLOPT_LN_SBPLX"))
+#' \dontrun{
+#' optimize_design_twostage(
+#'   beta = 0.2,
+#'   alternative_TP = 0.4,
+#'   alternative_TC = 0,
+#'   Delta = 0.2,
+#'   print_progress = FALSE,
+#'   binding_futility = TRUE,
+#'   lambda = .9,
+#'   kappa = 1
+#' )
+#' }
+#' @references
+#' Meis, J, Pilz, M, Herrmann, C, Bokelmann, B, Rauch, G, Kieser, M. Optimization of the two-stage group
+#' sequential three-arm gold-standard design for non-inferiority trials. *Statistics in Medicine.* 2023;
+#' 42(4): 536– 558. [doi:10.1002/sim.9630](https://doi.org/10.1002/sim.9630).
+#'
 optimize_design_twostage <-
   function(cT2   = NULL,
            cP1   = NULL,
@@ -404,11 +421,9 @@ optimize_design_twostage <-
 #' @export
 #' @importFrom nloptr nloptr
 #' @details
-#' TODO: Documentation is still work in progross...
-#'
 #' This function calculates optimal design parameters for a two-stage three-arm gold-standard
-#' non-inferiority trial. Run \code{vignette("mathematical_details", package = "OptimalGoldstandardDesigns")}
-#' to see details about the test statistics and testing procedure corresponding to this design.
+#' non-inferiority trial. Run \code{vignette("Introduction", package = "OptimalGoldstandardDesigns")}
+#' to see some examples related to the associated paper [(Meis et al., 2023)](https://doi.org/10.1002/sim.9630).
 #'
 #'
 #' Parameters which can be optimized are the allocation ratios for all groups and stages and the
@@ -429,7 +444,8 @@ optimize_design_twostage <-
 #'
 #'
 #' The design is optimized with respect to the objective criterion given by the parameter
-#' \code{objective}. By default, ...
+#' \code{objective}. By default, this is the overall sample size plus an optional
+#' penalty for the placebo group sample size, controlled by the parameter `kappa`.
 #'
 #' Designs are calculated to fulfill the following constraints: the family-wise type I error
 #' rate is controlled at \code{alpha} under any combination of the two null hypotheses
@@ -448,7 +464,17 @@ optimize_design_twostage <-
 #'
 #'
 #' @examples
-#' D <- optimize_design_twostage(nloptr_opts = list(maxeval = 1, algorithm = "NLOPT_LN_SBPLX"))
+#' \dontrun{
+#' optimize_design_onestage(
+#'   alpha = .025,
+#'   beta = .2,
+#'   alternative_TP = .4,
+#'   alternative_TC = 0,
+#'   Delta = .2,
+#'   print_progress = FALSE
+#' )
+#' }
+#'
 optimize_design_onestage <-
   function(cP1   = NULL,
            cC1   = NULL,

diff --git a/man/conditional_Sigma.Rd b/man/conditional_Sigma.Rd
diff --git a/man/conditional_mean.Rd b/man/conditional_mean.Rd
diff --git a/man/optimize_design_onestage.Rd b/man/optimize_design_onestage.Rd
diff --git a/man/optimize_design_twostage.Rd b/man/optimize_design_twostage.Rd
diff --git a/tests/testthat/test_design_helper_functions.R b/tests/testthat/test_design_helper_functions.R
@@ -55,7 +55,7 @@ test_that(
   "Covariance matrix calculation is correct and works as expected.",
   {
     skip_on_cran()
-    skip_if(.skip_slow_test, "Slow test skipped.")
+    # skip_if(.skip_slow_test, "Slow test skipped.")
     set.seed(123)
     D <- list()
     D$n <- list()

diff --git a/tests/testthat/test_design_twostage_binding.R b/tests/testthat/test_design_twostage_binding.R
@@ -1,5 +1,5 @@
 skip_on_cran()
-skip_if(.skip_slow_test, "Slow test skipped.")
+# skip_if(.skip_slow_test, "Slow test skipped.")
 D <- optimize_design_twostage(print_progress = FALSE,
                               binding_futility = TRUE)
 test_that(

diff --git a/tests/testthat/test_design_twostage_binding_sequential.R b/tests/testthat/test_design_twostage_binding_sequential.R
@@ -1,5 +1,5 @@
 skip_on_cran()
-skip_if(.skip_slow_test, "Slow test skipped.")
+# skip_if(.skip_slow_test, "Slow test skipped.")
 D <- optimize_design_twostage(
   always_both_futility_tests = FALSE,
   binding_futility = TRUE,

diff --git a/tests/testthat/test_design_twostage_nonbinding.R b/tests/testthat/test_design_twostage_nonbinding.R
@@ -1,5 +1,5 @@
 skip_on_cran()
-skip_if(.skip_slow_test, "Slow test skipped.")
+# skip_if(.skip_slow_test, "Slow test skipped.")
 D <- optimize_design_twostage(print_progress = FALSE)
 
 test_that(

diff --git a/tests/testthat/test_schloemer_comparison.R b/tests/testthat/test_schloemer_comparison.R
@@ -1,5 +1,5 @@
 skip_on_cran()
-skip_if(.skip_slow_test, "Slow test skipped.")
+# skip_if(.skip_slow_test, "Slow test skipped.")
 # Compare results with work from Patrick Schloemer
 library(mvtnorm)
 library(mnormt)