R/f_comparison_adapters.R

Defines functions .expandComparisonSurvivalCategories .getComparisonSurvivalCategory .validateComparisonSurvivalDropoutDimensions .getComparisonSurvivalDropoutValues .getComparisonSpecialRCode .comparisonValueRCode .getComparisonCoordinateNames .getComparisonConditionalPowerData .getComparisonAdapterData .getComparisonAdapterContext .addComparisonContext .comparisonContextValue .getComparisonMetadataSources .getComparisonDesign .getComparisonAdapter

## |
## |  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
## |


.getComparisonAdapter <- function(object) {
    classes <- c("EventProbabilities", "NumberOfSubjects",
        "TrialDesignOptimalConditionalErrorCharacteristics", "ConditionalPowerResults",
        "PerformanceScore", "FisherInformation")
    for (className in classes) {
        if (inherits(object, className)) {
            return(className)
        }
    }
    return(NULL)
}

.getComparisonDesign <- function(object) {
    if (inherits(object, "PerformanceScore")) {
        return(object$.simulationResults$.design)
    }
    if (inherits(object, "FisherInformation")) {
        plan <- object$.getDesignPlan()
        if (!is.null(plan)) {
            return(plan$.design)
        }
        return(NULL)
    }
    if (inherits(object, "TrialDesignOptimalConditionalErrorCharacteristics")) {
        return(object$.design)
    }
    return(.getTrialDesign(object))
}

.getComparisonMetadataSources <- function(object) {
    sources <- list(object)
    design <- .getComparisonDesign(object)
    if (!is.null(design)) {
        sources <- c(sources, list(design))
    }
    if (inherits(object, "PerformanceScore")) {
        sources <- c(sources, list(object$.simulationResults))
    }
    if (inherits(object, "FisherInformation") && !is.null(object$.getDesignPlan())) {
        sources <- c(sources, list(object$.getDesignPlan()))
    }
    return(sources)
}

.comparisonContextValue <- function(value) {
    if (length(value) == 1L && is.atomic(value) && is.null(dim(value))) {
        return(value)
    }
    return(paste(capture.output(dput(value)), collapse = " "))
}

.addComparisonContext <- function(data, source, prefix = "", parameters = NULL) {
    if (is.null(source)) {
        return(data)
    }
    if (is.null(parameters)) {
        parameters <- c(source$.getUserDefinedParameters(), source$.getDefaultParameters())
    }
    for (parameter in intersect(parameters, names(source))) {
        if (source$isNotApplicableParameter(parameter)) {
            next
        }
        value <- source[[parameter]]
        name <- paste0(prefix, parameter)
        if (!name %in% names(data) && length(value) && is.atomic(value)) {
            data[[name]] <- rep(.comparisonContextValue(value), nrow(data))
        }
    }
    return(data)
}

.getComparisonAdapterContext <- function(object) {
    adapter <- .getComparisonAdapter(object)
    if (is.null(adapter)) {
        return(NULL)
    }
    target <- switch(adapter,
        EventProbabilities = "Event probability",
        NumberOfSubjects = "Recruitment",
        TrialDesignOptimalConditionalErrorCharacteristics = "Adaptive design characteristics",
        ConditionalPowerResults = "Conditional power",
        PerformanceScore = "Performance score",
        FisherInformation = "Fisher information"
    )
    endpoint <- if (adapter == "EventProbabilities") {
        "Survival"
    } else {
        "Undefined"
    }
    contextObject <- if (adapter == "PerformanceScore") {
        object$.simulationResults
    } else if (adapter == "FisherInformation") {
        object$.getDesignPlan()
    } else {
        object
    }
    if (!is.null(contextObject)) {
        for (endpointName in c("Means", "Rates", "Survival", "Count")) {
            if (grepl(endpointName, class(contextObject)[1L], fixed = TRUE)) {
                endpoint <- if (endpointName == "Count") {
                    "Counts"
                } else {
                    endpointName
                }
            }
        }
    }
    return(list(target = target, endpoint = endpoint))
}

