Nothing
## |
## | rpact: Confirmatory Adaptive Clinical Trial Design and Analysis
## | This file is part of the rpact R package.
## |
## | RPACT — Statistical Tools for Drug Development
## |
## | Authors: Gernot Wassmer, PhD, and Friedrich Pahlke, PhD
## | SPDX-FileCopyrightText: RPACT GmbH, Germany <info@rpact.com>
## | SPDX-License-Identifier: LGPL-3.0-only
## |
## | Licensed under the GNU Lesser General Public License, version 3.
## | License text: https://www.gnu.org/licenses/lgpl-3.0.html
## |
## | Package documentation: https://www.rpact.org
## | Resources and customer portal: https://connect.rpact.app
## | Consulting and services: https://www.rpact.com
## | Contact: info@rpact.com
## |
## Original contribution: Morten Dreher
#'
#' @title
#' Create an Optimal Conditional Error Design
#'
#' @description This function returns a design object which contains all
#' important parameters for the specification of the optimal conditional
#' error function.
#' The returned object is of class \code{TrialDesignOptimalConditionalError}
#' and can be passed to other package functions.
#'
#'
#' @details
#' The design object contains the information required to determine the
#' specific setting of the optimal conditional error function and can be
#' passed to other package functions.
#' From the given user specifications, the constant to achieve level
#' condition for control of the overall type I error rate as well as the
#' constants to ensure a non-increasing optimal CEF (if required) are
#' automatically calculated.
#'
#' @section Hypotheses and trial decisions:
#' The one-sided hypotheses are \eqn{H_0: \Delta \leq 0} versus
#' \eqn{H_1: \Delta > 0}. With a first-stage p-value \eqn{p_1}, stop for
#' efficacy if \eqn{p_1 \leq \alpha_1} and \eqn{\alpha_1 > 0}; stop for
#' futility if \eqn{p_1 > \alpha_0}. Futility is binding: continuing beyond
#' this boundary is not part of the calibrated design. In the continuation
#' region, reject at stage two if its p-value is no larger than
#' `getConditionalError()`. The second-stage p-value must be based on
#' the new, independent second-stage data, not the cumulative data.
#' Setting `efficacyBounds = 0` disables early efficacy and
#' `futilityBounds = 1` disables early futility.
#' Here, \eqn{\alpha_1} denotes `efficacyBounds` and \eqn{\alpha_0} denotes
#' `futilityBounds`; both are single interim cutoffs on the p-value scale.
#' The calibration satisfies
#' \deqn{\alpha = \alpha_1 + \int_{\alpha_1}^{\alpha_0} \alpha_2(p_1) \, dp_1.}
#' Target conditional power refers to a specified planning effect after
#' continuation; it is not the overall power returned by [getDesignCharacteristics()].
#'
#' @section Likelihood ratio distribution:
#' To calculate the optimal conditional error function, an assumption about
#' the true parameter under which the second-stage information is to be
#' minimised is required.
#' Various options are available and can be specified via the argument
#' \code{likelihoodRatioDistribution}:
#' \itemize{
#' \item \code{likelihoodRatioDistribution="fixed"}: calculates the likelihood
#' ratio for a fixed \eqn{\Delta}. The non-centrality parameter of the
#' likelihood ratio \eqn{\vartheta} is then computed as
#' \code{thetaLR}*\code{sqrt(firstStageInformation)} and the likelihood
#' ratio is calculated as:
#' \deqn{l(p_1) = e^{\Phi^{-1}(1-p_1)\vartheta - \vartheta^2/2}.} \code{thetaLR}
#' may also contain multiple elements, in which case a weighted likelihood ratio
#' is calculated for the given values. Unless positive weights that sum to 1 are
#' provided by the argument \code{weightsLR}, equal weights are assumed.
#' \item \code{likelihoodRatioDistribution="normal"}: calculates the likelihood ratio
#' for a normally distributed prior of \eqn{\vartheta} with mean
#' \code{thetaLR}*\code{sqrt(firstStageInformation)} (\eqn{\mu}) and standard
#' deviation \code{stDevLR}*\code{sqrt(firstStageInformation)} (\eqn{\sigma}).
#' The parameters \code{thetaLR} and \code{stDevLR} must be specified on the
#' mean difference scale.
#' \deqn{l(p_1) = (1+\sigma^2)^{-\frac{1}{2}}\cdot e^{-(\mu/\sigma)^2/2 + (\sigma\Phi^{-1}(1-p_1) + \mu/\sigma)^2 / (2\cdot (1+\sigma^2))}}
#' \item \code{likelihoodRatioDistribution="exp"}: calculates the likelihood
#' ratio for an exponentially distributed prior of \eqn{\vartheta} with
#' rate \code{kappaLR}*\code{sqrt(firstStageInformation)} (\eqn{\eta}).
#' The likelihood ratio is then calculated as:
#' \deqn{l(p_1) = \eta \cdot \sqrt{2\pi} \cdot e^{(\Phi^{-1}(1-p_1)-\eta)^2/2} \cdot \Phi(\Phi^{-1}(1-p_1)-\eta)}
#' \item \code{likelihoodRatioDistribution="unif"}:
#' calculates the likelihood ratio for a uniformly distributed prior of
#' \eqn{\vartheta} on the support \eqn{[0, \Delta\cdot\sqrt{I_1}]}, where
#' \eqn{\Delta} is specified as \code{maxThetaLR} and \eqn{I_1}
#' is the \code{firstStageInformation}.
#' \deqn{l(p_1) = \frac{\sqrt{2\pi}}{\Delta\cdot\sqrt{I_1}} \cdot e^{\Phi^{-1}(1-p_1)^2/2} \cdot (\Phi(\Delta\cdot\sqrt{I_1} - \Phi^{-1}(1-p_1))-p_1)}
#' \item \code{likelihoodRatioDistribution="maxlr"}:
#' the non-centrality parameter \eqn{\vartheta} is estimated from the data
#' and no additional parameters must be specified.
#' The likelihood ratio is estimated from the data as:
#' \deqn{l(p_1) = e^{max(0, \Phi^{-1}(1-p_1))^2/2}}
#' The maximum likelihood ratio is always restricted to effect sizes
#' \eqn{\vartheta \geq 0} (corresponding to \eqn{p_1 \leq 0.5}).
#' }
#'
#' @section Effect for conditional power:
#' For the treatment effect at which the target conditional power should be
#' achieved, either a fixed effect or an interim estimate can be used.
#' The planning effect `thetaH1` need not equal `thetaLR`: the former sets the
#' conditional power target, whereas the latter specifies the effect or mixture
#' under which expected second-stage information is minimised.
#' The usage of a fixed effect is indicated by setting \code{useInterimEstimate=FALSE},
#' in which case the fixed effect is provided by \code{thetaH1} on the mean difference scale.
#' For an interim estimate, specified by \code{useInterimEstimate=TRUE},
#' a lower cut-off for the interim estimate must be provided, by \code{minThetaH1}
#' on the mean difference scale.
#' In addition, an upper limit of the estimate may be analogously provided by
#' \code{maxThetaH1}. These effects may alternatively be specified on the
#' non-centrality parameter scale as
#' \code{nonCentralityParameterH1}, \code{minNonCentralityParameterH1}, and
#' \code{maxNonCentralityParameterH1}.
#'
#' @section Sample size and information:
#' The first-stage information of the trial design must be specified to allow for
#' calculations between the mean difference and non-centrality parameter scale.
#' It is provided to the design object via \code{firstStageInformation}. \cr
#' Listed below are some examples for the calculation between information (\eqn{I_1}) and sample size:
#' \itemize{
#' \item One-sample z-test with \eqn{n} total patients:
#' \eqn{I_1 = \frac{n}{\sigma^2}}, where \eqn{\sigma^2} is the variance of an individual observation
#'
#' \item Balanced two-sample z-test with \eqn{n_1} patients per group:
#' \eqn{I_1 = \frac{1}{2}\cdot\frac{n_1}{\sigma^2}}, where \eqn{\sigma^2} is the common variance
#'
#' \item General two-sample z-test with \eqn{n_1}, \eqn{n_2} patients per group:
#' \eqn{I_1 = 1/(\frac{\sigma_1^2}{n_1}+\frac{\sigma_2^2}{n_2})}, where \eqn{\sigma_1^2}, \eqn{\sigma_2^2} are the group-wise variances
#' }
#'
#' @section Monotonicity:
#' By default, the function Q (likelihood ratio divided by the squared effect)
#' is transformed to be non-increasing in the first-stage p-value. For constant
#' conditional power this yields a non-increasing conditional error function.
#' A conditional power callback combined with interim effect estimates and
#' information constraints can still produce a non-monotone conditional error
#' function; `enforceMonotonicity` does not guarantee monotonicity in that setting.
#' The necessary intervals and constants for the transformation are calculated by
#' an internal monotonisation routine.
#' Although not recommended for the operating characteristics of the design,
#' the transformation may be omitted by setting \code{enforceMonotonicity=FALSE}.
#'
#' @section Constraints:
#' In some applications, it may be feasible to restrict the optimal conditional
#' error function by a lower and/or upper limit.
#' These constraints can be directly implemented on the function by using the
#' arguments \code{minConditionalError} and \code{maxConditionalError}.
#' By default, \code{minConditionalError=0} and \code{maxConditionalError=1},
#' i.e., no constraints are applied.
#' The constraints may also be specified on the second-stage information via
#' \code{minInformationPerStage} and \code{maxInformationPerStage}.
#' If both \code{minConditionalError} and \code{maxInformationPerStage}
#' respectively \code{maxConditionalError} and \code{minInformationPerStage}
#' are provided, both constraints will be applied.
#' Set these constraints when creating the design, so that calibration accounts
#' for them. For fixed \eqn{\Delta_1} and conditional power \eqn{CP},
#' an upper information bound corresponds to the lower conditional error bound
#' \eqn{\Phi(\Phi^{-1}(CP) - \Delta_1 \sqrt{I_{2,\max}})}; a lower information
#' bound analogously corresponds to an upper conditional error bound.
#' Information bounds apply only when the trial continues: information is zero
#' after early stopping. They refer to additional stage-two information, not
#' cumulative information.
#' `minInformationPerStage` and `maxInformationPerStage` are scalar limits for
#' stage two only; they do not constrain `firstStageInformation`.
#' In the continuation region, conditional error cannot exceed the conditional power;
#' an upper bound above it has no additional effect. Before calibration, the integrated
#' lower and upper bounds are checked for compatibility with the overall alpha level.
#'
#' @section Level constant:
#' The level constant is determined by an internal root-finding routine.
#' It is identified using the \code{uniroot()} function and by default, the
#' interval between 0 and 10 is searched for the level constant.
#' In specific settings, the level constant may lie outside of this interval.
#' In such cases, the search interval can be changed by altering the
#' parameters \code{minLevelConstant} and \code{maxLevelConstant}. \cr
#' If inappropriate constraints to the optimal conditional error function are
#' provided via \code{minConditionalError} and \code{maxConditionalError}
#' or \code{minInformationPerStage} and \code{maxInformationPerStage}, it may
#' be impossible to find a level constant which exhausts the full alpha level.
#'
#' Numerical integration uses an adapted routine for piecewise constant functions
#' where applicable. Set `options(rpact.design.optimal.enforce.basic.integration = TRUE)`
#' to use standard adaptive integration for comparison.
#'
#' @section Generic functions:
#' The \code{print()} and \code{plot()} functions are available for objects
#' of class \code{TrialDesignOptimalConditionalError}.
#' For details, see \code{?print.TrialDesignOptimalConditionalError} and
#' \code{?plot.TrialDesignOptimalConditionalError}.
#'
#' @inheritParams param_alphaOCEF
#' @inheritParams param_efficacyBoundsOCEF
#' @inheritParams param_futilityBoundsOCEF
#' @inheritParams param_conditionalPowerOCEF
#' @inheritParams param_conditionalPowerFunctionOCEF
#' @inheritParams param_thetaH1OCEF
#' @inheritParams param_minThetaH1OCEF
#' @inheritParams param_maxThetaH1OCEF
#' @inheritParams param_likelihoodRatioDistributionOCEF
#' @inheritParams param_firstStageInformationOCEF
#' @inheritParams param_useInterimEstimateOCEF
#' @inheritParams param_minInformationPerStageOCEF
#' @inheritParams param_maxInformationPerStageOCEF
#' @inheritParams param_minConditionalErrorOCEF
#' @inheritParams param_maxConditionalErrorOCEF
#' @inheritParams param_minLevelConstantOCEF
#' @inheritParams param_maxLevelConstantOCEF
#' @inheritParams param_enforceMonotonicityOCEF
#' @param efficacyBoundsScale,futilityBoundsScale Scale of the interim boundaries.
#' Currently only `"pValue"` is supported. These are p-value cutoffs, not the
#' test-statistic boundaries used by conventional group sequential designs.
#' @param nonCentralityParameterH1 Fixed conditional-power effect on the
#' non-centrality scale; alternative to `thetaH1` when `useInterimEstimate = FALSE`.
#' @param minNonCentralityParameterH1,maxNonCentralityParameterH1 Lower and upper
#' limits for the interim effect on the non-centrality scale; alternatives to
#' `minThetaH1` and `maxThetaH1` when `useInterimEstimate = TRUE`.
#' Non-centrality equals the mean difference times `sqrt(firstStageInformation)`.
#' Mean-difference arguments take precedence when both scales are supplied.
#' The default upper limit is `Inf`.
#' @param ... Distribution parameters `thetaLR`, `weightsLR`, `stDevLR`,
#' `kappaLR`, and `maxThetaLR`, as described under Likelihood ratio distribution.
#'
#' @return An object of class \code{TrialDesignOptimalConditionalError},
#' which can be passed to `getConditionalError()`, `getStageInformation()`,
#' and [getDesignCharacteristics()].
#' This adaptive design is not interchangeable with a conventional `TrialDesign`.
#'
#' @template examples_get_design_optimal
#'
#' @noRd
#'
#' @template reference_optimal
#' @template reference_monotone
#' @template reference_optconerrf
#'
getDesignOptimalConditionalError <- function(
alpha,
efficacyBounds,
futilityBounds,
conditionalPower = NA_real_,
thetaH1 = NA_real_,
minThetaH1 = NA_real_,
maxThetaH1 = Inf,
useInterimEstimate = TRUE,
firstStageInformation,
likelihoodRatioDistribution,
minInformationPerStage = 0,
maxInformationPerStage = Inf,
minConditionalError = 0,
maxConditionalError = 1,
conditionalPowerFunction = NULL,
minLevelConstant = 0,
maxLevelConstant = 10,
enforceMonotonicity = TRUE,
efficacyBoundsScale = "pValue",
futilityBoundsScale = "pValue",
nonCentralityParameterH1 = NULL,
minNonCentralityParameterH1 = NULL,
maxNonCentralityParameterH1 = Inf,
...
) {
design <- TrialDesignOptimalConditionalError$new(
alpha = alpha,
efficacyBounds = efficacyBounds,
futilityBounds = futilityBounds,
conditionalPower = conditionalPower,
thetaH1 = thetaH1,
minThetaH1 = minThetaH1,
maxThetaH1 = maxThetaH1,
firstStageInformation = firstStageInformation,
useInterimEstimate = useInterimEstimate,
likelihoodRatioDistribution = likelihoodRatioDistribution,
minInformationPerStage = minInformationPerStage,
maxInformationPerStage = maxInformationPerStage,
minConditionalError = minConditionalError,
maxConditionalError = maxConditionalError,
conditionalPowerFunction = conditionalPowerFunction,
minLevelConstant = minLevelConstant,
maxLevelConstant = maxLevelConstant,
enforceMonotonicity = enforceMonotonicity,
efficacyBoundsScale = efficacyBoundsScale,
futilityBoundsScale = futilityBoundsScale,
nonCentralityParameterH1 = nonCentralityParameterH1,
minNonCentralityParameterH1 = minNonCentralityParameterH1,
maxNonCentralityParameterH1 = maxNonCentralityParameterH1,
...
)
suppliedArguments <- names(as.list(match.call(expand.dots = TRUE)))[-1]
for (parameterName in setdiff(names(formals(getDesignOptimalConditionalError)), suppliedArguments)) {
if (parameterName %in% design$.getVisibleFieldNames() &&
design$.getParameterType(parameterName) == C_PARAM_USER_DEFINED) {
design$.setParameterType(parameterName, C_PARAM_DEFAULT_VALUE)
}
}
return(design)
}
.getOptimalDesignExpectedInformation <- function(design, likelihoodRatioDistribution = NULL, ...) {
.assertIsOptimalDesign(design)
distribution <- if (is.null(likelihoodRatioDistribution)) design$likelihoodRatioDistribution else likelihoodRatioDistribution
if (identical(distribution, "maxlr")) {
stopIllegalArgument(
"Expected information requires a probability distribution; specify 'fixed', 'normal', 'exp', or 'unif'.",
parameter = "likelihoodRatioDistribution",
value = distribution,
constraint = "a probability distribution: fixed, normal, exp or unif",
functionName = ".getOptimalDesignExpectedInformation",
diagnosticId = "optimal.expected_information_requires_distribution"
)
}
# Integrate over a helper function from efficacyBounds to futilityBounds
return(
stats::integrate(
f = .getOptimalDesignExpectedInformationIntegrand,
lower = design$efficacyBounds,
upper = design$futilityBounds,
design = design,
likelihoodRatioDistribution = likelihoodRatioDistribution,
...
)$value
)
}
#'
#' @title
#' Calculate the Optimal Conditional Error
#'
#' @inheritParams param_pValueOCEF
#' @inheritParams param_designOCEF
#' @param stage Completed interim stage. Currently only `1` is supported.
#'
#' @details The optimal conditional error \eqn{\alpha_2} given a
#' first-stage p-value \eqn{p_1} is calculated as:
#' \deqn{\alpha_2(p_1)=\psi(-e^{c_0} \cdot \frac{\Delta_1^2}{l(p_1)}).}
#'
#' The level constant \eqn{c_0} as well as the specification of the effect
#' size \eqn{\Delta_1} and the likelihood ratio \eqn{l(p_1)}
#' must be contained in the \code{design} object (see \code{?getDesignOptimalConditionalError}).
#' Early stopping rules are supported, i.e., for \eqn{p_1 \leq \alpha_1}
#' with \eqn{\alpha_1 > 0}, the returned conditional error is 1 and for
#' \eqn{p_1 > \alpha_0}, the returned conditional error is 0.
#'
#' @return A numeric vector of conditional errors, one per first-stage p-value.
#'
#' @template reference_optimal
#' @template reference_monotone
#' @template reference_optconerrf
#'
#' @template examples_get_optimal_conditional_error
#'
#' @seealso `getDesignOptimalConditionalError()`
#'
#' @rdname getConditionalError
#'
#' @noRd
#'
getConditionalError <- function(design, pValue, stage = 1) {
.assertIsOptimalDesignStage(stage, supportedStage = 1, functionName = "getConditionalError")
.assertIsOptimalDesign(design)
.assertIsNumericVector(pValue, "pValue")
.assertIsInClosedInterval(pValue, "pValue", lower = 0, upper = 1)
return(vapply(pValue, .getOptimalDesignConditionalErrorValue, numeric(1), design = design))
}
.getOptimalDesignCharacteristics <- function(design, theta, ...) {
.warnInCaseOfUnknownArguments(functionName = "getDesignCharacteristics", ...)
if (missing(theta)) {
stopMissingArgument(
"Specify 'theta' to evaluate an optimal conditional error design.",
parameter = "theta", constraint = "finite treatment effects on the mean difference scale",
functionName = "getDesignCharacteristics"
)
}
.assertIsOptimalDesign(design)
.assertIsNumericVector(x = theta, argumentName = "theta")
if (any(!is.finite(theta))) {
stopIllegalArgument(
"'theta' must contain finite values.",
parameter = "theta",
value = theta,
constraint = "must contain finite values",
functionName = "getDesignCharacteristics"
)
}
nonCentralityParameters <- theta * base::sqrt(design$firstStageInformation)
# One value per entry in theta
firstStageFutility <- numeric(length(theta))
firstStageEfficacy <- numeric(length(theta))
overallReject <- numeric(length(theta))
for (i in seq_along(theta)) {
# Early decision probabilities
firstStageFutility[i] <- stats::pnorm(
stats::qnorm(1 - design$futilityBounds) - nonCentralityParameters[i]
)
firstStageEfficacy[i] <- 1 -
stats::pnorm(stats::qnorm(1 - design$efficacyBounds) - nonCentralityParameters[i])
# Calculate probability to reject at the second stage for the given effect
.getOptimalDesignStageRejectionIntegrand <- function(pValue) {
(1 -
stats::pnorm(
stats::qnorm(1 - getConditionalError(pValue = pValue, design = design)) -
sqrt(getStageInformation(pValue = pValue, design = design)) * theta[i]
)) *
exp(
qnorm(1 - pValue) *
nonCentralityParameters[i] -
nonCentralityParameters[i]^2 / 2
)
}
integral <- stats::integrate(f = .getOptimalDesignStageRejectionIntegrand,
lower = design$efficacyBounds, upper = design$futilityBounds)$value
overallReject[i] <- firstStageEfficacy[i] + integral
}
return(TrialDesignOptimalConditionalErrorCharacteristics$new(
design = design, theta = theta, overallReject = overallReject,
rejectPerStage = rbind(firstStageEfficacy, overallReject - firstStageEfficacy),
futilityPerStage = matrix(firstStageFutility, nrow = 1)
))
}
#'
#' @title
#' Calculate Stage Information for an Adaptive Design
#'
#' @description Calculate the additional information required after an interim
#' analysis, or its unconditional expectation, for an optimal conditional error design.
#'
#' @inheritParams param_designOCEF
#' @inheritParams param_pValueOCEF
#' @inheritParams param_likelihoodRatioDistributionExpectedOCEF
#' @param stage Target stage for which additional information is required.
#' Currently only `2` is supported; the interim p-value comes from stage one.
#' @param type `"conditional"` (default) for information given `pValue`, or
#' `"expected"` for the unconditional expected additional information.
#' @param ... Distribution parameters for `type = "expected"`: `thetaLR`,
#' `weightsLR`, `stDevLR`, `kappaLR`, and `maxThetaLR`, as applicable.
#' @return For `type = "conditional"`, a numeric vector with one information
#' value per p-value, including zero after early stopping. For `type = "expected"`,
#' a numeric scalar including zero information for trials stopped at stage one.
#' Neither result includes first-stage information. Designs using `"maxlr"`
#' require an explicit probability distribution for the expectation.
#'
#' @section Conditional information: The second-stage information \eqn{I_{2}} is calculated given a first-stage p-value \eqn{p_1} as:
#' \deqn{I_{2}(p_1) = \frac{(\Phi^{-1}(1-\alpha_2(p_1)) + \Phi^{-1}(CP))^2}{\Delta_1^2} = \frac{\nu(\alpha_2(p_1))}{\Delta_1^2},}
#' where
#' \itemize{
#' \item \eqn{\alpha_2(p_1)} is the conditional error function
#' \item \eqn{CP} is the target conditional power
#' \item \eqn{\Delta_1} is the assumed treatment effect (expressed as a mean difference).
#' }
#' The conditional error is calculated according to the specification provided in the \code{design} argument.
#' For p-values smaller or equal to the first-stage efficacy boundary as well
#' as p-values greater than the first-stage futility boundary,
#' the returned information is 0 (since the trial is ended early in both cases).
#' When `efficacyBounds = 0`, early efficacy stopping is disabled, including at a p-value of zero.
#'
#' @section Expected information:
#' The expected second-stage information is calculated as:
#' \deqn{\mathbb{E}(I_{2})=\int_{\alpha_1}^{\alpha_0}\frac{\nu(\alpha_2(p_1)) \cdot l(p_1)}{\Delta_1^2} dp_1,}
#' where
#' \itemize{
#' \item \eqn{\alpha_1, \alpha_0} are the first-stage efficacy and futility boundaries
#' \item \eqn{\alpha_2(p_1)} is the optimal conditional error calculated for \eqn{p_1}
#' \item \eqn{l(p_1)} is the "true" likelihood ratio under which to calculate the
#' expected sample size. This can be different from the likelihood ratio used
#' to calibrate the optimal conditional error function.
#' \item \eqn{\Delta_1} is the assumed treatment effect to power for, expressed as a
#' mean difference. It may depend on the interim data (i.e., \eqn{p_1}) in case
#' \code{useInterimEstimate = TRUE} was specified for the design object.
#' \item \eqn{\nu(\alpha_2(p_1)) = (\Phi^{-1}(1-\alpha_2(p_1))+\Phi^{-1}(CP))^2} is a
#' factor calculated for the specific assumptions about the optimal conditional
#' error function and the target conditional power \eqn{CP}.
#' }
#'
#' Add `design$firstStageInformation` to obtain expected total information.
#' This expectation is unconditional, not conditional on reaching stage two.
#' Changing the evaluation distribution here does not recalibrate the design.
#'
#' @template examples_get_stage_information
#'
#' @seealso `getDesignOptimalConditionalError()`, `getConditionalError()`,
#' [getFisherInformation()] for information at planned analyses of conventional designs.
#'
#' @template reference_optimal
#' @template reference_monotone
#' @template reference_optconerrf
#'
#' @noRd
#'
getStageInformation <- function(design, stage = 2, type = c("conditional", "expected"),
pValue = NULL, likelihoodRatioDistribution = NULL, ...) {
.assertIsOptimalDesign(design)
.assertIsOptimalDesignStage(stage, supportedStage = 2, functionName = "getStageInformation")
if (missing(type)) type <- "conditional"
.assertIsSingleCharacter(type, "type")
if (!type %in% c("conditional", "expected")) {
stopIllegalArgument(
"'type' must be conditional or expected.", parameter = "type", value = type,
constraint = "conditional or expected", functionName = "getStageInformation"
)
}
if (type == "expected") {
if (!is.null(pValue)) {
stopConflictingArguments(
"Expected stage information is unconditional; do not supply 'pValue'.",
parameter = "pValue", value = pValue, relatedParameter = "type", relatedValue = type,
constraint = "pValue must be NULL for type = expected", functionName = "getStageInformation"
)
}
return(.getOptimalDesignExpectedInformation(design, likelihoodRatioDistribution, ...))
}
if (!is.null(likelihoodRatioDistribution) || length(list(...)) > 0) {
stopConflictingArguments(
"Evaluation distribution arguments are only used for expected information.",
parameter = "likelihoodRatioDistribution", value = likelihoodRatioDistribution,
relatedParameter = "type", relatedValue = type,
constraint = "distribution arguments require type = expected", functionName = "getStageInformation"
)
}
if (is.null(pValue)) {
stopMissingArgument(
"Specify 'pValue' for conditional stage information.", parameter = "pValue",
constraint = "numeric p-values between 0 and 1", functionName = "getStageInformation"
)
}
.assertIsNumericVector(pValue, "pValue")
.assertIsInClosedInterval(pValue, "pValue", lower = 0, upper = 1)
return(vapply(pValue, .getOptimalDesignStageInformation, numeric(1), design = design))
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.