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
## |
#' @include f_simulation_multiarm.R
NULL
#' Get number of events for a multi-arm survival stage (internal)
#'
#' @title Internal: compute additional events for a stage in multi-arm survival simulation
#'
#' @description
#' Internal helper used by \code{getSimulationMultiArmSurvival} to compute the number
#' of events to schedule for the given stage. The function supports conditional
#' sample size reassessment when \code{conditionalPower} is specified and returns
#' a single numeric value representing new events for the specified stage.
#'
#' @param ... Currently unused; reserved for compatibility with user-supplied callbacks.
#' @param stage Integer stage index (1-based as used by callers). Note: the function
#' internally converts to 0-based (\code{stage <- stage - 1}) for calculations.
#' @param directionUpper Logical or \code{NA}; one-sided test direction.
#' @param conditionalPower Numeric target conditional power (or \code{NA} to use planned events).
#' @param conditionalCriticalValue Numeric vector of conditional critical values (indexed by stage \- 1).
#' @param plannedEvents Numeric vector of cumulative planned events per stage.
#' @param allocationRatioPlanned Numeric vector of allocation ratios (active : control) per stage.
#' @param selectedArms Logical matrix indicating selected arms per stage (rows = arms, cols = stages).
#' @param estimatedTheta Numeric hypothesized effect (hazard ratio) used instead of observed effects when provided.
#' @param thetaH0 Numeric null-hypothesis hazard ratio.
#' @param overallEffects Numeric matrix of observed overall effect estimates (rows = alternatives/arms, cols = stages).
#' @param minNumberOfEventsPerStage Numeric vector of minimum events allowed per stage.
#' @param maxNumberOfEventsPerStage Numeric vector of maximum events allowed per stage.
#'
#' @details
#' - If \code{conditionalPower} is \code{NA} the function returns the planned incremental
#' events for the stage: \code{plannedEvents[stage+1] - plannedEvents[stage]}.\cr
#' - Otherwise, if any arm is selected at the current stage the function computes a
#' standardized effect (\code{thetaStandardized}) using \code{overallEffects} or
#' \code{estimatedTheta} and applies the conditional power formula. If the conditional
#' critical value is very large (\> 8) the upper bound \code{maxNumberOfEventsPerStage}
#' for the next stage is returned. The result is clipped to the supplied min/max
#' event bounds.
#' - The function returns a single numeric value (new events for the stage). Callers
#' should ensure inputs are valid; this helper does not perform extensive argument checking.
#'
#' @return A single numeric value giving the number of new events to schedule for the stage.
#'
#' @examples
#' \dontrun{
#' # return planned increment when no conditional power is requested
#' .getSimulationSurvivalMultiArmStageEvents(
#' stage = 2,
#' directionUpper = TRUE,
#' conditionalPower = NA_real_,
#' conditionalCriticalValue = rep(NA_real_, 1),
#' plannedEvents = c(100, 200),
#' allocationRatioPlanned = c(1, 1),
#' selectedArms = matrix(TRUE, nrow = 3, ncol = 2),
#' thetaH0 = 1,
#' estimatedTheta = NA_real_,
#' overallEffects = matrix(1, nrow = 3, ncol = 2),
#' minNumberOfEventsPerStage = c(0, 50),
#' maxNumberOfEventsPerStage = c(0, 200)
#' )
#' }
#'
#' @keywords internal
#'
#' @noRd
#'
.getSimulationSurvivalMultiArmStageEvents <- function(
...,
stage,
directionUpper,
conditionalPower,
conditionalCriticalValue,
plannedEvents,
eventsOverStages,
allocationRatioPlanned,
selectedArms,
thetaH0,
estimatedTheta,
overallEffects,
minNumberOfEventsPerStage,
maxNumberOfEventsPerStage) {
stage <- stage - 1 # to be consistent with non-multiarm situation
gMax <- nrow(overallEffects)
if (!is.na(conditionalPower)) {
if (any(selectedArms[1:gMax, stage + 1], na.rm = TRUE)) {
if (is.na(estimatedTheta)) {
if (is.na(directionUpper) || isTRUE(directionUpper)) {
thetaStandardized <- log(max(
min(
overallEffects[selectedArms[1:gMax, stage + 1], stage],
na.rm = TRUE
),
thetaH0 * (1 + 1e-07)
) / thetaH0)
} else {
thetaStandardized <- log(min(
max(
overallEffects[selectedArms[1:gMax, stage + 1], stage],
na.rm = TRUE
),
thetaH0 * (1 - 1e-07)
) / thetaH0)
}
} else {
thetaStandardized <- log(min(
estimatedTheta,
thetaH0 * (1 + ifelse(is.na(directionUpper) || isTRUE(directionUpper), 1e-07, -1e-07))
) / thetaH0)
}
if (conditionalCriticalValue[stage] > 8) {
newEvents <- maxNumberOfEventsPerStage[stage + 1]
} else {
newEvents <- (1 + allocationRatioPlanned[stage])^2 /
allocationRatioPlanned[stage] *
(max(
0,
conditionalCriticalValue[stage] +
.getQNorm(conditionalPower),
na.rm = TRUE
))^2 /
thetaStandardized^2
newEvents <- min(
max(minNumberOfEventsPerStage[stage + 1], newEvents),
maxNumberOfEventsPerStage[stage + 1]
)
}
} else {
newEvents <- 0
}
} else {
newEvents <- plannedEvents[stage + 1] - plannedEvents[stage]
}
return(newEvents)
}
.getSimulationSurvivalMultiArmStageEventsBasic <- function(
...,
stage,
directionUpper,
conditionalPower,
conditionalCriticalValue,
plannedEvents,
eventsOverStages,
allocationRatioPlanned,
selectedArms,
thetaH0,
thetaH1,
overallEffects,
minNumberOfEventsPerStage,
maxNumberOfEventsPerStage) {
stage <- stage - 1 # to be consistent with non-multiarm situation
gMax <- nrow(overallEffects)
if (!is.na(conditionalPower)) {
if (any(selectedArms[1:gMax, stage + 1], na.rm = TRUE)) {
if (is.na(thetaH1)) {
if (is.na(directionUpper) || isTRUE(directionUpper)) {
thetaStandardized <- log(max(
min(
overallEffects[selectedArms[1:gMax, stage + 1], stage],
na.rm = TRUE
),
thetaH0 * (1 + 1e-07)
) / thetaH0)
} else {
thetaStandardized <- log(min(
max(
overallEffects[selectedArms[1:gMax, stage + 1], stage],
na.rm = TRUE
),
thetaH0 * (1 - 1e-07)
) / thetaH0)
}
} else {
thetaStandardized <- log(min(
thetaH1,
thetaH0 * (1 + ifelse(is.na(directionUpper) || isTRUE(directionUpper), 1e-07, -1e-07))
) / thetaH0)
}
if (conditionalCriticalValue[stage] > 8) {
newEvents <- maxNumberOfEventsPerStage[stage + 1]
} else {
newEvents <- (1 + allocationRatioPlanned[stage])^2 /
allocationRatioPlanned[stage] *
(max(
0,
conditionalCriticalValue[stage] +
.getQNorm(conditionalPower),
na.rm = TRUE
))^2 /
thetaStandardized^2
newEvents <- min(
max(minNumberOfEventsPerStage[stage + 1], newEvents),
maxNumberOfEventsPerStage[stage + 1]
)
}
} else {
newEvents <- 0
}
} else {
newEvents <- plannedEvents[stage + 1] - plannedEvents[stage]
}
return(newEvents)
}
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.