.getComparisonAdapterData <- function(object, includeAllParameters = FALSE) {
    adapter <- .getComparisonAdapter(object)
    if (is.null(adapter)) {
        return(NULL)
    }
    if (adapter == "TrialDesignOptimalConditionalErrorCharacteristics") {
        n <- length(object$theta)
        data <- data.frame(stages = rep(1:2, each = n), theta = rep(object$theta, 2L),
            overallReject = rep(object$overallReject, 2L),
            rejectPerStage = as.vector(t(object$rejectPerStage)),
            futilityPerStage = c(as.vector(object$futilityPerStage), rep(NA_real_, n)))
        data <- .addComparisonContext(data, object$.design, prefix = "optimal_",
            parameters = object$.design$.getVisibleFieldNames())
        data$alpha <- rep(object$.design$alpha, nrow(data))
        data$kMax <- 2L
        return(data)
    }
    if (adapter == "FisherInformation") {
        data <- as.data.frame(object)
        names(data) <- c("stage", "situations", "information")
        data$type <- rep(object$type, nrow(data))
        plan <- object$.getDesignPlan()
        if (!is.null(plan)) {
            matrix <- as.matrix(object)
            for (parameter in intersect(c("alternative", "pi1", "lambda1", "hazardRatio", "theta"), names(plan))) {
                value <- plan[[parameter]]
                if (length(value) == ncol(matrix)) {
                    data[[parameter]] <- rep(value, each = nrow(matrix))
                }
            }
        }
        return(.addComparisonContext(data, plan))
    }
    if (adapter == "ConditionalPowerResults") {
        return(.getComparisonConditionalPowerData(object))
    }
    data <- as.data.frame(object, niceColumnNamesEnabled = FALSE,
        includeAllParameters = includeAllParameters)
    if (adapter == "PerformanceScore") {
        simulation <- object$.simulationResults
        alternative <- if (inherits(simulation, "SimulationResultsMeans")) {
            "alternative"
        } else {
            "pi1"
        }
        data[[alternative]] <- object$.alternative
        parameters <- setdiff(c(simulation$.getUserDefinedParameters(), simulation$.getDefaultParameters()), alternative)
        data <- .addComparisonContext(data, simulation, prefix = "simulation_", parameters = parameters)
        return(.addComparisonContext(data, simulation$.design, prefix = "design_",
            parameters = simulation$.design$.getVisibleFieldNames()))
    }
    if (adapter %in% c("EventProbabilities", "NumberOfSubjects")) {
        data <- .addComparisonContext(data, object, parameters = object$.getVisibleFieldNames())
    }
    return(data)
}

.getComparisonConditionalPowerData <- function(object) {
    kMax <- object$.design$kMax
    multi <- inherits(object, "ConditionalPowerResultsMultiHypotheses")
    gMax <- if (multi) {
        nrow(object$conditionalPower)
    } else {
        1L
    }
    data <- data.frame(stages = rep(seq_len(kMax), each = gMax))
    if (multi) {
        if (grepl("Enrichment", class(object)[1L], fixed = TRUE)) {
            populations <- c(paste0("S", seq_len(gMax - 1L)), "F")
            data$populations <- rep(populations, times = kMax)
        } else {
            data$treatmentArm <- rep(seq_len(gMax), times = kMax)
        }
    }
    for (parameter in object$.getVisibleFieldNames()) {
        value <- object[[parameter]]
        if (!is.atomic(value) || !length(value)) {
            next
        }
        if (is.matrix(value) && identical(dim(value), c(gMax, kMax))) {
            data[[parameter]] <- as.vector(value)
        } else if (length(value) == 1L) {
            data[[parameter]] <- rep(value, nrow(data))
        } else if (parameter %in% c("nPlanned", "allocationRatioPlanned") && length(value) == kMax) {
            data[[parameter]] <- rep(value, each = gMax)
        } else if (multi && length(value) == gMax && is.null(dim(value))) {
            data[[parameter]] <- rep(value, times = kMax)
        } else if (!multi && length(value) == kMax && is.null(dim(value))) {
            data[[parameter]] <- value
        } else {
            data[[parameter]] <- rep(.comparisonContextValue(value), nrow(data))
        }
    }
    stageResults <- object$.stageResults
    if (!is.null(stageResults)) {
        data$observedStage <- rep(stageResults$stage, nrow(data))
        data <- .addComparisonContext(data, stageResults, prefix = "observed_",
            parameters = stageResults$.getVisibleFieldNames())
        if (!is.null(stageResults$.dataInput)) {
            inputs <- as.data.frame(stageResults$.dataInput)
            for (parameter in names(inputs)) {
                data[[paste0("observedData_", parameter)]] <- rep(
                    .comparisonContextValue(inputs[[parameter]]), nrow(data))
            }
        }
    }
    return(data)
}

