Fix CRAN issues.

DESCRIPTION

@@ -1,17 +1,24 @@
 Package: adestr
 Type: Package
-Title: Adaptive Design Estimation in R
+Title: Estimation in optimal adaptive two-stage designs
 Version: 0.5.0
-Authors@R: c(person("Jan", "Meis", role = c("aut", "cre"), email="meis@imbi.uni-heidelberg.de", comment = c(ORCID = "0000-0001-5407-7220")))
+Authors@R:c(person("Jan", "Meis", role = c("aut", "cre"), email = "meis@imbi.uni-heidelberg.de", comment = c(ORCID = "0000-0001-5407-7220")),
+  person("Martin", "Maechler", role = c("cph"), email = "maechler@stat.math.ethz.ch", comment = c(ORCID = "0000-0002-8685-9910", "Original author of monoSpl.c (from the 'stats' package).")))
 Description:
   Methods to evaluate the performance characteristics of
   various point and interval estimators for optimal adaptive two-stage designs.
-  Specifically, this package is written to work with trial designs created by the adoptr package
+  Specifically, this package is written to work with trial designs created by the 'adoptr' package
   (Kunzmann et al. (2021) <doi:10.18637/jss.v098.i09>; Pilz et al. (2021) <doi:10.1002/sim.8953>)).
   Apart from the a priori evaluation of performance characteristics, this package also allows for the
   evaluation of the implemented estimators on real datasets, and it implements methods
   to calculate p-values.
-License: MIT + file LICENSE
+License: GPL (>= 2)
+Copyright:
+  This package contains a modified version of the monotonic spline functions from the
+  'stats' package. Specifically, the code is containted in the files R/fastmonoHFC.R,
+  src/fastmonoHFC.c, modreg.h and monoSpl.c. The R Core team and Martin Maechler 
+  are the copyright holders of the original code.
+  Jan Meis is the copyright holder of everything else.
 Encoding: UTF-8
 LazyData: true
 VignetteBuilder: knitr
@@ -60,5 +67,3 @@ Collate:
     'print.R'
 URL: https://jan-imbi.github.io/adestr/
 RdMacros: Rdpack
-
-

NAMESPACE

@@ -1,7 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method("[",EstimatorScoreResultList)
-S3method(format,EstimatorScoreResultList)
 export(AdaptivelyWeightedSampleMean)
 export(Bias)
 export(BiasReduced)
@@ -56,7 +54,6 @@ export(evaluate_scenarios_parallel)
 export(get_example_design)
 export(get_example_statistics)
 export(get_stagewise_estimators)
-export(get_statistics_from_paper)
 export(plot_p)
 exportClasses(EstimatorScore)
 exportClasses(IntervalEstimator)

R/analyze.R