.getComparisonCoordinateNames <- function(data) {
    coordinates <- intersect(c("stages", "stage", "time", "treatmentArm", "populations", "situations",
        "categoryType", "category"), names(data))
    if ("categoryType" %in% coordinates) {
        coordinates <- unique(c(coordinates, intersect("situation", names(data))))
    }
    coordinates <- coordinates[vapply(data[coordinates], function(values) {
        return(any(!is.na(values)))
    }, logical(1))]
    return(coordinates)
}


.comparisonValueRCode <- function(value) {
    return(paste(capture.output(dput(value)), collapse = "\n"))
}

.getComparisonSpecialRCode <- function(object, leadingArguments, includeDefaultParameters,
        prefix, postfix, stringWrapPrefix, newArgumentValues, tolerance,
        pipeOperator, pipeOperatorPostfix, output, explicitPrint) {
    if (length(leadingArguments) || !is.list(newArgumentValues) || length(newArgumentValues)) {
        stopIllegalArgument("Comparison adapter reconstruction does not support argument overrides",
            functionName = "getObjectRCode", parameter = c("leadingArguments", "newArgumentValues"),
            value = list(leadingArguments = leadingArguments, newArgumentValues = newArgumentValues),
            constraint = "leadingArguments and newArgumentValues must be empty",
            diagnosticId = "comparison.adapter_r_code_overrides_unsupported",
            context = list(objectClass = class(object)[1L]))
    }
    if (inherits(object, "FisherInformation")) {
        plan <- object$.getDesignPlan()
        if (is.null(plan)) {
            # Standalone information objects have no source plan to recalculate.
            code <- paste0("getFromNamespace(\"FisherInformation\", \"rpact\")$new(",
                "information = ", .comparisonValueRCode(object$information),
                ", type = ", .comparisonValueRCode(object$type),
                ", stage = ", .comparisonValueRCode(object$stage),
                ", situations = ", .comparisonValueRCode(object$situations), ")")
        } else {
            planCode <- .getComparisonObjectRCode(plan, includeDefaultParameters, tolerance, pipeOperator)
            code <- paste0("getFisherInformation(", paste(planCode, collapse = "\n"),
                ", stage = ", .comparisonValueRCode(object$stage),
                ", type = ", .comparisonValueRCode(object$type), ")")
        }
    } else {
        design <- object$.design
        constructor <- getFromNamespace("getDesignOptimalConditionalError", "rpact")
        parameters <- design$.getUserDefinedParameters()
        if (includeDefaultParameters) {
            parameters <- c(parameters, design$.getDefaultParameters())
        }
        constructorParameters <- union(names(formals(constructor)),
            names(formals(TrialDesignOptimalConditionalError$public_methods$initialize)))
        parameters <- intersect(constructorParameters, parameters)
        arguments <- vapply(parameters, function(parameter) {
            return(paste0(parameter, " = ", .comparisonValueRCode(design[[parameter]])))
        }, character(1))
        code <- paste0("getFromNamespace(\".getOptimalDesignCharacteristics\", \"rpact\")(",
            "design = getFromNamespace(\"getDesignOptimalConditionalError\", \"rpact\")(",
            paste(arguments, collapse = ",\n"), "), theta = ", .comparisonValueRCode(object$theta), ")")
    }
    return(.formatRCode(paste0(prefix, code), precondition = character(),
        stringWrapParagraphWidth = NULL, postfix = postfix, stringWrapPrefix = stringWrapPrefix,
        pipeOperator = pipeOperator, pipeOperatorPostfix = pipeOperatorPostfix,
        output = output, explicitPrint = explicitPrint))
}

.getComparisonSurvivalDropoutValues <- function(object, parameter, situations) {
    arms <- object$activeArms
    values <- object[[parameter]]
    expectedRows <- if (endsWith(parameter, "2")) {
        1L
    } else {
        arms
    }
    # Current simulations retain stages; older result objects stored only
    # the finishing horizon per arm and situation.
    stageWise <- length(dim(values)) == 3L ||
        (expectedRows == 1L && is.matrix(values) && nrow(values) == object$.design$kMax)
    if (stageWise) {
        if (is.matrix(values)) {
            values <- array(values, dim = c(dim(values), 1L))
        }
        expected <- c(object$.design$kMax, situations, expectedRows)
        if (length(dim(values)) != 3L || !all(dim(values) == expected)) {
            stopIllegalDataInput("Unexpected dimensions for comparison drop-out parameter '", parameter, "'",
                functionName = ".getComparisonSurvivalDropoutValues", parameter = parameter, value = object[[parameter]],
                constraint = "stage by situation by arm array", diagnosticId = "comparison.dropout_dimensions_invalid",
                context = list(expectedDimensions = expected, actualDimensions = dim(values)))
        }
        return(values)
    }
    if (is.null(dim(values))) {
        values <- matrix(values, nrow = 1L)
    }
    if (!is.matrix(values) || nrow(values) != expectedRows || ncol(values) != situations) {
        stopIllegalDataInput("Unexpected dimensions for comparison drop-out parameter '", parameter, "'",
            functionName = ".getComparisonSurvivalDropoutValues", parameter = parameter, value = object[[parameter]],
            constraint = "arm by situation matrix, or a single-arm situation vector",
            diagnosticId = "comparison.dropout_dimensions_invalid",
            context = list(expectedDimensions = c(expectedRows, situations), actualDimensions = dim(values)))
    }
    return(values)
}


.validateComparisonSurvivalDropoutDimensions <- function(object, includeAllParameters = FALSE) {
    if (!inherits(object, "SimulationResultsMultiArmSurvival")) {
        return(invisible(NULL))
    }
    situations <- ncol(object$effectMatrix)
    groupFields <- grep("^(observedDropoutProportion|dropoutObservationTime)[12]$", names(object), value = TRUE)
    for (parameter in groupFields) {
        if (is.null(object[[parameter]]) || (!includeAllParameters && object$isNotApplicableParameter(parameter))) {
            next
        }
        .getComparisonSurvivalDropoutValues(object, parameter, situations)
    }
}

.getComparisonSurvivalCategory <- function(object, parameter) {
    if (!inherits(object, "SimulationResultsMultiArmSurvival")) {
        return(NULL)
    }
    if (parameter %in% c("singleEventsPerStage", "cumulativeEventsPerStage")) {
        return("comparison")
    }
    if (parameter %in% c("singleEventsPerArmAndStage", "selectedArms", "rejectedArmsPerStage",
            "lambdaTreatment", "medianTreatment", "effectMatrix") ||
            grepl("^(observedDropoutProportion|dropoutObservationTime)[12]$", parameter)) {
        return("arm")
    }
    inputs <- c(object$.getUserDefinedParameters(), object$.getDefaultParameters(),
        names(.getComparisonDesign(object)), .comparisonIdentifiers, .comparisonScope)
    if (parameter %in% names(object) && !parameter %in% inputs) {
        return("overall")
    }
    return(NULL)
}