@@ -26,7 +26,7 @@ Results <- setClass("Results", slots = c(data ="data.frame",
 #' \code{\link{PValue}}.
 #' @inheritParams evaluate_estimator
 #'
-#' @return \code{Results} object containing the values of the statistics
+#' @returns \code{Results} object containing the values of the statistics
 #' when applied to data.
 #' @export
 #'

R/estimators.R

@@ -14,6 +14,8 @@
 #'
 #'
 #' @param label name of the statistic. Used in printing methods.
+#' @returns An object of class \code{Statistic}. This class signals that
+#' an object can be supplied to the \code{\link{analyze}} function.
 #'
 #' @export
 #' @rdname Statistic-class
@@ -74,7 +76,9 @@ setClass("Estimator", contains = "Statistic")
 #' @param label name of the estimator. Used in printing methods.
 #' @seealso \code{\link{evaluate_estimator}}
 #'
-#' @return an object of class \code{PointEstimator}.
+#' @returns an object of class \code{PointEstimator}. This class signals that an
+#' object can be supplied to the \code{\link{evaluate_estimator}} and the
+#' \code{\link{analyze}} functions.
 #'
 #' @references
 #' \insertAllCited{}
@@ -101,7 +105,8 @@ VirtualPointEstimator <- function() stop("Cannot create instance of class Virtua
 #' @param label name of the p-value. Used in printing methods.
 #' @seealso [plot_p]
 #'
-#' @return An object of class \code{PValue}.
+#' @returns an object of class \code{PValue}. This class signals that an
+#' object can be supplied to the \code{\link{analyze}} function.
 #' @details
 #' The implemented p-values are:
 #' * \code{MLEOrderingPValue()}
@@ -152,7 +157,9 @@ VirtualPValue <- function() stop("Cannot create instance of class VirtualPValue.
 #' @param label name of the estimator. Used in printing methods.
 #' @seealso \code{\link{evaluate_estimator}}
 #'
-#' @return an object of class \code{IntervalEstimator}.
+#' @return an object of class \code{IntervalEstimator}. This class signals that an
+#' object can be supplied to the \code{\link{evaluate_estimator}} and the
+#' \code{\link{analyze}} functions.
 #'
 #' @export
 #' @aliases ConfidenceInterval ConfidenceInterval-class
@@ -206,7 +213,7 @@ VirtualIntervalEstimator <- function() stop("Cannot create instance of class Vir
 #'
 #' @inheritParams evaluate_estimator
 #'
-#' @return a list with the conditional functional representations
+#' @returns a list with the conditional functional representations
 #' (one for each stage where the trial might end) of the estimator or p-value.
 #' @export
 #'

R/evaluate_estimator.R

@@ -32,7 +32,8 @@
 #' @md
 #' @slot label name of the performance score. Used in printing methods.
 #'
-#' @return an \code{EstimatorScore} object.
+#' @returns an object of class \code{EstimatorScore}. This class signals that
+#' an object can be used with the \code{\link{evaluate_estimator}} function.
 #' @export
 #' @aliases EstimatorScore
 #' @seealso \code{\link{evaluate_estimator}}
@@ -132,7 +133,11 @@ setMethod("c", signature("EstimatorScoreResultList"), definition =
 #' @param early_efficacy_part include early efficacy part of integral.
 #' @param conditional_integral treat integral as a conditional integral.
 #'
-#' @return \code{EstimatorScoreResult} object containing the performance characteristics of the estimator.
+#' @return an object of class \code{EstimatorScoreResult}
+#' containing the values of the evaluated \code{\link{EstimatorScore}} and
+#' information about the setting for which they were calculated
+#' (e.g. the \code{estimator}, \code{data_distribution}, \code{design}, \code{mu}, and \code{sigma}).
+#'
 #' @seealso [EstimatorScore]
 #' @seealso [PointEstimator] [IntervalEstimator]
 #' @seealso \link[adestr:plot,EstimatorScoreResultList-method]{plot}
@@ -1021,7 +1026,7 @@ setMethod("evaluate_estimator", signature("Centrality", "PointEstimator"),
 #' @param early_efficacy_part_lists a list of lists of `early_efficacy_part_lists` parameters.
 #' @param conditional_integral_lists a list of lists of `conditional_integral_lists` parameters.
 #'
-#' @return list of data.frames containing the results for the respective scenarios.
+#' @returns a list of data.frames containing the results for the respective scenarios.
 #' @export
 #'
 #' @examples

R/fastmonoHFC.R

@@ -62,6 +62,7 @@ fastmonoH.FC_function <- function(x, y=NULL, ties = mean, extrapol = c("linear",
   dx <- x[-1L] - x[-nx]
   Sx <- dy/dx
   m <- c(Sx[1L], (Sx[-1L] + Sx[-n1])/2, Sx[n1])
+  browser()
   m <- .Call(MymonoFC_m, m, Sx, PACKAGE = "adestr")
   p0 <- y[-length(y)]
   p1 <- y[-1L]

R/helper_functions.R

@@ -106,7 +106,11 @@ get_overall_svar_twoarm <- function(smean1, smean1T, svar1, smean2, smean2T, sva
 #' two-armed trials.
 #' @param label (optional) label to be assigned to the design.
 #'
-#' @return an exmplary design of class \code{TwoStageDesign}.
+#' @returns an exemplary design of class \code{TwoStageDesign}. This object
+#' contains information about the sample size recalculation rule \code{n2}, the
+#' futility and efficacy boundaries \code{c1f} and \code{c1e} and the
+#' second-stage rejection boundary \code{c2}.
+#'
 #' @export
 #'
 #' @examples
@@ -170,11 +174,35 @@ get_example_design <- function(two_armed = FALSE, label = NULL) {
 }
 #' Generate a list of estimators and p-values to use in examples
 #'
+#' This function generates a list of objects of class \code{\link{PointEstimator}},
+#' \code{\link{IntervalEstimator}}s, and \code{\link{PValue}}s to use in
+#' examples of the \code{\link{analyze}} function.
+#'
+#' @details
+#' ## Point estimators
+#' The following \code{\link{PointEstimator}}s are included:
+#'  * \code{\link{SampleMean}}
+#'  * \code{\link{PseudoRaoBlackwell}}
+#'  * \code{\link{MedianUnbiasedLikelihoodRatioOrdering}}
+#'  * \code{\link{BiasReduced}}
+#'
+#' ## Confidence intervals
+#' The following \code{\link{IntervalEstimator}}s are included:
+#'  * \code{\link{StagewiseCombinationFunctionOrderingCI}}
+#'  * \code{\link{LikelihoodRatioOrderingCI}}
+#'
+#' ## P-Values
+#' The following \code{\link{PValue}}s are included:
+#'  * \code{\link{StagewiseCombinationFunctionOrderingPValue}}
+#'  * \code{\link{LikelihoodRatioOrderingPValue}}
+#' @md
+#'
 #' @param point_estimators logical indicating whether point estimators should be included in output list
 #' @param interval_estimators logical indicating whether interval estimators should be included in output list
 #' @param p_values logical indicating whether p-values should be included in output list
 #'
-#' @return a list of estimators and pvalues.
+#' @returns a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and
+#' \code{\link{PValue}}.
 #' @export
 #'
 #' @inherit analyze examples
@@ -194,14 +222,14 @@ get_example_statistics <- function(point_estimators = TRUE,
   return(ret)
 }
 
-#' Generate a list of estimators and p-values to use in examples
+#' Generate the list of estimators and p-values that were used in the paper
 #'
 #' @param point_estimators logical indicating whether point estimators should be included in output list
 #' @param interval_estimators logical indicating whether interval estimators should be included in output list
 #' @param p_values logical indicating whether p-values should be included in output list
 #'
-#' @return a list of estimators and pvalues.
-#' @export
+#' @returns a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and
+#' \code{\link{PValue}}.
 #'
 #' @inherit analyze examples
 get_statistics_from_paper <- function(point_estimators = TRUE,

R/plot.R

@@ -11,7 +11,7 @@
 #' @export
 #' @importFrom ggplot2 ggplot scale_x_continuous geom_line facet_wrap
 #' @importFrom latex2exp TeX
-#' @return a ggplot2 object visualizing the score values.
+#' @returns a \code{\link{ggplot2}} object visualizing the score values.
 #' @examples
 #' score_result1 <- evaluate_estimator(
 #'   MSE(),
@@ -89,7 +89,7 @@ setMethod("plot", signature = "list", definition =
 #' @param subdivisions number of subdivisions per axis for the grid of test statistic values.
 #' @param ... additional arguments handed down to ggplot
 #'
-#' @return a ggplot2 object visualizing the p-values on a grid of possible test-statistic values.
+#' @returns a \code{\link{ggplot2}} object visualizing the p-values on a grid of possible test-statistic values.
 #'
 #' @export
 #' @importFrom ggplot2 ggplot geom_tile geom_line geom_segment scale_color_manual scale_fill_gradient scale_x_continuous

R/print.R

@@ -250,10 +250,8 @@ setMethod("toTeX", signature("NeymanPearsonOrderingPValue"),
             str
           })
 
-#' @export
-format.EstimatorScoreResultList <- function(x, ...) rep("<EstimatorScoreResult>", length(x))
 
-#' @export
+format.EstimatorScoreResultList <- function(x, ...) rep("<EstimatorScoreResult>", length(x))
 `[.EstimatorScoreResultList` <- function(x, i){
   class(x) <- class(x)[class(x)!="EstimatorScoreResultList"]
   x <- x[i]

R/priors.R

@@ -11,7 +11,9 @@ setClass("NormalPrior", contains = "Prior", slots = c(mu = "numeric", sigma = "n
 #' @param mu mean of prior distribution.
 #' @param sigma standard deviation of the prior distribution.
 #'
-#' @return An object of class \code{NormalPrior}.
+#' @returns an object of class \code{NormalPrior}. This object can be supplied
+#' as the argument \code{mu} of the \code{\link{evaluate_estimator}} function
+#' to calculate performance scores weighted by a prior.
 #'
 #' @export
 #'
@@ -29,7 +31,9 @@ setClass("UniformPrior", contains = "Prior", slots = c(min = "numeric", max = "n
 #' @param min minimum of support interval.
 #' @param max maximum of support interval.
 #'
-#' @return An object of class \code{UniformPrior}.
+#' @returns an object of class \code{UniformPrior}. This object can be supplied
+#' as the argument \code{mu} of the \code{\link{evaluate_estimator}} function
+#' to calculate performance scores weighted by a prior.
 #'
 #' @export
 #'

R/reference_implementation.R

@@ -19,25 +19,19 @@
   x2 <- .z_to_x(z = z2, n = n2, mu0 = mu0, sigma = sigma)
   (n1 * x1 + n2 * x2) / (n1 + n2)
 }
-.n2_extrapol <- function(design, x1) {
+.n2_extrapol <- function(design, z1) {
   if (length(design@n2_pivots)>1){
-    h <- (design@c1e - design@c1f) / 2
-    return(stats::splinefun(
-      h * design@x1_norm_pivots + (h + design@c1f),
-      design@n2_pivots,
-      method = "monoH.FC"
-    )(x1))
+    z_interval_length <- design@c1e - design@c1f
+    z_trafo <- design@c1f + z_interval_length/2 * (1 + design@x1_norm_pivots)
+    return(stats::splinefun(z_trafo, design@n2_pivots, method = "monoH.FC")(z1))
   } else{
     return(design@n2_pivots)
   }
 }
-.c2_extrapol <- function(design, x1) {
-  h <- (design@c1e - design@c1f) / 2
-  return(stats::splinefun(
-    h * design@x1_norm_pivots + (h + design@c1f),
-    design@c2_pivots,
-    method = "monoH.FC"
-  )(x1))
+.c2_extrapol <- function(design, z1) {
+  z_interval_length <- design@c1e - design@c1f
+  z_trafo <- design@c1f + z_interval_length/2 * (1 + design@x1_norm_pivots)
+  return(stats::splinefun(z_trafo, design@c2_pivots, method = "monoH.FC")(z1))
 }
 
 ## The densities for integration.

R/twostagedesign_with_cache.R

@@ -65,6 +65,21 @@ setClass("Normal", contains = "DataDistribution")
 #' @param two_armed (logical) determines whether one or two-armed trials are assumed.
 #'
 #' @export
+#' @returns an object of class \code{Normal}. This object encodes the distributional
+#' assumptions of the data for usage in the functions
+#' \code{\link{evaluate_estimator}} and \code{\link{analyze}}.
+#' @examples
+#' evaluate_estimator(
+#'   score = MSE(),
+#'   estimator = SampleMean(),
+#'   data_distribution = Normal(FALSE),
+#'   design = get_example_design(),
+#'   mu = c(0, 0.3, 0.6),
+#'   sigma = 1,
+#'   exact = FALSE
+#' )
+#'
+#'
 Normal <- function(two_armed = TRUE) new("Normal", two_armed = two_armed)
 setClass("Student", contains = "DataDistribution")
 
@@ -76,8 +91,22 @@ setClass("Student", contains = "DataDistribution")
 #' under the assumption of known variance.
 #'
 #' @param two_armed (logical) determines whether one or two-armed trials are assumed.
+#' @returns an object of class \code{Student}. This object encodes the distributional
+#' assumptions of the data for usage in the functions
+#' \code{\link{evaluate_estimator}} and \code{\link{analyze}}.
 #'
 #' @export
+#' @examples
+#' evaluate_estimator(
+#'   score = MSE(),
+#'   estimator = SampleMean(),
+#'   data_distribution = Student(FALSE),
+#'   design = get_example_design(),
+#'   mu = c(0, 0.3, 0.6),
+#'   sigma = 1,
+#'   exact = FALSE
+#' )
+#'
 Student <- function(two_armed = TRUE) new("Student", two_armed = two_armed)
 n1 <- function(design, round = FALSE) if (round) round(design@n1) else design@n1
 ### end of remove ###