.expandComparisonSurvivalCategories <- function(object, data, includeAllParameters = FALSE) {
    if (!inherits(object, "SimulationResultsMultiArmSurvival")) {
        return(data)
    }
    arms <- object$activeArms
    types <- c("overall", rep("comparison", arms), rep("arm", arms + 1L))
    categories <- c("All arms", paste("Treatment", seq_len(arms), "vs. Control"),
        paste("Treatment", seq_len(arms)), "Control")
    rowIndices <- rep(seq_len(nrow(data)), each = length(types))
    result <- data[rowIndices, , drop = FALSE]
    result$categoryType <- rep(types, nrow(data))
    result$category <- rep(categories, nrow(data))
    overall <- result$categoryType == "overall"
    # Inputs and design settings remain available for grouping on every row.
    # Scalar and stage-wise simulation results belong only to the overall rows.
    inputs <- c(object$.getUserDefinedParameters(), object$.getDefaultParameters(),
        names(.getComparisonDesign(object)), .comparisonIdentifiers, .comparisonScope)
    for (parameter in setdiff(intersect(names(result), names(object)), inputs)) {
        result[[parameter]][!overall] <- NA
    }
    groupFields <- grep("^(observedDropoutProportion|dropoutObservationTime)[12]$", names(object), value = TRUE)
    for (parameter in groupFields) {
        result[grep(paste0("^", parameter, "\\."), names(result), value = TRUE)] <- NULL
        values <- object[[parameter]]
        if (is.null(values) || (!includeAllParameters && object$isNotApplicableParameter(parameter))) {
            next
        }
        result[[parameter]] <- NA_real_
        values <- .getComparisonSurvivalDropoutValues(object, parameter, max(data$situation))
        if (length(dim(values)) == 3L) {
            for (g in seq_len(dim(values)[3L])) {
                category <- if (endsWith(parameter, "2")) {
                    "Control"
                } else {
                    paste("Treatment", g)
                }
                rows <- result$categoryType == "arm" & result$category == category
                result[[parameter]][rows] <- values[cbind(result$stages[rows], result$situation[rows], g)]
            }
            next
        }
        for (g in seq_len(nrow(values))) {
            category <- if (endsWith(parameter, "2")) {
                "Control"
            } else {
                paste("Treatment", g)
            }
            rows <- result$categoryType == "arm" & result$category == category
            result[[parameter]][rows] <- values[g, result$situation[rows]]
        }
    }
    arrayFields <- c("singleEventsPerStage", "cumulativeEventsPerStage",
        "singleEventsPerArmAndStage", "selectedArms", "rejectedArmsPerStage")
    for (parameter in arrayFields) {
        values <- object[[parameter]]
        if (is.null(values) || (!includeAllParameters && object$isNotApplicableParameter(parameter))) {
            next
        }
        comparison <- identical(.getComparisonSurvivalCategory(object, parameter), "comparison")
        groups <- if (parameter == "singleEventsPerArmAndStage") {
            arms + 1L
        } else {
            arms
        }
        expected <- c(object$.design$kMax, max(data$situation), groups)
        if (length(dim(values)) != 3L || !all(dim(values) == expected)) {
            stopIllegalDataInput("Unexpected dimensions for comparison array '", parameter, "'",
                functionName = ".expandComparisonSurvivalCategories", parameter = parameter, value = values,
                constraint = "stage by situation by category array", diagnosticId = "comparison.array_dimensions_invalid",
                context = list(expectedDimensions = expected, actualDimensions = dim(values)))
        }
        result[[parameter]] <- NA_real_
        for (g in seq_len(groups)) {
            category <- if (comparison) {
                paste("Treatment", g, "vs. Control")
            } else if (g > arms) {
                "Control"
            } else {
                paste("Treatment", g)
            }
            rows <- result$category == category
            result[[parameter]][rows] <- values[cbind(result$stages[rows], result$situation[rows], g)]
        }
    }
    for (parameter in intersect(c("lambdaTreatment", "medianTreatment", "effectMatrix"), names(result))) {
        values <- object[[parameter]]
        if (is.matrix(values) && nrow(values) == arms && ncol(values) == max(data$situation)) {
            result[[parameter]] <- NA_real_
            for (g in seq_len(arms)) {
                rows <- result$categoryType == "arm" & result$category == paste("Treatment", g)
                result[[parameter]][rows] <- values[g, result$situation[rows]]
            }
        }
    }
    rownames(result) <- NULL
    return(result)
}

Try the rpact package in your browser

Any scripts or data that you put into this service are public.

rpact documentation built on Nov. 17, 2026, 1:07 a.m.