Nothing
## |
## | rpact: Confirmatory Adaptive Clinical Trial Design and Analysis
## | This file is part of the rpact R package.
## |
## | RPACT <U+2014> 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 class_core_parameter_set.R
#' @include class_summary.R
#'
NULL
#'
#' @title
#' Compare Existing Trial Planning Objects
#'
#' @description
#' Creates a comparison of existing designs, design characteristics, sample size
#' or power plans, simulation results, and power/ASN results without recalculating
#' them. A single
#' comparison summary returns its underlying comparison.
#'
#' @param objects Optional objects, lists of objects, `TrialComparison` objects,
#' or `TrialComparisonSummary` objects.
#' NULL is treated as an empty list.
#' @param ... Designs, design characteristics, plans, simulations,
#' `PowerAndAverageSampleNumberResult`, `EventProbabilities`, `NumberOfSubjects`,
#' `ConditionalPowerResults` (including subclasses), `PerformanceScore`,
#' `FisherInformation`, or `TrialDesignOptimalConditionalErrorCharacteristics`
#' objects, lists thereof,
#' `TrialComparison` objects, or `TrialComparisonSummary` objects. Entries
#' from `...` precede entries from `objects`.
#'
#' @return An R6 `TrialComparison` inheriting from `ParameterSet`. For a single
#' `TrialComparisonSummary`, its underlying comparison is returned by reference;
#' otherwise a new collection is created.
#'
#' @details
#' The comparison retains references to its objects. Changes to an original
#' object are reflected in subsequent comparisons; no comparison data are cached.
#' `$getObjects()` and [getObjects()] return the named list of references. Replacing entries in
#' that returned list does not change the comparison. `length()` is the number
#' of objects and `names()` returns their supplied names (or `NULL`). Retrieve
#' contained objects using `comparison[[i]]`, `comparison[["name"]]` or
#' `comparison$name`. R6 members take precedence for `$`; use `[[` to retrieve
#' an object whose name coincides with a member such as `add`. Unknown names
#' return NULL. The [fetch.TrialComparison()]
#' method provides the same object access through `fetch(comparison, name)` or
#' `fetch(comparison, position)`.
#' A single summary can be unwrapped with `summaryObject |> getComparison()`,
#' returning exactly `summaryObject$object`. Changes to the returned collection
#' therefore affect that underlying comparison. In combinations or nested lists,
#' summaries contribute their underlying comparisons' current objects; a new
#' collection is created without changing the source collections. Summary display
#' settings are not transferred to the comparison.
#'
#' Lists and comparisons are recursively expanded in their original order.
#' Names on individual objects are retained; container names are discarded.
#' Supplied non-empty names must be unique across the expanded collection;
#' duplicate names raise an error. Unnamed entries and repeated references to
#' the same object are allowed. getComparison() creates an empty comparison.
#' Its data frame has zero rows and columns, and plotting requires
#' numeric data to be added first.
#'
#' `comparison$add(..., objects = NULL)` appends objects with the same input
#' rules and returns the comparison invisibly, supporting chaining. All new
#' entries are validated before the stored list is changed, including name
#' collisions with existing objects. Adding another
#' comparison copies its current list of references; subsequent additions to that
#' source comparison do not affect the target. Existing summary objects remain
#' snapshots; call `summary()` again after changing the collection.
#'
#' `comparison$delete(index)` removes one object by its positive integer position
#' or exact name and returns the comparison invisibly. Invalid
#' positions or unknown names raise an error without changing the collection.
#' Removing the last object leaves an empty comparison, which can be filled again.
#' Names and order of remaining objects are retained; positions are renumbered.
#' The S3 generics [add()] and [delete()] delegate to these methods and support
#' pipelines such as `comparison |> add(other) |> delete(1)`.
#' Shallow cloning shares the contained objects. `clone(deep = TRUE)` is unsupported.
#'
#' `print()` describes the collection and selected observed ranges. `summary()`
#' groups differences by object scope, inputs/design settings and results, with
#' equal profiles grouped by object number. Parameter provenance and native
#' dimensions determine the applicable profile coordinates. Repeated design
#' settings on arm/category rows are removed after exact consistency checks.
#' Genuine scalar parameters are compared independently of the number of rows;
#' dimensioned parameters retain their stage, group and scenario domains even
#' when their values happen to be equal. Constant numeric vector cells, such as
#' `1, 1`, are normalized to the corresponding scalar value. Missing values and
#' their positions participate in exact comparisons. No rounding or numerical
#' tolerance is used to decide whether profiles differ.
#'
#' For comparisons containing interim analyses, fixed plans' `nFixed`, `nFixed1`,
#' and `nFixed2` are harmonized to `numberOfSubjects`, `numberOfSubjects1`, and
#' `numberOfSubjects2`. The corresponding stored group sizes are included for
#' sequential plans. Comparisons of fixed plans alone retain the fixed names.
#' With `includeAllParameters = TRUE`, sequential plans' `nFixed` reference values
#' remain separate from their stage-wise sample sizes. Fixed survival plans also
#' use `cumulativeEventsPerStage` for `eventsFixed` when interim analyses occur
#' in the comparison; sequential plans retain their fixed-design event reference.
#'
#' Available sample-size expectations `expectedNumberOfSubjectsH1` and
#' `expectedEventsH1` use `expectedNumberOfSubjects` and `expectedNumberOfEvents`.
#' These expectations refer to each scenario's supplied alternative. Harmonization
#' does not change alternatives or stopping rules, combine H0/H0-H1 expectations,
#' or reinterpret simulation assumptions used for conditional power.
#' Conflicting non-missing target values remain in separate columns.
#' Power/ASN results from [getPowerAndAverageSampleNumber()] retain their generic
#' `theta`, `nMax`, and `averageSampleNumber` scales. Individual `theta` scenarios
#' retain their stage coordinates even in full exports. The comparison includes `nMax`
#' even when the compact source data frame omits it; no endpoint or conversion to
#' subjects or events is inferred. With column harmonization enabled, their
#' stage-wise `earlyStop` becomes `earlyStopPerStage`, `overallEarlyStop` becomes
#' `earlyStop`, and `overallFutility` becomes `futilityStop`. `calculatedPower`
#' merges into `overallReject` when the values agree. Original names remain
#' available with `harmonizeColumnNames = FALSE` in data frames and summaries.
#' Original objects are unchanged.
#'
#' Event probabilities and recruitment results retain their time coordinates and
#' assumptions. Conditional-power results retain planned stages, treatment arms
#' or populations, and observed stage and data context; no analysis is rerun.
#' Performance scores retain scenario alternatives, simulation inputs and design
#' settings. Fisher information retains selected stages, situations, the source
#' plan when available, and its cumulative or stage-wise type; these scales are
#' not harmonized. Profiles and plot groups respect time, arm, population and
#' situation coordinates.
#'
#' Console and Markdown output are bounded. Limits and display rounding do not
#' change the underlying data. [as.data.frame.TrialComparison()] returns the full
#' comparison table. [plot.TrialComparison()] selects axes only when unambiguous.
#' [getObjectRCode()] reconstructs the comparison and its contained objects;
#' executing generated simulation code reruns the corresponding simulations.
#'
#' @template return_object_trial_comparison
#' @template how_to_get_help_for_generics
#'
#' @seealso
#' [compare()], [add()], [delete()], [fetch.TrialComparison()], [getObjects()]
#'
#' @examples
#' asn <- getPowerAndAverageSampleNumber(getDesignGroupSequential(kMax = 2),
#' theta = c(0, 0.2), nMax = 100
#' )
#' getComparison(asn, asn)
#'
#' comparison <- getComparison(list(
#' fixed = getDesignFixed(), sequential = getDesignGroupSequential(kMax = 2)
#' ))
#' print(comparison)
#' comparisonSummary <- summary(comparison)
#' identical(comparisonSummary |> getComparison(), comparison)
#' head(as.data.frame(comparison))
#' withCharacteristics <- getComparison(
#' getDesignGroupSequential(kMax = 2),
#' getDesignCharacteristics(getDesignGroupSequential(kMax = 3))
#' )
#' combined <- getComparison(comparison, other = getDesignFixed(alpha = 0.05))
#' combined$add(list(getDesignFixed(alpha = 0.01)))
#' empty <- getComparison()
#' empty$add(getDesignFixed())
#' combined$delete(1)
#' combined$delete("sequential")
#' \dontrun{
#' plot(comparison,
#' xAxis = "objectNumber",
#' yAxis = "criticalValues",
#' plotLineEnabled = FALSE
#' )
#' }
#'
#' @export
#'
getComparison <- function(..., objects = NULL) {
arguments <- list(...)
if (!is.null(objects)) {
arguments <- c(arguments, list(objects))
}
if (length(arguments) == 1L && inherits(arguments[[1L]], "TrialComparisonSummary")) {
return(arguments[[1L]]$object)
}
return(TrialComparison$new(.collectComparisonObjects(arguments)))
}
#'
#' @title
#' Start or Extend a Trial Comparison
#'
#' @description
#' S3 generic for comparing existing trial planning objects. The `ParameterSet`
#' method creates a comparison or appends to an existing `TrialComparison`.
#'
#' @param x A supported trial planning object or a `TrialComparison`.
#' @param y A trial design, design characteristics, sample size or power plan,
#' simulation result, list of supported objects, or `TrialComparison` to add.
#' May be omitted to create a comparison containing only `x`.
#'
#' @return A `TrialComparison`. When `x` is already a comparison, it is modified
#' by reference if `y` is supplied. Without `y`, a new comparison is returned.
#'
#' @details
#' For supported `ParameterSet` objects, `compare(x, y)` calls
#' [getComparison()] with `x` and `y`. Supported classes are `TrialDesign`,
#' `TrialDesignCharacteristics`, `TrialDesignPlan`, `SimulationResults`,
#' `PowerAndAverageSampleNumberResult`, `EventProbabilities`, `NumberOfSubjects`,
#' `ConditionalPowerResults` (including subclasses), `PerformanceScore`,
#' `FisherInformation`, and `TrialDesignOptimalConditionalErrorCharacteristics`.
#' If `x` is a `TrialComparison`, it calls `x$add(y)` instead. The input
#' validation and collection rules of [getComparison()] apply in both cases.
#' Objects are retained by reference without recalculating them.
#'
#' @seealso
#' [getComparison()], [add()], [delete()], [fetch.TrialComparison()], [getObjects()]
#'
#' @examples
#' comp <- getDesignInverseNormal(kMax = 2) |>
#' compare(getSampleSizeMeans(alternative = 0.2)) |>
#' compare(getSampleSizeMeans(alternative = 0.59))
#' length(comp)
#'
#' @export
#'
compare <- function(x, y) {
UseMethod("compare")
}
#'
#' @title
#' Start or Extend a Trial Comparison
#'
#' @rdname compare
#'
#' @description
#' The `ParameterSet` method starts or extends a trial comparison.
#'
#' @export
#'
compare.ParameterSet <- function(x, y) {
if (missing(y)) {
return(getComparison(x))
}
if (inherits(x, "TrialComparison")) {
return(x$add(y))
}
return(getComparison(x, y))
}
#'
#' @title
#' Compare and Summarize Trial Planning Objects
#'
#' @description
#' Combines two operands with [getComparison()] and returns the summary of the
#' resulting comparison. Repeated use extends the summarized comparison.
#'
#' @param x,y Supported trial planning objects, their `SummaryFactory` summaries,
#' `TrialComparison` objects, or `TrialComparisonSummary` objects.
#'
#' @return A visible `TrialComparisonSummary`, as returned by
#' `summary(getComparison(x, y))` after unwrapping summary operands.
#'
#' @details
#' Summary operands contribute their underlying `object`. For `ParameterSet`
#' operands, the supported classes are those accepted by [getComparison()]:
#' designs, design characteristics, sample size or power plans, simulations, and
#' power/ASN results, event probabilities, recruitment results, conditional power,
#' performance scores, Fisher information, and optimal conditional-error
#' characteristics.
#' Existing comparisons contribute their contained objects in order, retaining
#' names and references. The operands' collection membership is not modified.
#' The validation and unique-name rules of [getComparison()] apply.
#'
#' The result can be assigned, extended with another `%vs%`, or passed directly
#' to [plot.TrialComparison()]. Chained operations do not print intermediate
#' summaries. Plot axes must still be specified when their selection is ambiguous.
#'
#' @seealso
#' [getComparison()], [compare()]
#'
#' @examples
#' comparison <- getSampleSizeMeans(alternative = 0.22, stDev = 0.5) %vs%
#' getSampleSizeMeans(alternative = 0.44, stDev = 1) %vs%
#' getSampleSizeMeans(alternative = 0.59, stDev = 1)
#' comparison
#'
#' comp1 <- getSampleSizeMeans(alternative = 0.22) %vs%
#' compare(getSampleSizeMeans(alternative = 0.44))
#' comp2 <- comp1 %vs% compare(getSampleSizeMeans(alternative = 0.59))
#' comp2
#' comp2 |> getComparison()
#'
#' \dontrun{
#' getSampleSizeMeans(alternative = 0.22, stDev = 0.5) %vs%
#' getSampleSizeMeans(alternative = 0.44, stDev = 1) %vs%
#' getSampleSizeMeans(alternative = 0.59, stDev = 1) |>
#' plot(
#' xAxis = "alternative",
#' yAxis = c("nFixed", "criticalValuesEffectScale"), category = "stDev"
#' )
#' }
#'
#' @rdname versus
#'
#' @export
#'
`%vs%` <- function(x, y) {
if (inherits(x, "SummaryFactory")) {
x <- x$object
}
if (inherits(y, "SummaryFactory")) {
y <- y$object
}
return(summary(getComparison(x, y)))
}
.collectComparisonObjects <- function(arguments, objects = NULL) {
if (!is.null(objects)) {
arguments <- c(arguments, list(objects))
}
result <- list()
for (i in seq_along(arguments)) {
object <- arguments[[i]]
if (inherits(object, "TrialComparisonSummary")) {
object <- object$object
}
if (inherits(object, "TrialComparison")) {
entries <- object$getObjects()
} else if (is.list(object) && !is.data.frame(object)) {
entries <- .collectComparisonObjects(object)
} else {
# Subsetting keeps an individual object's supplied name, including
# empty names. Container names do not rename its leaves.
entries <- arguments[i]
}
result <- c(result, entries)
}
return(result)
}
.assertComparisonObjectNames <- function(objects, functionName) {
objectNames <- names(objects)
suppliedNames <- objectNames[!is.na(objectNames) & nzchar(objectNames)]
duplicateNames <- unique(suppliedNames[duplicated(suppliedNames)])
if (length(duplicateNames) == 0) {
return(invisible())
}
stopConflictingArguments(
"Object names must be unique; duplicate names: ",
paste(.sQuote(duplicateNames), collapse = ", "), ".",
functionName = functionName,
parameter = "objects",
value = objectNames,
constraint = "non-empty, non-missing object names must be unique",
diagnosticId = "comparison.object_names_duplicated",
context = list(
duplicateNames = duplicateNames,
objectPositions = which(objectNames %in% duplicateNames)
)
)
}
.getTrialComparisonData <- function(
objects,
niceColumnNamesEnabled = FALSE,
includeAllParameters = FALSE,
harmonizeColumnNames = TRUE) {
.assertIsSingleLogical(niceColumnNamesEnabled, "niceColumnNamesEnabled")
.assertIsSingleLogical(includeAllParameters, "includeAllParameters")
.assertIsSingleLogical(harmonizeColumnNames, "harmonizeColumnNames")
if (!length(objects)) {
return(data.frame())
}
return(.getComparisonData(objects,
niceColumnNamesEnabled = niceColumnNamesEnabled,
includeAllParameters = includeAllParameters,
harmonizeColumnNames = harmonizeColumnNames
))
}
#'
#' @title
#' Get Objects from a Collection
#'
#' @description
#' S3 generic for retrieving the objects contained in a collection.
#' The `TrialComparison` method delegates to `$getObjects()`.
#'
#' @param x An object supporting a `getObjects()` method, such as a `TrialComparison`.
#' @param ... Further arguments. Currently unused for `TrialComparison`.
#'
#' @return For `TrialComparison`, the list of contained objects in their stored
#' order, retaining supplied names, or an empty list for an empty comparison.
#'
#' @details
#' The returned list contains references to the original R6 objects. Changing
#' a contained object affects subsequent comparisons. Replacing or removing
#' entries in the returned list does not change the comparison's membership;
#' use [add()] and [delete()] to modify the collection.
#'
#' @seealso
#' [getComparison()], [compare()]
#'
#' @examples
#' comparison <- getComparison(
#' fixed = getDesignFixed(),
#' sequential = getDesignGroupSequential(kMax = 2)
#' )
#' objects <- comparison |> getObjects()
#' names(objects)
#' identical(objects$fixed, comparison$fixed)
#'
#' @export
#'
getObjects <- function(x, ...) {
UseMethod("getObjects")
}
#'
#' @title
#' Get Objects from a Collection
#'
#' @description
#' The `TrialComparison` method returns the list of contained objects.
#'
#' @rdname getObjects
#'
#' @export
#'
getObjects.TrialComparison <- function(x, ...) {
.warnInCaseOfUnknownArguments(functionName = "getObjects.TrialComparison", ...)
return(x$getObjects())
}
#'
#' @title
#' Add Objects to a Collection
#'
#' @description
#' S3 generic for adding objects. The `TrialComparison` method
#' delegates to `$add()` and modifies the existing comparison by reference.
#'
#' @param x An object supporting an `add()` method, such as a `TrialComparison`.
#' @param ... For `TrialComparison`, designs, plans, simulations, lists or
#' comparisons to append. The optional named argument `objects` is appended
#' after the other arguments, with the same rules as [getComparison()].
#'
#' @return The modified comparison for `TrialComparison`.
#'
#' @seealso
#' [getComparison()], [delete()]
#'
#' @examples
#' comparison <- getComparison(fixed = getDesignFixed())
#' comparison |> add(sequential = getDesignGroupSequential(kMax = 2))
#' comparison |> add(objects = list(other = getDesignFixed(alpha = 0.05)))
#'
#' @export
#'
add <- function(x, ...) {
UseMethod("add")
}
#'
#' @title
#' Add Objects to a Collection
#'
#' @description
#' The `TrialComparison` method appends objects to the comparison.
#'
#' @rdname add
#'
#' @export
#'
add.TrialComparison <- function(x, ...) {
return(x$add(...))
}
#'
#' @title
#' Delete an Object from a Collection
#'
#' @description
#' S3 generic for removing objects. The `TrialComparison` method
#' delegates to `$delete()` and modifies the existing comparison by reference.
#'
#' @param x An object supporting a `delete()` method, such as a `TrialComparison`.
#' @param ... For `TrialComparison`, exactly one `index`, supplied by position
#' or name: a positive integer position or an exact object name.
#' Invalid selections leave the comparison
#' unchanged. Removing the last object leaves an empty comparison.
#'
#' @return The modified comparison for `TrialComparison`.
#'
#' @seealso
#' [getComparison()], [add()]
#'
#' @examples
#' comparison <- getComparison(
#' fixed = getDesignFixed(),
#' sequential = getDesignGroupSequential(kMax = 2)
#' )
#' comparison |> delete("fixed")
#' comparison |> delete(index = 1)
#' comparison |>
#' add(getDesignFixed()) |>
#' delete(1)
#'
#' @export
#'
delete <- function(x, ...) {
UseMethod("delete")
}
#'
#' @title
#' Delete an Object from a Collection
#'
#' @rdname delete
#'
#' @description
#' The `TrialComparison` method deletes one contained object by position or name.
#'
#' @export
#'
delete.TrialComparison <- function(x, ...) {
return(x$delete(...))
}
#'
#' @title
#' Trial Comparison
#'
#' @description
#' R6 container for existing trial planning objects, inheriting from
#' `ParameterSet`. Create instances using [getComparison()].
#'
#' @name TrialComparison
#'
#' @seealso
#' [getComparison()]
#'
NULL
TrialComparison <- R6::R6Class("TrialComparison",
inherit = ParameterSet,
public = list(
initialize = function(objects = list()) {
objects <- .collectComparisonObjects(list(objects))
.assertComparisonObjectNames(objects, functionName = "TrialComparison$initialize")
# Reuse the comparison validation, without storing a table.
.getTrialComparisonData(objects)
super$initialize()
private$.objects <- objects
},
getObjects = function() {
return(private$.objects)
},
add = function(..., objects = NULL) {
additions <- .collectComparisonObjects(list(...), objects)
if (!length(additions)) {
return(self)
}
combined <- c(private$.objects, additions)
# Validate the complete candidate before changing the stored list.
.assertComparisonObjectNames(combined, functionName = "TrialComparison$add")
.getTrialComparisonData(combined)
private$.objects <- combined
return(self)
},
delete = function(index) {
if (missing(index)) {
stopMissingArgument("Supply the name or position of the object to delete",
functionName = "TrialComparison$delete", parameter = "index",
constraint = "one object name or position", diagnosticId = "comparison.object_index_missing"
)
}
if (length(index) != 1L) {
stopArgumentLengthOutOfBounds("Supply exactly one object name or position",
functionName = "TrialComparison$delete", parameter = "index", value = index,
constraint = "exactly one index", expectedLength = 1L, actualLength = length(index),
diagnosticId = "comparison.object_index_length_invalid"
)
}
if (is.character(index) && !is.na(index) && nzchar(index)) {
position <- match(index, names(private$.objects))
if (is.na(position)) {
stopIllegalArgument("No object named '", index, "' exists in the comparison",
functionName = "TrialComparison$delete", parameter = "index", value = index,
constraint = "an exact name of a contained object",
diagnosticId = "comparison.object_name_unknown",
context = list(availableNames = names(private$.objects))
)
}
} else {
if (!is.numeric(index) || is.complex(index) || is.na(index) ||
!is.finite(index) || index != trunc(index)) {
stopIllegalArgument("The object index must be a non-empty name or an integer position",
functionName = "TrialComparison$delete", parameter = "index", value = index,
constraint = "one non-missing, non-empty character name or finite integer position",
diagnosticId = "comparison.object_index_invalid"
)
}
if (index < 1 || index > length(private$.objects)) {
stopIndexOutOfBounds("Object position is outside the comparison",
functionName = "TrialComparison$delete", parameter = "index", value = index, index = index,
constraint = "a position in [1, number of objects]",
lowerBound = 1L, upperBound = length(private$.objects),
diagnosticId = "comparison.object_index_out_of_bounds"
)
}
position <- index
}
remaining <- private$.objects[-position]
private$.objects <- if (length(remaining)) {
remaining
} else {
list()
}
return(self)
},
show = function(...) {
self$.show(..., consoleOutputEnabled = TRUE)
return(invisible(self))
},
.show = function(..., consoleOutputEnabled = FALSE) {
.showTrialComparison(self, ..., consoleOutputEnabled = consoleOutputEnabled)
return(invisible(self))
}
),
private = list(
.objects = NULL,
deep_clone = function(name, value) {
stopIllegalArgument("Deep cloning of TrialComparison is not supported; use clone(deep = FALSE)",
functionName = "TrialComparison$clone", parameter = "deep", value = TRUE,
constraint = "deep must be FALSE", diagnosticId = "comparison.deep_clone_unsupported"
)
}
)
)
#'
#' @title
#' Compare Existing Trial Planning Objects
#'
#' @description
#' `length()` returns the number of objects in the comparison.
#'
#' @rdname getComparison
#'
#' @param x A `TrialComparison`.
#'
#' @export
#'
length.TrialComparison <- function(x) {
return(length(x$getObjects()))
}
#'
#' @title
#' Compare Existing Trial Planning Objects
#'
#' @description
#' `names()` returns the supplied names of the comparison objects.
#'
#' @rdname getComparison
#'
#' @export
#'
names.TrialComparison <- function(x) {
return(names(x$getObjects()))
}
#'
#' @title
#' Access Objects in a Trial Comparison
#'
#' @description
#' Extracts a contained comparison object by name or position.
#'
#' @rdname extract.TrialComparison
#'
#' @param x A `TrialComparison`.
#' @param i A single object name or a positive integer position.
#' @param name An object name, supplied literally after `$`.
#' @param ... Further indices are not supported.
#' @param exact Whether character indices must match exactly, as for list `[[`.
#' `$` always matches exactly.
#'
#' @return The contained object by reference, or NULL for an unknown name.
#'
#' @details
#' Object names are unique. Numeric positions refer to the
#' stored object order. R6 members take precedence for `$`: `x$add` is the method
#' even when an object is named "add"; use `x[["add"]]` to select that object.
#' `[[` selects contained objects first and falls back to existing R6 members for
#' other character names. This also preserves existing internal field access.
#' These methods provide extraction; replacing collection entries is not supported.
#' Use [getComparison()] or `$add()` to build or extend the collection.
#'
#' @examples
#' comparison <- getComparison(
#' fixed = getDesignFixed(),
#' sequential = getDesignGroupSequential(kMax = 2)
#' )
#' identical(comparison$fixed, comparison[["fixed"]])
#' identical(comparison[[1]], comparison$fixed)
#'
#' @export
#'
`[[.TrialComparison` <- function(x, i, ..., exact = TRUE) {
if (missing(i)) {
stopMissingArgument("An object name or position must be supplied",
functionName = "[[.TrialComparison", parameter = "i",
constraint = "one object name or position", diagnosticId = "comparison.object_index_missing"
)
}
extra <- list(...)
if (length(extra)) {
stopIllegalArgument("Only one object index is supported",
functionName = "[[.TrialComparison", parameter = "...", value = extra,
constraint = "no additional indices", diagnosticId = "comparison.multiple_indices_unsupported"
)
}
.assertIsSingleLogical(exact, "exact")
if (length(i) != 1L) {
stopArgumentLengthOutOfBounds("Supply exactly one object name or position",
functionName = "[[.TrialComparison", parameter = "i", value = i,
constraint = "exactly one index", expectedLength = 1L, actualLength = length(i),
diagnosticId = "comparison.object_index_length_invalid"
)
}
objects <- .subset2(x, "getObjects")()
if (is.character(i)) {
if (!is.na(i) && nzchar(i) && i %in% names(objects)) {
return(objects[[i, exact = TRUE]])
}
if (!is.na(i) && nzchar(i) && exists(i, envir = x, inherits = FALSE)) {
return(.subset2(x, i))
}
return(objects[[i, exact = exact]])
}
if (!is.numeric(i) || is.complex(i) || is.na(i) || !is.finite(i) || i != trunc(i)) {
stopIllegalArgument("The object index must be a name or an integer position",
functionName = "[[.TrialComparison", parameter = "i", value = i,
constraint = "one character name or finite integer position",
diagnosticId = "comparison.object_index_invalid"
)
}
if (i < 1 || i > length(objects)) {
stopIndexOutOfBounds("Object position is outside the comparison",
functionName = "[[.TrialComparison", parameter = "i", value = i, index = i,
constraint = "a position in [1, number of objects]", lowerBound = 1L, upperBound = length(objects),
diagnosticId = "comparison.object_index_out_of_bounds"
)
}
objects[[i]]
}
#'
#' @title
#' Access Objects in a Trial Comparison
#'
#' @description
#' `$` accesses named comparison objects while preserving public R6 members.
#'
#' @rdname extract.TrialComparison
#'
#' @export
#'
`$.TrialComparison` <- function(x, name) {
# Resolve actual bindings without dispatch, keeping R6 methods and fields safe.
if (exists(name, envir = x, inherits = FALSE)) {
return(.subset2(x, name))
}
.subset2(x, "getObjects")()[[name, exact = TRUE]]
}
#'
#' @title
#' Fetch Objects from a Trial Comparison
#'
#' @description
#' Extracts contained objects by name or position without modifying the comparison
#' or copying its objects. A single selection returns the object itself by default.
#'
#' @param x A `TrialComparison`.
#' @param ... Object names or integer positions, including vectors and multiple
#' selections. Names may be quoted or unquoted. Positive positions count from
#' the beginning and negative positions from the end. With no selection, the
#' last object is returned. Quasi-quotation and programmatic selectors are
#' supported; an unquoted name matching a contained object takes precedence
#' over a variable of the same name in the calling environment.
#' @param output One of "value" (default), "named", "labeled", or "list".
#' "value" returns a single selected object directly and multiple selections
#' as a named list. The other modes always return a named list. Collection
#' labels are the supplied object names, with positions for unnamed objects;
#' consequently "labeled" and "named" are equivalent for comparisons.
#'
#' @return A contained object by reference or a list of objects. An unknown name
#' returns NULL (retained as a NULL entry in list output).
#' Empty selector vectors return an empty list.
#'
#' @details
#' `fetch(x, "fixed")`, `fetch(x, fixed)` and `fetch(x, 1)` provide the named and
#' positional object access supported by `[[`. Only contained objects are selected;
#' R6 members are never returned as a fallback. Numeric positions must be finite,
#' nonzero integers within the collection bounds. Selecting the last object of
#' an empty comparison raises an index error.
#'
#' @seealso
#' [fetch()] and [getComparison()].
#'
#' @examples
#' comparison <- getComparison(
#' fixed = getDesignFixed(),
#' sequential = getDesignGroupSequential(kMax = 2)
#' )
#' identical(comparison |> fetch("fixed"), comparison[["fixed"]])
#' identical(comparison |> fetch(fixed), comparison$fixed)
#' identical(comparison |> fetch(1), comparison[[1]])
#' comparison |> fetch(-1)
#' comparison |> fetch(1:2, output = "list")
#'
#' @export
#'
fetch.TrialComparison <- function(x, ..., output = c("value", "named", "labeled", "list")) {
output <- match.arg(output)
selectors <- rlang::enquos(...)
if (!length(selectors)) {
selectors <- list(rlang::new_quosure(-1L))
}
objects <- x$getObjects()
objectNames <- names(objects)
positions <- list()
labels <- list()
for (i in seq_along(selectors)) {
selector <- selectors[[i]]
expression <- rlang::quo_get_expr(selector)
if (is.symbol(expression) && (as.character(expression) %in% objectNames ||
!rlang::env_has(rlang::quo_get_env(selector), as.character(expression), inherit = TRUE))) {
value <- as.character(expression)
} else {
value <- rlang::eval_tidy(selector)
}
index <- .getComparisonFetchPositions(value, objects, selectorNumber = i)
label <- if (is.character(value)) {
value
} else {
if (is.null(objectNames)) {
as.character(index)
} else {
objectNames[index]
}
}
unnamed <- is.na(label) | !nzchar(label)
label[unnamed] <- as.character(index[unnamed])
positions[[i]] <- index
labels[[i]] <- label
}
positions <- unlist(positions, use.names = FALSE)
labels <- unlist(labels, use.names = FALSE)
if (!length(positions)) {
return(list())
}
result <- lapply(positions, function(position) {
if (is.na(position)) {
NULL
} else {
objects[[position]]
}
})
names(result) <- labels
if (output == "value" && length(result) == 1L) {
return(result[[1L]])
}
result
}
.getComparisonFetchPositions <- function(selector, objects, selectorNumber) {
if (is.character(selector) && is.null(dim(selector))) {
positions <- match(selector, names(objects))
positions[is.na(selector) | !nzchar(selector)] <- NA_integer_
return(positions)
}
if (!is.numeric(selector) || is.complex(selector) || !is.null(dim(selector)) ||
anyNA(selector) || any(!is.finite(selector)) || any(selector != trunc(selector))) {
stopIllegalArgument("Select comparison objects by character names or finite integer positions",
functionName = "fetch.TrialComparison", parameter = "...", value = selector,
constraint = "character names or finite integer positions",
diagnosticId = "comparison.fetch_selector_invalid", context = list(selectorNumber = selectorNumber)
)
}
size <- length(objects)
invalid <- which(selector == 0 | selector < -size | selector > size)
if (length(invalid)) {
stopIndexOutOfBounds("Object position is outside the comparison",
functionName = "fetch.TrialComparison", parameter = "...", value = selector,
index = selector[invalid[1L]], lowerBound = -size, upperBound = size,
constraint = "nonzero integer positions in [-number of objects, number of objects]",
diagnosticId = "comparison.fetch_index_out_of_bounds",
context = list(selectorNumber = selectorNumber)
)
}
ifelse(selector < 0, size + selector + 1L, selector)
}
#'
#' @title
#' Trial Comparison Data Frame
#'
#' @description
#' Converts a trial comparison to a data frame, optionally prepared for reporting.
#'
#' @param x A `TrialComparison`.
#' @param row.names Optional row names for the result.
#' @param optional Unused; included for compatibility with `as.data.frame()`.
#' @param ... Further arguments. Currently unused.
#' @inheritParams param_niceColumnNamesEnabled
#' @param includeAllParameters If `TRUE`, include all parameters supported by
#' the existing data-frame methods of the individual objects.
#' @param harmonizeColumnNames If `TRUE` (default), apply the class-specific
#' mappings described below. If `FALSE`, retain original parameter names and
#' omit extra fields that are included only to support these mappings.
#' Readable labels remain controlled by `niceColumnNamesEnabled`.
#' @param removeConstantParameters If `TRUE`, retain identifiers and only parameters
#' with different object profiles, using the same rules as `summary()`.
#' @param transposed If `TRUE`, return parameters as rows and comparison records
#' as columns, labelled by object and available stage/situation coordinates.
#' Shared scalar profiles use `Value`; duplicate labels receive unique suffixes.
#' If exactly one supplied or default input vector matches all situations across
#' stages, its caption replaces `Situation` (for example, `Alternative 1`).
#' Ambiguous axes retain `Situation`; shared profiles require agreement across objects.
#' Mixed column types are converted to a common type by transposition.
#' @param removeVariableParameters If `TRUE`, return shared parameter profiles once,
#' with stage and situation coordinates where needed, without object identifiers.
#' Cannot be combined with `removeConstantParameters = TRUE`.
#' @param digits Integer number of decimal places for numeric parameters, or `NA`
#' to retain full precision. Parameter profiles are compared before rounding.
#' @param ceilingEnabled If `TRUE`, round sample-size and event-count parameters
#' upwards to integers, using rpact parameter metadata. Variances are excluded.
#' @param output Output mode: `"data.frame"` (default), `"auto"`, `"html"`, or `"pdf"`.
#' Reporting modes add class `TrialComparisonTable` and rendering attributes;
#' they still return a data frame. `"auto"` selects HTML or LaTeX during knitting.
#' `"pdf"` produces LaTeX tables for a PDF document, not a PDF file.
#'
#' @return A data.frame, unrounded and with all columns by default. Reporting modes
#' additionally inherit from `TrialComparisonTable` for automatic knitr output.
#'
#' @details
#' With `harmonizeColumnNames = TRUE`, fixed-plan sample size columns are harmonized when the comparison includes
#' interim analyses: `nFixed`, `nFixed1`, and `nFixed2` become `numberOfSubjects`,
#' `numberOfSubjects1`, and `numberOfSubjects2`. Fixed survival events use
#' `cumulativeEventsPerStage` in mixed comparisons with interim analyses.
#' Available sample-size H1 expectations use `expectedNumberOfSubjects` and
#' `expectedNumberOfEvents`, referring to each scenario's supplied alternative.
#' See [getComparison()] for the class-specific rules and reference values.
#'
#' Shared profiles use the same exact comparison as [summary.TrialComparison()],
#' applied to the selected harmonized or original columns. The summary's
#' `harmonizeColumnNames` argument can be set independently of this data-frame option.
#' Filtering precedes rounding, readable labels and transposition. Common scalar
#' parameters are returned once; common stage or situation profiles retain their
#' coordinates. Reporting modes render HTML in a horizontally scrollable container
#' or LaTeX longtables split into column blocks with repeated identifier columns.
#' LaTeX output requires the suggested rmarkdown package and registers the longtable
#' dependency through knitr metadata. Other knitting targets use ordinary data-frame
#' output. Reporting does not modify the comparison or its contained objects.
#'
#' Multi-arm survival simulations use `categoryType` and `category` coordinates.
#' `comparison` rows (for example, `Treatment 1 vs. Control`) contain stage-wise
#' and cumulative event counts for treatment plus control. `arm` rows contain
#' individual-arm events, selections, rejections and drop-out summaries, including
#' a separate `Control` category. Arm-independent simulation results occur on
#' `overall` / `All arms` rows. Input and design settings remain available for
#' grouping. Result cells outside their applicable category are `NA`.
#' The unfiltered data frame retains this expanded structure for plotting and
#' grouping. Parameter filters use semantically normalized profiles: design
#' settings do not acquire an arm dimension from repeated rows, whereas arm-level
#' results retain their group domain even if all values are equal. Shared output
#' combines the observed coordinate domains of the common profiles, without
#' constructing new combinations or taking the first object's row layout.
#' Scalars and lower-dimensional profiles are repeated only on compatible
#' observed coordinates. Shared scalar-only output omits coordinate columns.
#'
#' @export
#'
as.data.frame.TrialComparison <- function(
x,
row.names = NULL,
optional = FALSE,
...,
niceColumnNamesEnabled = FALSE,
includeAllParameters = FALSE,
harmonizeColumnNames = TRUE,
removeConstantParameters = FALSE,
transposed = FALSE,
removeVariableParameters = FALSE,
digits = NA_integer_,
ceilingEnabled = FALSE,
output = "data.frame") {
.warnInCaseOfUnknownArguments(functionName = "as.data.frame.TrialComparison", ...)
.assertIsSingleLogical(removeConstantParameters, "removeConstantParameters")
.assertIsSingleLogical(niceColumnNamesEnabled, "niceColumnNamesEnabled")
.assertIsSingleLogical(harmonizeColumnNames, "harmonizeColumnNames")
.assertIsSingleLogical(transposed, "transposed")
.assertIsSingleLogical(removeVariableParameters, "removeVariableParameters")
.assertIsSingleLogical(ceilingEnabled, "ceilingEnabled")
if (length(digits) != 1L || !(is.numeric(digits) || identical(digits, NA)) ||
is.complex(digits) || !is.null(dim(digits)) ||
(!is.na(digits) && (!is.finite(digits) || digits != trunc(digits)))) {
stopIllegalArgument("'digits' must be a finite integer or NA",
functionName = "as.data.frame.TrialComparison", parameter = "digits", value = digits,
constraint = "one finite integer or NA", diagnosticId = "comparison.table_digits_invalid"
)
}
.assertIsSingleCharacter(output, "output")
if (!output %in% c("data.frame", "auto", "html", "pdf")) {
stopIllegalArgument("Unknown comparison table output mode",
functionName = "as.data.frame.TrialComparison", parameter = "output", value = output,
constraint = "one of data.frame, auto, html, pdf",
diagnosticId = "comparison.table_output_invalid"
)
}
if (removeConstantParameters && removeVariableParameters) {
stopConflictingArguments("Cannot remove both constant and variable parameters",
functionName = "as.data.frame.TrialComparison",
parameter = "removeVariableParameters", value = removeVariableParameters,
relatedParameter = "removeConstantParameters", relatedValue = removeConstantParameters,
constraint = "at most one parameter filter may be TRUE",
diagnosticId = "comparison.table_filters_conflict"
)
}
objects <- x$getObjects()
data <- .getTrialComparisonData(objects,
includeAllParameters = includeAllParameters,
harmonizeColumnNames = harmonizeColumnNames
)
objectNumbers <- data$objectNumber
columnNameData <- data
situationCaptions <- if (transposed) {
vapply(seq_along(objects), function(i) {
parameter <- .getComparisonSituationParameter(objects[[i]], data[data$objectNumber == i, , drop = FALSE])
if (is.null(parameter)) {
return("Situation")
}
return(.comparisonCaption(parameter, objects[[i]], tableOutputEnabled = TRUE))
}, character(1))
} else {
character()
}
allNames <- names(data)
if (removeConstantParameters) {
info <- .getTrialComparisonInfo(x, data)
selected <- getComparisonParameterNames(data, varyingOnly = FALSE)
selected <- selected[selected %in% c(.comparisonIdentifiers, info$paramName[info$nProfiles > 1L])]
data <- data[selected]
}
if (removeVariableParameters && nrow(data) > 0L) {
info <- .getTrialComparisonInfo(x, data)
data <- .getComparisonSharedData(info, data)
objectNumbers <- rep(1L, nrow(data))
rownames(data) <- NULL
columnNameData <- data
}
identifiers <- intersect(.comparisonIdentifiers, names(data))
parameters <- .getComparisonParameterOrder(objects, setdiff(names(data), identifiers))
data <- data[c(identifiers, parameters)]
countParameters <- c(
.getOutputFormatParameterNames("rpact.output.format.sample.size"),
.getOutputFormatParameterNames("rpact.output.format.event")
)
countParameters <- countParameters[!grepl("variance", countParameters, ignore.case = TRUE)]
for (parameter in setdiff(names(data), .comparisonIdentifiers)) {
if (is.numeric(data[[parameter]]) && !is.object(data[[parameter]])) {
originalValues <- data[[parameter]]
if (!is.na(digits)) {
data[[parameter]] <- round(originalValues, digits = digits)
}
if (ceilingEnabled && parameter %in% countParameters) {
for (number in unique(objectNumbers)) {
formatFunction <- .getParameterFormatFunction(parameter, objects[[number]])
if (formatFunction %in% c(".formatSampleSizes", ".formatEvents")) {
rows <- objectNumbers == number
data[[parameter]][rows] <- ceiling(originalValues[rows])
}
}
}
}
}
identifiers <- intersect(.comparisonIdentifiers, names(data))
if (niceColumnNamesEnabled) {
labels <- names(.getTrialComparisonData(x$getObjects(),
niceColumnNamesEnabled = TRUE,
includeAllParameters = includeAllParameters,
harmonizeColumnNames = harmonizeColumnNames
))
names(data) <- labels[match(names(data), allNames)]
identifiers <- labels[match(identifiers, allNames)]
}
if (transposed) {
rowCaptions <- if (removeVariableParameters) {
if (length(unique(situationCaptions)) == 1L) {
rep(situationCaptions[1L], nrow(columnNameData))
} else {
rep("Situation", nrow(columnNameData))
}
} else {
situationCaptions[columnNameData$objectNumber]
}
situationNames <- .getComparisonTransposedColumnNames(columnNameData, rowCaptions)
values <- as.data.frame(t(as.matrix(data)), stringsAsFactors = FALSE)
names(values) <- situationNames
data <- cbind(data.frame(Parameter = names(data), stringsAsFactors = FALSE), values)
rownames(data) <- NULL
identifiers <- "Parameter"
}
if (!is.null(row.names)) {
rownames(data) <- row.names
}
if (output != "data.frame") {
class(data) <- c("TrialComparisonTable", "data.frame")
attr(data, "comparisonTableOutput") <- output
attr(data, "comparisonTableIdentifiers") <- identifiers
attr(data, "comparisonTableCaption") <- if (removeVariableParameters) {
"Common parameters"
} else {
"Comparison"
}
}
return(data)
}
.comparisonIdentifiers <- c("objectNumber", "objectName", "stages", "stage", "situation", "categoryType", "category")
.comparisonScope <- c("objectType", "endpoint", "calculationTarget")
.getComparisonSituationParameter <- function(object, data) {
if (!inherits(object, "ParameterSet") || !"situation" %in% names(data)) {
return(NULL)
}
situations <- data$situation
if (!length(situations) || anyNA(situations)) {
return(NULL)
}
nSituations <- max(situations)
if (nSituations <= 1L || !setequal(situations, seq_len(nSituations))) {
return(NULL)
}
# Only supplied/default inputs can explain a scenario axis. Derived results
# and vectors indexed by stage, arm or population must not name that axis.
candidates <- intersect(c(object$.getUserDefinedParameters(), object$.getDefaultParameters()), names(data))
candidates <- setdiff(candidates, c(.comparisonIdentifiers, .getComparisonCoordinateNames(data)))
candidates <- candidates[vapply(candidates, function(parameter) {
values <- object[[parameter]]
if (!is.atomic(values) || !is.null(dim(values)) || length(values) != nSituations ||
anyNA(values) || length(unique(values)) <= 1L) {
return(FALSE)
}
# Check the unrounded values at every stage, not merely vector lengths.
return(isTRUE(all.equal(unname(data[[parameter]]), unname(values[situations]),
check.attributes = FALSE, tolerance = 0)))
}, logical(1))]
if (length(candidates) != 1L) {
return(NULL)
}
return(candidates[[1L]])
}
.getComparisonTransposedColumnNames <- function(data, situationCaptions = rep("Situation", nrow(data))) {
coordinates <- unique(c(.getComparisonCoordinateNames(data), intersect("situation", names(data))))
# The generated situation index is redundant for a single situation with
# semantic coordinates, but distinguishes multiple scenarios at each stage.
if (length(setdiff(coordinates, "situation")) &&
"situation" %in% coordinates && length(unique(data$situation)) <= 1L) {
coordinates <- setdiff(coordinates, "situation")
}
captions <- c(stages = "Stage", stage = "Stage", time = "Time",
treatmentArm = "Treatment arm", populations = "Population",
situations = "Situation", situation = "Situation", categoryType = "Category type", category = "Category")
labels <- vapply(seq_len(nrow(data)), function(i) {
parts <- character()
if ("objectNumber" %in% names(data)) {
label <- data$objectName[i]
if (is.null(label) || is.na(label) || !nzchar(trimws(label))) {
label <- paste("Object", data$objectNumber[i])
}
parts <- label
}
for (coordinate in coordinates) {
value <- data[[coordinate]][i]
if (!is.na(value) && nzchar(trimws(as.character(value)))) {
caption <- if (coordinate == "situation") {
situationCaptions[i]
} else {
captions[[coordinate]]
}
parts <- c(parts, paste(caption, value))
}
}
if (!length(parts)) {
return("Value")
}
return(paste(unique(parts), collapse = " / "))
}, character(1))
return(make.unique(labels))
}
.assertComparisonLimit <- function(value, parameter, functionName) {
if (!is.numeric(value) || is.complex(value) || length(value) != 1L || is.na(value) ||
!is.finite(value) || value < 1 || value != trunc(value)) {
stopIllegalArgument("'", parameter, "' must be a positive finite integer",
functionName = functionName, parameter = parameter, value = value,
constraint = "one finite integer >= 1", diagnosticId = "comparison.display_limit_invalid"
)
}
}
.comparisonText <- function(text, width = 100L) {
text <- gsub("[[:cntrl:]]", " ", as.character(text))
ifelse(nchar(text) > width, paste0(substr(text, 1L, width - 3L), "..."), text)
}
.comparisonPreview <- function(values, maxValues = 4L, digits = NA_integer_, reference = NULL, truncate = TRUE) {
shown <- utils::head(values, maxValues)
text <- .formatComparisonParameterValues(shown, digits)
if (is.na(digits) && !is.null(reference) && is.numeric(values)) {
labels <- .formatComparisonParameterValues(reference)
text <- labels[match(shown, reference)]
}
text[is.na(text)] <- "NA"
if (is.numeric(shown)) {
text[is.nan(shown)] <- "NaN"
}
text[!nzchar(trimws(text))] <- '""'
text <- paste(.comparisonText(text, if (!truncate) {
Inf
} else if (length(shown) == 1L) {
55L
} else {
20L
}), collapse = ", ")
if (length(values) > maxValues) {
text <- paste0(text, ", ... (", length(values), " values)")
}
text
}
.comparisonRole <- function(objects, parameter) {
if (parameter %in% .comparisonScope) {
return("Object types and scope")
}
sourceParameter <- sub("^(optimal_|design_|simulation_)", "", parameter)
roles <- unlist(lapply(objects, function(object) {
return(unlist(lapply(.getComparisonMetadataSources(object), function(source) {
if (sourceParameter %in% source$.getInputParameters()) {
return("input")
}
if (sourceParameter %in% c(source$.getGeneratedParameters(), source$.getDerivedParameters())) {
return("result")
}
return(character())
}), use.names = FALSE))
}), use.names = FALSE)
# Retain input precedence when compared objects assign different roles.
if ("input" %in% roles) {
return("Inputs and design settings")
}
if ("result" %in% roles) {
return("Results and derived parameters")
}
# Adapter coordinates without ParameterSet metadata retain their input role.
if (grepl("^observed", parameter) || parameter %in% c(
"time", "treatmentArm", "populations", "situations", "type", "nPlanned"
)) {
return("Inputs and design settings")
}
return("Results and derived parameters")
}
.getTrialComparisonTitle <- function(objects, summaryEnabled = FALSE) {
categories <- vapply(objects, function(object) {
context <- .getComparisonAdapterContext(object)
if (!is.null(context)) {
return(context$target)
}
if (inherits(object, "SimulationResults")) {
return("Power simulation")
}
if (inherits(object, c("TrialDesign", "TrialDesignCharacteristics"))) {
return("Design")
}
if (inherits(object, "PowerAndAverageSampleNumberResult")) {
return("Power and average sample size (ASN)")
}
if (inherits(object, "TrialDesignPlan")) {
if (object$.isSampleSizeObject()) {
return("Sample size calculation")
}
if (object$.isPowerObject()) {
return("Power calculation")
}
}
return("Design plan")
}, character(1))
categories <- unique(categories)
category <- if (!length(categories)) {
"Trial"
} else if (length(categories) == 1L) {
categories[[1L]]
} else {
"Design plan"
}
title <- paste(category, "comparison")
if (summaryEnabled) {
title <- paste(title, "summary")
}
return(title)
}
.comparisonObjectType <- function(object, startWithUpperCase = TRUE) {
context <- .getComparisonAdapterContext(object)
if (!is.null(context)) {
return(if (startWithUpperCase) {
.firstCharacterToUpperCase(context$target)
} else {
tolower(context$target)
})
}
label <- object$.toString(startWithUpperCase = FALSE)
if (inherits(object, "TrialDesignPlan") && !inherits(object, "SimulationResults")) {
label <- paste(.formatCamelCase(object$.objectType), label)
}
if (startWithUpperCase) {
label <- .firstCharacterToUpperCase(label)
}
return(label)
}
.comparisonOverview <- function(objects) {
if (!length(objects)) {
return("Empty trial comparison.")
}
types <- vapply(objects, .comparisonObjectType, character(1), startWithUpperCase = FALSE)
if (length(unique(types)) == 1L &&
all(vapply(objects, inherits, logical(1), "TrialDesignPlan")) &&
!any(vapply(objects, inherits, logical(1), "SimulationResults"))) {
return(paste0(
"Comparison of ", length(objects), " ", types[1L],
if (length(objects) == 1L) {
" calculation."
} else {
" calculations."
}
))
}
distinct <- unique(types)
description <- ""
for (type in distinct) {
description <- .concatenateSummaryText(description, type)
}
return(paste0(
"Comparison of ", length(objects), " trial planning ",
if (length(objects) == 1L) {
"result: "
} else {
"results: "
}, description, "."
))
}
.comparisonCaption <- function(parameter, object = NULL, tableOutputEnabled = FALSE) {
if (!is.null(object) && !parameter %in% c(.comparisonScope, .comparisonIdentifiers)) {
sources <- .getComparisonMetadataSources(object)
matching <- vapply(sources, function(source) {
return(parameter %in% names(source))
}, logical(1))
if (!any(matching)) {
baseParameter <- sub("\\.[^.]+$", "", parameter)
if (grepl("^(observedDropoutProportion|dropoutObservationTime)[12]$", baseParameter)) {
for (source in sources) {
values <- source[[baseParameter]]
if (!is.matrix(values)) {
next
}
for (g in seq_len(nrow(values))) {
group <- if (inherits(source, "SimulationResultsEnrichmentSurvival")) {
.getCategoryCaptionEnrichment(source, baseParameter, g)
} else {
paste0("arm", g)
}
if (identical(parameter, paste0(baseParameter, ".", group))) {
caption <- .getParameterCaption(baseParameter, source,
tableOutputEnabled = tableOutputEnabled)
if (is.null(caption) || !nzchar(caption)) {
caption <- .getParameterCaption(baseParameter, source)
}
return(.getParameterSetParameterCaptionPerRow(source, baseParameter, caption, g))
}
}
}
}
return(NA_character_)
}
object <- sources[[which(matching)[1L]]]
}
if (inherits(object, "SimulationResultsMultiArmSurvival") &&
grepl("^(observedDropoutProportion|dropoutObservationTime)1$", parameter)) {
return(paste0(sub(" \\(1\\)$", "", .getParameterCaption(parameter, object)), " (treatment arm)"))
}
if (inherits(object, "SimulationResultsMultiArmSurvival") &&
parameter %in% c("singleEventsPerStage", "cumulativeEventsPerStage", "singleEventsPerArmAndStage")) {
scope <- if (parameter == "singleEventsPerArmAndStage") {
"individual arm"
} else {
"treatment plus control"
}
return(paste0(.getParameterCaption(parameter, object), " (", scope, ")"))
}
caption <- .getParameterCaption(parameter, obj = object, tableOutputEnabled = tableOutputEnabled)
if (is.null(caption) || length(caption) != 1L || is.na(caption) || !nzchar(caption)) {
caption <- C_TABLE_COLUMN_NAMES[[parameter]]
}
if (is.null(caption) || length(caption) != 1L || is.na(caption) || !nzchar(caption)) {
caption <- switch(parameter,
objectType = "Object type",
endpoint = "Endpoint",
calculationTarget = "Calculation target",
situation = "Situation",
stage = "Stage",
parameter
)
}
return(caption)
}
.comparisonCaptionLabel <- function(parameter, captions, tableOutputEnabled = FALSE) {
captions <- unique(captions[!is.na(captions) & nzchar(captions)])
if (!length(captions)) {
return(.comparisonCaption(parameter, tableOutputEnabled = tableOutputEnabled))
}
return(paste(captions, collapse = " / "))
}
.comparisonConstantCell <- function(value) {
if (is.na(value)) {
return(value)
}
tokens <- trimws(strsplit(value, ",", fixed = TRUE)[[1L]])
numericPattern <- "^[+-]?([0-9]+([.][0-9]*)?|[.][0-9]+)([eE][+-]?[0-9]+)?$"
if (!length(tokens) || grepl(",[[:space:]]*$", value) || !all(grepl(numericPattern, tokens))) {
return(value)
}
numbers <- as.numeric(tokens)
if (!all(is.finite(numbers)) || length(unique(numbers)) != 1L) {
return(value)
}
# Use a compact scalar representation that round-trips without precision loss.
number <- numbers[[1L]] + 0
for (precision in 1:17) {
text <- sprintf("%.*g", precision, number)
if (identical(as.numeric(text), number)) {
return(text)
}
}
return(value)
}
.getComparisonProfileSource <- function(object, parameter) {
if (is.null(object) || grepl("^(optimal_|design_|simulation_)", parameter)) {
return(NULL)
}
design <- .getComparisonDesign(object)
if (!is.null(design) && parameter %in% names(design)) {
return(list(object = design, parameter = parameter))
}
if (parameter %in% names(object)) {
return(list(object = object, parameter = parameter))
}
mapping <- .getComparisonColumnMapping(object, hasInterimAnalyses = TRUE)
sources <- names(mapping)[mapping == parameter & names(mapping) %in% names(object)]
if (length(sources) == 1L) {
return(list(object = object, parameter = sources[[1L]]))
}
for (source in .getComparisonMetadataSources(object)) {
if (parameter %in% names(source)) {
return(list(object = source, parameter = parameter))
}
}
return(NULL)
}
.getComparisonProfileDimensions <- function(data, source, categoryType) {
if (is.null(source)) {
return(NULL)
}
value <- source$object[[source$parameter]]
dimensions <- dim(value)
stages <- intersect(c("stages", "stage"), names(data))
situations <- intersect(c("situation", "situations"), names(data))
categories <- intersect(c("categoryType", "category"), names(data))
stageParameters <- c("informationRates", "criticalValues", "stageLevels", "alphaSpent",
"betaSpent", "futilityBounds", "weights", "plannedEvents", "plannedSubjects",
"minNumberOfEventsPerStage", "maxNumberOfEventsPerStage",
"minNumberOfSubjectsPerStage", "maxNumberOfSubjectsPerStage")
if (inherits(source$object, "TrialDesign")) {
if (source$parameter %in% stageParameters || length(value) > 1L) {
return(stages)
}
return(character())
}
if (!is.null(categoryType) && categoryType %in% c("arm", "comparison")) {
keys <- categories
if (length(dimensions) == 3L) {
keys <- c(stages, keys)
if (dimensions[2L] > 1L) {
keys <- c(keys, situations)
}
return(keys)
}
if (is.matrix(value)) {
if (ncol(value) > 1L) {
keys <- c(keys, situations)
}
return(keys)
}
# A genuinely missing parameter has no coordinate domain to infer.
if (length(value) == 1L && is.na(value)) {
return(character())
}
return(NULL)
}
if (source$parameter %in% stageParameters) {
return(stages)
}
if (length(value) == 1L && is.null(dimensions)) {
return(character())
}
if (inherits(source$object, c("TrialDesignPlan", "SimulationResults")) &&
(!.isMultiHypothesesObject(source$object) || identical(categoryType, "overall"))) {
if (is.matrix(value)) {
keys <- if (nrow(value) > 1L) {
stages
} else {
character()
}
if (ncol(value) > 1L) {
keys <- c(keys, situations)
}
return(keys)
}
if (is.null(dimensions) && length(value) > 1L) {
return(situations)
}
}
return(NULL)
}
.reduceComparisonProfile <- function(profile, keys) {
reduced <- unique(profile[c(keys, "value")])
if (!length(keys)) {
if (nrow(reduced) == 1L) {
return(reduced)
}
return(NULL)
}
if (anyDuplicated(.comparisonCoordinateIds(reduced, keys))) {
return(NULL)
}
return(reduced)
}
.comparisonProfile <- function(data, parameter, object = NULL) {
source <- .getComparisonProfileSource(object, parameter)
categoryType <- .getComparisonSurvivalCategory(object, parameter)
if (!is.null(categoryType) && "categoryType" %in% names(data)) {
data <- data[!is.na(data$categoryType) & data$categoryType == categoryType, , drop = FALSE]
if (grepl("^(observedDropoutProportion|dropoutObservationTime)[12]$", parameter)) {
control <- endsWith(parameter, "2")
data <- data[!is.na(data$category) & (data$category == "Control") == control, , drop = FALSE]
}
}
values <- data[[parameter]]
if (is.character(values)) {
values <- vapply(values, .comparisonConstantCell, character(1), USE.NAMES = FALSE)
data[[parameter]] <- values
}
contextParameter <- grepl("^(optimal_|design_|simulation_)", parameter)
if ((is.null(source) && all(is.na(values))) || parameter %in% .comparisonScope ||
(contextParameter && length(unique(values)) <= 1L)) {
return(data.frame(value = values[1L]))
}
coordinates <- .getComparisonCoordinateNames(data)
semanticCoordinates <- setdiff(coordinates, c("stages", "stage"))
keys <- if (length(semanticCoordinates)) {
coordinates
} else {
intersect(c("stages", "stage", "situation"), names(data))
}
profile <- data[keys]
profile$value <- values
if (!is.null(source) && (is.null(categoryType) || identical(categoryType, "overall"))) {
reduced <- .reduceComparisonProfile(profile, setdiff(keys, c("categoryType", "category")))
if (!is.null(reduced)) {
profile <- reduced
}
}
dimensions <- .getComparisonProfileDimensions(data, source, categoryType)
if (!is.null(dimensions)) {
reduced <- .reduceComparisonProfile(profile, intersect(dimensions, names(profile)))
if (!is.null(reduced)) {
profile <- reduced
}
} else if (is.null(source) && length(unique(values)) <= 1L && !length(semanticCoordinates)) {
profile <- data.frame(value = values[1L])
} else if (is.null(source) && !length(semanticCoordinates)) {
for (key in keys) {
reduced <- .reduceComparisonProfile(profile, key)
if (!is.null(reduced)) {
profile <- reduced
break
}
}
}
keys <- setdiff(names(profile), "value")
if (length(keys)) {
profile <- profile[do.call(order, profile[keys]), , drop = FALSE]
}
rownames(profile) <- NULL
return(profile)
}
.getComparisonSharedCoordinates <- function(profiles, data) {
keys <- unique(unlist(lapply(profiles, function(profile) {
return(setdiff(names(profile), "value"))
}), use.names = FALSE))
coordinateOrder <- c("stages", "stage", "time", "situation", "situations",
"treatmentArm", "populations", "categoryType", "category")
keys <- c(intersect(coordinateOrder, keys), setdiff(keys, coordinateOrder))
if (!length(keys)) {
return(list(data = data.frame(row.names = 1L), present = matrix(FALSE, 1L, 0L)))
}
frames <- list()
present <- list()
for (profile in profiles) {
coordinates <- intersect(keys, names(profile))
if (!length(coordinates)) {
next
}
frame <- unique(profile[coordinates])
for (key in setdiff(keys, coordinates)) {
frame[[key]] <- data[[key]][rep(NA_integer_, nrow(frame))]
}
frames[[length(frames) + 1L]] <- frame[keys]
present[[length(present) + 1L]] <- matrix(rep(keys %in% coordinates, each = nrow(frame)),
nrow = nrow(frame), dimnames = list(NULL, keys))
}
grid <- do.call(rbind, frames)
present <- do.call(rbind, present)
# A less specific row is redundant only when an actually observed, more
# specific coordinate tuple covers it. Never form a Cartesian product.
keep <- rep(TRUE, nrow(grid))
signatures <- unique(present)
for (i in seq_len(nrow(signatures))) {
required <- which(signatures[i, ])
rows <- which(rowSums(present[, required, drop = FALSE]) == length(required) &
rowSums(present) == length(required))
covering <- which(rowSums(present[, required, drop = FALSE]) == length(required) &
rowSums(present) > length(required))
if (length(covering)) {
keep[rows] <- !.comparisonCoordinateIds(grid[rows, , drop = FALSE], keys[required]) %in%
.comparisonCoordinateIds(grid[covering, , drop = FALSE], keys[required])
}
}
grid <- grid[keep, , drop = FALSE]
present <- present[keep, , drop = FALSE]
uniqueRows <- !duplicated(cbind(grid, as.data.frame(present)))
grid <- grid[uniqueRows, , drop = FALSE]
present <- present[uniqueRows, , drop = FALSE]
rowOrder <- do.call(order, grid)
return(list(data = grid[rowOrder, , drop = FALSE], present = present[rowOrder, , drop = FALSE]))
}
.getComparisonSharedData <- function(info, data) {
common <- which(info$nProfiles == 1L)
if (!length(common)) {
return(data.frame())
}
profiles <- lapply(info$profiles[common], `[[`, 1L)
coordinates <- .getComparisonSharedCoordinates(profiles, data)
result <- coordinates$data
for (i in seq_along(profiles)) {
profile <- profiles[[i]]
keys <- setdiff(names(profile), "value")
if (!length(keys)) {
values <- rep(profile$value[1L], nrow(result))
} else {
indices <- match(.comparisonCoordinateIds(result, keys), .comparisonCoordinateIds(profile, keys))
applicable <- rowSums(coordinates$present[, keys, drop = FALSE]) == length(keys)
indices[!applicable] <- NA_integer_
values <- profile$value[indices]
}
result[[info$paramName[common[i]]]] <- values
}
rownames(result) <- NULL
return(result)
}
.getComparisonParameterOrder <- function(objects, candidates) {
sourceNames <- sub("^(optimal_|design_|simulation_)", "", candidates)
ordered <- character()
for (method in c(".getUserDefinedParameters", ".getDefaultParameters",
".getGeneratedParameters", ".getDerivedParameters")) {
group <- character()
for (object in objects) {
for (source in .getComparisonMetadataSources(object)) {
parameters <- source[[method]]()
parameters <- parameters[parameters %in% sourceNames]
# Insert additional parameters before their next known neighbour.
# Conflicting orders retain the earlier object's precedence.
for (i in seq_along(parameters)) {
parameter <- parameters[[i]]
if (parameter %in% group) {
next
}
following <- parameters[seq.int(i, length(parameters))]
following <- following[following %in% group]
position <- if (length(following)) {
match(following[[1L]], group) - 1L
} else {
length(group)
}
group <- append(group, parameter, after = position)
}
}
}
ordered <- c(ordered, unlist(lapply(group, function(parameter) {
return(candidates[sourceNames == parameter])
}), use.names = FALSE))
}
# Keep scope columns first and untyped adapter columns in their original order.
return(unique(c(intersect(.comparisonScope, candidates), ordered, candidates)))
}
.getTrialComparisonInfo <- function(object, data = .getTrialComparisonData(object$getObjects())) {
info <- .getComparisonParameterInfo(data)
# Use the common metadata API for the full ordered candidate set; row-wise
# variation alone cannot identify equal stage profiles of different objects.
candidates <- getComparisonParameterNames(data, varyingOnly = FALSE, exclude = .comparisonIdentifiers)
objects <- object$getObjects()
candidates <- .getComparisonParameterOrder(objects, candidates)
info <- info[match(candidates, info$paramName), , drop = FALSE]
frames <- split(data, factor(data$objectNumber, levels = seq_along(objects)))
profiles <- lapply(info$paramName, function(parameter) {
return(lapply(seq_along(frames), function(i) {
return(.comparisonProfile(frames[[i]], parameter, objects[[i]]))
}))
})
# Exact serialized keys avoid display rounding and quadratic pairwise comparisons.
groups <- lapply(profiles, function(items) {
keys <- vapply(items, function(item) paste(as.character(serialize(item, NULL, version = 2)), collapse = ""), "")
match(keys, unique(keys))
})
info$nProfiles <- vapply(groups, function(group) length(unique(group)), integer(1))
info$role <- vapply(info$paramName, function(parameter) .comparisonRole(objects, parameter), "")
# Capture object-specific captions separately: captions must not participate
# in exact value-profile grouping or change when a summary is printed later.
info$paramCaptions <- lapply(info$paramName, function(parameter) {
vapply(objects, function(item) {
.comparisonCaption(parameter, item)
}, character(1))
})
info$paramCaption <- vapply(seq_len(nrow(info)), function(i) {
.comparisonCaptionLabel(info$paramName[i], info$paramCaptions[[i]])
}, character(1))
info$profiles <- profiles
info$profileGroups <- groups
rownames(info) <- NULL
info
}
#'
#' @title
#' Print a Trial Comparison
#'
#' @description
#' Prints a compact overview of a trial comparison using descriptive parameter captions.
#'
#' @param x A `TrialComparison`.
#' @param ... Further arguments. Currently unused.
#' @param markdown Whether to return Markdown output. NA uses rpact settings.
#' @param digits Display rounding only, as in [getComparisonParameterDescriptions()].
#' @param maxTypes,maxMetrics Maximum numbers of object types and selected metrics
#' to display. These limits do not affect [as.data.frame.TrialComparison()].
#'
#' @return The object invisibly, or knitr Markdown output when requested.
#'
#' @export
#'
print.TrialComparison <- function(
x,
...,
markdown = NA,
digits = NA_integer_,
maxTypes = 5L,
maxMetrics = 6L) {
.warnInCaseOfUnknownArguments(functionName = "print.TrialComparison", ...)
.assertIsSingleLogical(markdown, "markdown", naAllowed = TRUE)
if (is.na(markdown)) {
markdown <- .isMarkdownEnabled("print")
}
if (markdown && .comparisonHasConsumerCall(sys.calls())) {
.addObjectToPipeOperatorQueue(x)
return(invisible(x))
}
if (markdown) {
return(knitr::asis_output(paste(utils::capture.output(x$.catMarkdownText(
digits = digits, maxTypes = maxTypes, maxMetrics = maxMetrics
)), collapse = "\n")))
}
x$.show(
digits = digits,
maxTypes = maxTypes,
maxMetrics = maxMetrics,
consoleOutputEnabled = TRUE
)
invisible(x)
}
.showTrialComparison <- function(
object,
...,
digits = NA_integer_,
maxTypes = 5L,
maxMetrics = 6L,
consoleOutputEnabled = TRUE) {
.warnInCaseOfUnknownArguments(functionName = "TrialComparison$show", ...)
.assertComparisonLimit(maxTypes, "maxTypes", "print.TrialComparison")
.assertComparisonLimit(maxMetrics, "maxMetrics", "print.TrialComparison")
data <- .getTrialComparisonData(object$getObjects())
info <- .getComparisonParameterInfo(data)
getComparisonParameterDescriptions(info[FALSE, ], digits = digits) # Validate display precision.
object$.resetCat()
emit <- function(...) {
object$.cat(..., consoleOutputEnabled = consoleOutputEnabled)
}
indent <- if (consoleOutputEnabled) {
" "
} else {
" "
}
object$.cat(.getTrialComparisonTitle(object$getObjects()), "\n\n",
heading = 1, consoleOutputEnabled = consoleOutputEnabled
)
emit(length(object), " objects; ", nrow(data), " comparison rows; ", ncol(data), " columns.\n")
types <- table(vapply(object$getObjects(), function(item) {
.comparisonObjectType(item)
}, ""))
typeLabels <- .comparisonText(utils::head(names(types), maxTypes), 55L)
typeWidth <- max(c(0L, nchar(typeLabels)))
if (length(types)) {
emit("\n")
object$.cat("Object types:\n", heading = 2, consoleOutputEnabled = consoleOutputEnabled)
}
for (i in seq_along(typeLabels)) {
emit(indent, sprintf("%-*s : %s", typeWidth, typeLabels[i], types[i]), "\n")
}
if (length(types) > maxTypes) {
emit(indent, "... ", length(types) - maxTypes, " more object types.\n")
}
metrics <- intersect(c(
"kMax", "alpha", "beta", "nMax", "averageSampleNumber", "maxNumberOfSubjects", "maxNumberOfEvents",
"nFixed", "overallReject", "expectedNumberOfSubjects", "expectedNumberOfEvents", "studyDuration"
), info$paramName[!info$isEmpty])
shownMetrics <- utils::head(metrics, maxMetrics)
metricCaptions <- vapply(shownMetrics, function(parameter) {
captions <- vapply(object$getObjects(), function(item) {
.comparisonCaption(parameter, item)
}, character(1))
.comparisonText(.comparisonCaptionLabel(parameter, captions), 65L)
}, character(1))
metricWidth <- max(c(0L, nchar(metricCaptions)))
if (length(metrics)) {
emit("\n")
object$.cat("Observed metrics (across objects, stages and situations):\n",
heading = 2, consoleOutputEnabled = consoleOutputEnabled
)
}
for (parameter in shownMetrics) {
row <- info[info$paramName == parameter, , drop = FALSE]
values <- row$values[[1L]]
if (is.numeric(values) && length(values) > 1L) {
values <- range(values)
}
emit(
indent, sprintf("%-*s : %s", metricWidth, metricCaptions[[parameter]],
.comparisonPreview(values, digits = digits)),
if (row$hasMissingValues) {
" (missing values present)"
} else {
""
}, "\n"
)
}
if (length(metrics) > maxMetrics) {
emit(indent, "... ", length(metrics) - maxMetrics, " more observed metrics.\n")
}
emit("\n")
object$.cat("Available operations:\n", heading = 2, consoleOutputEnabled = consoleOutputEnabled)
operations <- c(
"summary(x)", "as.data.frame(x)",
"plot(x, xAxis = ..., yAxis = ...)",
"getObjects(x)")
descriptions <- c(
"Compare differences",
"Access all data", "Plot selected parameters",
"Access contained objects")
operationWidth <- max(nchar(operations))
for (i in seq_along(operations)) {
emit(indent, sprintf("%-*s : %s", operationWidth, operations[i], descriptions[i]), "\n")
}
return(invisible(object))
}
#'
#' @title
#' Summarize Differences Between Trial Planning Objects
#'
#' @description
#' Summarizes differences between the object profiles in a trial comparison.
#'
#' @param object A `TrialComparison` or an existing `TrialComparisonSummary`.
#' @param ... Further arguments. Currently unused.
#' @param digits Display rounding only; exact values determine differences.
#' @param maxParameters Maximum number of differing parameters shown, across all
#' sections. Increase this to inspect further differences.
#' @param maxProfiles Maximum number of distinct profiles shown per parameter.
#' @param maxObjects Maximum object numbers/names listed per profile.
#' @param maxValues Maximum profile values shown per preview.
#' @param maxTableColumns Maximum result/profile columns per Markdown table block
#' (default 4). Coordinate columns are additional. Also applies with `showAll = TRUE`.
#' @param textMode Console text handling: `"wrap"` (default) wraps complete text,
#' `"truncate"` shows compact previews with an explicit shortening notice,
#' and `"full"` writes complete text without automatic wrapping. Markdown
#' always retains complete text in its profile tables.
#' @param width Console line width, at least 20 characters. Defaults to
#' `getOption("width", 80L)`. Long unbroken words can exceed this width.
#' @param showAll If `TRUE`, lift all four `max*` limits and disable text truncation.
#' Wrapping remains active when `textMode = "wrap"`. Defaults to `FALSE`.
#' @param showDataType If `TRUE`, include data type descriptions such as
#' `integer, continuous` in parameter headings. Defaults to `FALSE`.
#' @param harmonizeColumnNames If `TRUE` (default), compare the harmonized
#' columns described in [getComparison()]. If `FALSE`, compare the original
#' parameter names, as in `as.data.frame(object, harmonizeColumnNames = FALSE)`.
#' @param output One of "all", "title", "overview", or "body".
#'
#' @return A `TrialComparisonSummary` inheriting from `SummaryFactory`. Its
#' `parameterInfo` contains metadata, full exact profiles and object group IDs.
#' The displayed summary is a snapshot; call `summary()` again after changing
#' an underlying object. The `harmonizeColumnNames` attribute of `parameterInfo`
#' records the selected naming mode for plotting and R-code reconstruction.
#' Input roles take precedence when roles differ across the compared object types.
#'
#' @details
#' Constant numeric vector cells compare equal to their scalar value regardless
#' of vector length. Nonconstant vectors, missing values, and their positions
#' remain part of the exact comparison. The stored comparison data are unchanged.
#' Profile coordinates follow the parameter's source and native dimensions.
#' Repeated design settings on simulation category rows are normalized only
#' when the remaining coordinates uniquely determine the exact values. Stage
#' and group domains of dimensioned parameters remain meaningful when their
#' values are equal. Uncertain or conflicting dependencies retain additional
#' coordinates rather than averaging or selecting an arbitrary value.
#' Both parameter-filter options of [as.data.frame.TrialComparison()] use these
#' profiles; unfiltered data-frame rows remain unchanged for plotting.
#' This value normalization also applies when column-name harmonization is disabled.
#' Plotting a summary retains its selected column-name mode unless custom data
#' are supplied.
#'
#' Parameter captions are resolved separately for each original object, including
#' its design when a parameter comes from that design. `parameterInfo$paramName`
#' retains the column names selected by `harmonizeColumnNames`; `paramCaption`
#' contains the display label
#' and `paramCaptions` contains captions in object order (NA for absent parameters).
#' These captions are captured with the summary. Distinct object-specific captions
#' are shown together and identified alongside the corresponding object labels;
#' they do not change exact value-profile grouping. Unnamed entries are labelled
#' `Simulation` when all objects are simulation results, `Design` when all objects
#' are trial designs, and `Result` otherwise, followed by their collection position.
#' Explicit names take precedence. Full type descriptions remain in the overview.
#' The overview and these labels are captured with the summary. The legend explains exact
#' profile comparison and mentions NA only when displayed profiles contain
#' missing values. Titles distinguish designs, sample size calculations, power
#' calculations, and power simulations. Mixed comparisons use a design plan
#' comparison title; empty comparisons retain the general trial comparison title.
#' Markdown output places coordinates in rows and displayed profiles in columns.
#' Scalar profiles use one-row tables. At most `maxTableColumns` profile columns
#' (default 4) appear per block, with coordinate columns repeated in each block.
#' This layout limit also applies with `showAll = TRUE`. Long profile labels are
#' listed above the tables with short references. Incompatible coordinate
#' structures use separate tables. Missing and omitted coordinates use the same
#' markers as console tables. Data limits apply independently of table layout.
#'
#' Console output uses a single comparison line for numeric, character or logical scalar values when
#' at most four objects are compared, all fit within the profile/object limits,
#' captions agree and the complete line fits within `width`. Otherwise scalars
#' retain the labelled profile display. Profiles with compatible coordinate
#' columns are aligned by their exact coordinates and displayed side by side.
#' Coordinates constant across the complete parameter are listed once, except
#' redundant constant category types, categories and situation identifiers, which
#' are omitted. Varying categories use an Arm or Comparison column caption where
#' appropriate. A scalar missing profile is displayed as an `NA` column alongside
#' the coordinates of the other profiles; non-missing scalars are not expanded.
#' If the table exceeds `width`, values are listed vertically per coordinate.
#' Profiles sharing at least one coordinate can use a joint table even if their
#' remaining axes differ. A dash marks an inapplicable coordinate; values are
#' not broadcast to categories absent from their source profile. Profiles without
#' shared coordinates retain separate displays.
#' `<absent>` denotes a coordinate absent from a profile, whereas `<omitted>`
#' denotes a value outside that profile's `maxValues` preview. Neither marker
#' represents a stored `NA`. Display choices do not change exact profile grouping.
#'
#' A `NULL` display argument reads its setting through `.getEnvironmentVariable()`.
#' Explicit arguments take precedence over environment variables, which take
#' precedence over R options and defaults. The four default limits are 12
#' parameters, 3 profiles, 6 objects and 4 values. R options use the prefix
#' `rpact.comparison.summary.` followed by the argument name: `maxParameters`,
#' `maxProfiles`, `maxObjects`, `maxValues`, `maxTableColumns`, `textMode`, `width`, `showAll` or `showDataType`.
#' The corresponding environment variables are `RPACT_COMPARISON_SUMMARY_MAX_PARAMETERS`,
#' `RPACT_COMPARISON_SUMMARY_MAX_PROFILES`, `RPACT_COMPARISON_SUMMARY_MAX_OBJECTS`,
#' `RPACT_COMPARISON_SUMMARY_MAX_VALUES`, `RPACT_COMPARISON_SUMMARY_TEXT_MODE`,
#' `RPACT_COMPARISON_SUMMARY_WIDTH`, `RPACT_COMPARISON_SUMMARY_SHOW_ALL` and
#' `RPACT_COMPARISON_SUMMARY_SHOW_DATA_TYPE`.
#' Settings are captured when the summary is created. For a complete display use
#' `summary(x, showAll = TRUE)`; for a compact display use `textMode = "truncate"`.
#'
#' @export
#'
summary.TrialComparison <- function(
object,
...,
digits = NA_integer_,
maxParameters = NA_integer_,
maxProfiles = NA_integer_,
maxObjects = NA_integer_,
maxValues = NA_integer_,
output = c("all", "title", "overview", "body"),
harmonizeColumnNames = TRUE,
textMode = c("wrap", "truncate", "full"),
width = NA_integer_,
showAll = NA,
showDataType = FALSE,
maxTableColumns = NA_integer_) {
.warnInCaseOfUnknownArguments(functionName = "summary.TrialComparison", ...)
.assertIsSingleLogical(harmonizeColumnNames, "harmonizeColumnNames")
setting <- function(value, parameter, default, type) {
if (!is.null(value) && !(length(value) == 1L && is.na(value))) {
return(value)
}
suffix <- gsub("([a-z])([A-Z])", "\\1_\\2", parameter)
return(.getEnvironmentVariable(paste0("RPACT_COMPARISON_SUMMARY_", toupper(suffix)),
paste0("rpact.comparison.summary.", parameter), default = default, type = type))
}
textModeChoices <- c("wrap", "truncate", "full")
if (missing(textMode)) {
textMode <- setting(NA_character_, "textMode", "wrap", "character")
}
textMode <- tryCatch(match.arg(textMode, textModeChoices), error = function(e) {
stopIllegalArgument("'textMode' must be wrap, truncate or full: ", conditionMessage(e),
functionName = "summary.TrialComparison", parameter = "textMode", value = textMode,
constraint = "one of wrap, truncate, full", diagnosticId = "comparison.summary_text_mode_invalid",
context = list(allowedValues = textModeChoices))
})
width <- setting(width, "width", getOption("width", 80L), "numeric")
.assertComparisonLimit(width, "width", "summary.TrialComparison")
if (width < 20L) {
stopArgumentOutOfRange("'width' must be at least 20 characters",
functionName = "summary.TrialComparison", parameter = "width", value = width,
lowerBound = 20L, constraint = "width >= 20", diagnosticId = "comparison.summary_width_invalid")
}
showAll <- setting(showAll, "showAll", FALSE, "logical")
.assertIsSingleLogical(showAll, "showAll")
if (missing(showDataType)) {
showDataType <- setting(NA, "showDataType", FALSE, "logical")
} else {
showDataType <- setting(showDataType, "showDataType", FALSE, "logical")
}
.assertIsSingleLogical(showDataType, "showDataType")
limits <- list(
maxParameters = maxParameters,
maxProfiles = maxProfiles,
maxObjects = maxObjects,
maxValues = maxValues,
maxTableColumns = maxTableColumns)
defaults <- c(maxParameters = 12L, maxProfiles = 3L, maxObjects = 6L, maxValues = 4L, maxTableColumns = 4L)
for (parameter in names(limits)) {
limits[[parameter]] <- setting(limits[[parameter]], parameter, defaults[[parameter]], "numeric")
.assertComparisonLimit(limits[[parameter]], parameter, "summary.TrialComparison")
}
data <- .getTrialComparisonData(object$getObjects(),
harmonizeColumnNames = harmonizeColumnNames)
info <- .getTrialComparisonInfo(object, data)
attr(info, "harmonizeColumnNames") <- harmonizeColumnNames
getComparisonParameterDescriptions(info[FALSE, ], digits = digits)
return(TrialComparisonSummary$new(object, info,
maxParameters = limits$maxParameters, maxProfiles = limits$maxProfiles,
maxObjects = limits$maxObjects, maxValues = limits$maxValues,
maxTableColumns = limits$maxTableColumns,
digits = digits, output = match.arg(output), harmonizeColumnNames = harmonizeColumnNames,
textMode = textMode, width = width, showAll = showAll, showDataType = showDataType))
}
#'
#' @title
#' Update a Trial Comparison Summary
#'
#' @rdname summary.TrialComparison
#'
#' @description
#' The `TrialComparisonSummary` method refreshes a summary from its underlying
#' comparison, retaining stored display settings unless explicitly overridden.
#' This also supports `%vs%` chains followed by `summary(...)`.
#'
#' @export
#'
summary.TrialComparisonSummary <- function(object, ...) {
parameterNames <- object$.getInputParameters()
arguments <- lapply(parameterNames, function(name) {
return(object[[name]])
})
names(arguments) <- parameterNames
overrides <- list(...)
arguments <- arguments[!names(arguments) %in% names(overrides)]
return(do.call(summary.TrialComparison,
c(list(object = object$object), arguments, overrides)))
}
.getComparisonSummaryHarmonization <- function(object) {
return(object$harmonizeColumnNames)
}
#'
#' @name TrialComparisonSummary
#'
#' @title
#' Summary of a Trial Comparison
#'
#' @description
#' A snapshot of comparison profiles and display settings, created by
#' [summary.TrialComparison()] or [compare()].
#'
#' @template field_parameterInfo_comparisonSummary
#' @template field_digits_comparisonSummary
#' @template field_maxParameters_comparisonSummary
#' @template field_maxProfiles_comparisonSummary
#' @template field_maxObjects_comparisonSummary
#' @template field_maxValues_comparisonSummary
#' @template field_maxTableColumns_comparisonSummary
#' @template field_harmonizeColumnNames_comparisonSummary
#' @template field_textMode_comparisonSummary
#' @template field_width_comparisonSummary
#' @template field_showAll_comparisonSummary
#' @template field_showDataType_comparisonSummary
#' @template field_object_comparisonSummary
#' @template field_title_comparisonSummary
#' @template field_header_comparisonSummary
#' @template field_summaryItems_comparisonSummary
#' @template field_intervalFormat_comparisonSummary
#' @template field_justify_comparisonSummary
#' @template field_output_comparisonSummary
#' @template field_markdown_comparisonSummary
#'
#' @details
#' Inherits from `SummaryFactory` and `ParameterSet`. Each resolved summary
#' input is classified centrally as a default or user-defined parameter.
#' [getObjectRCode()] includes only user-defined inputs unless
#' `includeDefaultParameters = TRUE`. Settings resolved from R options or
#' environment variables are retained when they differ from package defaults.
#' `showAll` affects rendering without replacing the stored limits or text mode.
#' Markdown tables place coordinates in rows and profiles in columns, using at
#' most `maxTableColumns` profile columns per block even with `showAll = TRUE`.
#' Coordinate columns repeat in each block. Scalar profiles use one-row tables.
#' Long profile labels are listed above the tables with short column references.
#' Profiles with incompatible dimensions are displayed in separate tables.
#' The underlying comparison is retained by reference, whereas profiles and
#' display labels are snapshots. Recompute the summary after changing objects.
#'
#' @seealso [getComparison()], [compare()]
#'
#' @keywords internal
#'
TrialComparisonSummary <- R6::R6Class("TrialComparisonSummary",
inherit = SummaryFactory,
private = list(
objectNames = NULL,
objectTypes = NULL,
objectLabel = NULL,
overview = NULL
),
public = list(
parameterInfo = NULL,
digits = NA_integer_,
maxParameters = NA_integer_,
maxProfiles = NA_integer_,
maxObjects = NA_integer_,
maxValues = NA_integer_,
maxTableColumns = NA_integer_,
harmonizeColumnNames = TRUE,
textMode = NA_character_,
width = NA_integer_,
showAll = NA,
showDataType = FALSE,
initialize = function(object, info, maxParameters, maxProfiles, maxObjects, maxValues,
digits, output, harmonizeColumnNames, textMode, width, showAll, showDataType, maxTableColumns) {
super$initialize(object = object, output = output)
self$title <- .getTrialComparisonTitle(object$getObjects(), summaryEnabled = TRUE)
self$parameterInfo <- info
.setValueAndParameterType(self, "digits", digits, NA_integer_)
.setValueAndParameterType(self, "maxParameters", maxParameters, 12L)
.setValueAndParameterType(self, "maxProfiles", maxProfiles, 3L)
.setValueAndParameterType(self, "maxObjects", maxObjects, 6L)
.setValueAndParameterType(self, "maxValues", maxValues, 4L)
.setValueAndParameterType(self, "maxTableColumns", maxTableColumns, 4L)
.setValueAndParameterType(self, "output", output, "all")
.setValueAndParameterType(self, "harmonizeColumnNames", harmonizeColumnNames, TRUE)
.setValueAndParameterType(self, "textMode", textMode, "wrap")
.setValueAndParameterType(self, "width", width, 80L)
.setValueAndParameterType(self, "showAll", showAll, FALSE)
.setValueAndParameterType(self, "showDataType", showDataType, FALSE)
self$.setParameterType("parameterInfo", C_PARAM_GENERATED)
self$.setParameterType("title", C_PARAM_GENERATED)
private$objectNames <- names(object)
private$objectTypes <- vapply(object$getObjects(), .comparisonObjectType, character(1))
objects <- object$getObjects()
private$objectLabel <- if (length(objects) > 0L &&
all(vapply(objects, inherits, logical(1), "SimulationResults"))) {
"Simulation"
} else if (length(objects) > 0L &&
all(vapply(objects, inherits, logical(1), "TrialDesign"))) {
"Design"
} else {
"Result"
}
private$overview <- .comparisonOverview(object$getObjects())
},
.show = function(..., consoleOutputEnabled = TRUE) {
.showTrialComparisonSummary(self, private, consoleOutputEnabled)
return(invisible(self))
}
)
)
.comparisonProfileMatrix <- function(
profiles,
labels,
maxValues,
digits,
reference,
wrapColumnLabels = FALSE) {
coordinates <- lapply(profiles, function(profile) {
keys <- setdiff(names(profile), "value")
if (length(keys) == 0) {
return(rep(list("Value"), min(nrow(profile), maxValues)))
}
return(lapply(seq_len(min(nrow(profile), maxValues)), function(i) {
return(vapply(keys, function(key) {
return(paste(
.comparisonCaption(key, tableOutputEnabled = TRUE),
.comparisonPreview(profile[[key]][i], truncate = FALSE)
))
}, character(1)))
}))
})
positions <- lapply(coordinates, function(profile) {
return(vapply(profile, function(parts) {
return(paste(parts, collapse = "; "))
}, character(1)))
})
columns <- unique(unlist(positions, use.names = FALSE))
omitted <- vapply(profiles, function(profile) {
return(max(0L, nrow(profile) - maxValues))
}, numeric(1))
if (any(omitted > 0L)) {
columns <- c(columns, "...")
}
values <- matrix("",
nrow = length(profiles), ncol = length(columns),
dimnames = list(labels, columns)
)
for (i in seq_along(profiles)) {
profile <- profiles[[i]]
values[i, match(positions[[i]], columns)] <- vapply(utils::head(profile$value, maxValues), function(value) {
return(.comparisonPreview(value, digits = digits, reference = reference, truncate = FALSE))
}, character(1))
if (omitted[i] > 0L) {
values[i, ncol(values)] <- paste0("... (+", omitted[i], " values; increase maxValues)")
}
}
if (wrapColumnLabels) {
displayLabels <- unlist(lapply(coordinates, function(profile) {
return(vapply(profile, function(parts) {
return(paste(gsub(" ", "\u00a0", parts, fixed = TRUE), collapse = " "))
}, character(1)))
}), use.names = FALSE)
# Match by the original coordinates before replacing display labels.
# Spaces within each dimension are protected; dimensions can wrap freely.
indices <- match(columns, unlist(positions, use.names = FALSE))
matched <- !is.na(indices)
columns[matched] <- displayLabels[indices[matched]]
colnames(values) <- columns
}
return(values)
}
.comparisonScalarLine <- function(row, description, private, limits, digits) {
profiles <- row$profiles[[1L]]
groups <- row$profileGroups[[1L]]
captions <- unique(stats::na.omit(row$paramCaptions[[1L]]))
if (length(profiles) > 4L || row$nProfiles > limits$maxProfiles ||
any(tabulate(groups) > limits$maxObjects) || length(captions) > 1L ||
!all(vapply(profiles, function(profile) {
return(identical(names(profile), "value") && nrow(profile) == 1L &&
(is.numeric(profile$value) || is.character(profile$value) || is.logical(profile$value)))
}, logical(1)))) {
return(NULL)
}
ids <- seq_along(profiles)
labels <- paste(private$objectLabel, ids)
named <- rep(FALSE, length(ids))
if (!is.null(private$objectNames)) {
named <- !is.na(private$objectNames) & nzchar(private$objectNames)
labels[named] <- private$objectNames[named]
}
comparison <- if (any(named)) {
paste(labels, collapse = " vs. ")
} else {
paste(private$objectLabel, paste(ids, collapse = " vs. "))
}
values <- vapply(profiles, function(profile) {
return(.comparisonPreview(profile$value, digits = digits,
reference = row$values[[1L]], truncate = FALSE))
}, character(1))
line <- paste0(" ", description, " (", comparison, "): ", paste(values, collapse = " vs. "))
if (nchar(line, type = "width") > limits$width || grepl("[\r\n]", line)) {
return(NULL)
}
return(line)
}
# Match complete, unformatted coordinates; delimiters and display rounding must
# never merge distinct positions. Integer and double coordinates are equivalent.
.comparisonCoordinateIds <- function(profile, keys) {
return(vapply(seq_len(nrow(profile)), function(i) {
coordinates <- lapply(keys, function(key) {
value <- profile[[key]][i]
if (is.numeric(value)) {
value <- as.numeric(value)
} else if (is.factor(value)) {
value <- as.character(value)
}
return(value)
})
return(paste(as.character(serialize(coordinates, NULL, version = 2)), collapse = ""))
}, character(1)))
}
.comparisonMissingProfile <- function(profile) {
return(identical(names(profile), "value") && nrow(profile) == 1L &&
is.na(profile$value) && !is.nan(profile$value))
}
.comparisonRedundantCoordinates <- function(profiles) {
keys <- c("categoryType", "category", "situation")
return(keys[vapply(keys, function(key) {
values <- unlist(lapply(profiles, function(profile) {
return(profile[[key]])
}), use.names = FALSE)
return(length(unique(values)) == 1L)
}, logical(1))])
}
.comparisonCoordinateDisplay <- function(coordinates, allProfiles) {
allProfiles <- Filter(function(profile) {
return(!.comparisonMissingProfile(profile))
}, allProfiles)
keys <- names(coordinates)
constants <- character()
if (all(vapply(allProfiles, function(profile) {
return(nrow(profile) > 0L && setequal(setdiff(names(profile), "value"), keys))
}, logical(1)))) {
constants <- keys[vapply(keys, function(key) {
values <- unlist(lapply(allProfiles, function(profile) {
return(profile[[key]])
}), use.names = FALSE)
return(length(unique(values)) == 1L)
}, logical(1))]
}
captions <- vapply(keys, .comparisonCaption, character(1), tableOutputEnabled = TRUE)
names(captions) <- keys
captions[keys %in% c("stage", "stages")] <- "Stage"
redundant <- character()
if ("categoryType" %in% constants && "category" %in% keys) {
categoryType <- coordinates$categoryType[1L]
if (!is.na(categoryType) && categoryType %in% c("comparison", "arm")) {
captions["category"] <- if (categoryType == "comparison") {
"Comparison"
} else {
"Arm"
}
redundant <- "categoryType"
}
}
redundant <- union(redundant, .comparisonRedundantCoordinates(allProfiles))
context <- vapply(setdiff(constants, redundant), function(key) {
return(paste0(captions[[key]], ": ",
.comparisonPreview(coordinates[[key]][1L], truncate = FALSE)))
}, character(1))
varying <- setdiff(keys, constants)
coordinateText <- lapply(varying, function(key) {
return(vapply(coordinates[[key]], .comparisonPreview, character(1), truncate = FALSE))
})
names(coordinateText) <- captions[varying]
return(list(columns = coordinateText, context = context))
}
.comparisonAlignProfileCoordinates <- function(profiles) {
coordinateProfiles <- Filter(function(profile) {
return(!.comparisonMissingProfile(profile))
}, profiles)
schemas <- lapply(coordinateProfiles, function(profile) {
return(setdiff(names(profile), "value"))
})
if (!length(schemas) || !length(Reduce(intersect, schemas))) {
return(NULL)
}
keys <- Reduce(union, schemas)
sharedKeys <- Reduce(intersect, schemas)
if (all(vapply(schemas, setequal, logical(1), keys))) {
return(NULL)
}
# A display-only sentinel distinguishes an inapplicable coordinate from stored NA.
marker <- "<not applicable>"
values <- unlist(lapply(coordinateProfiles, function(profile) {
return(unlist(profile[setdiff(names(profile), "value")], use.names = FALSE))
}), use.names = FALSE)
while (marker %in% values) {
marker <- paste0(marker, ".")
}
aligned <- lapply(profiles, function(profile) {
if (.comparisonMissingProfile(profile)) {
return(profile)
}
for (key in keys) {
if (!key %in% names(profile)) {
profile[[key]] <- rep(marker, nrow(profile))
} else if (!key %in% sharedKeys && is.numeric(profile[[key]])) {
values <- profile[[key]]
profile[[key]] <- sprintf("%.17g", values)
profile[[key]][is.na(values)] <- NA_character_
} else if (!key %in% sharedKeys) {
profile[[key]] <- as.character(profile[[key]])
}
}
return(profile[c(keys, "value")])
})
return(list(profiles = aligned, marker = marker))
}
.comparisonProfileTable <- function(profiles, labels, allProfiles, maxValues, digits, reference) {
alignment <- .comparisonAlignProfileCoordinates(allProfiles)
if (!is.null(alignment)) {
# Include every profile when choosing the sentinel and deciding which axes vary.
indices <- vapply(profiles, function(profile) {
return(which(vapply(allProfiles, identical, logical(1), profile))[1L])
}, integer(1))
table <- .comparisonProfileTable(alignment$profiles[indices], labels,
alignment$profiles, maxValues, digits, reference)
if (!is.null(table)) {
table$notApplicable <- any(table$cells[, seq_len(table$nCoordinates), drop = FALSE] == alignment$marker)
table$cells[table$cells == alignment$marker] <- "-"
categoryTypes <- unique(unlist(lapply(allProfiles, function(profile) {
return(profile$categoryType)
}), use.names = FALSE))
typeColumn <- match(.comparisonCaption("categoryType", tableOutputEnabled = TRUE),
colnames(table$cells))
categoryColumn <- match(.comparisonCaption("category", tableOutputEnabled = TRUE),
colnames(table$cells))
if (length(categoryTypes) == 1L && categoryTypes %in% c("arm", "comparison") &&
!is.na(typeColumn) && !is.na(categoryColumn)) {
colnames(table$cells)[categoryColumn] <- if (categoryTypes == "arm") {
"Arm"
} else {
"Comparison"
}
table$cells <- table$cells[, -typeColumn, drop = FALSE]
table$nCoordinates <- table$nCoordinates - 1L
}
sharedKeys <- Reduce(intersect, lapply(allProfiles[!vapply(allProfiles,
.comparisonMissingProfile, logical(1))], function(profile) {
return(setdiff(names(profile), "value"))
}))
captions <- vapply(sharedKeys, .comparisonCaption, character(1), tableOutputEnabled = TRUE)
captions[sharedKeys %in% c("stage", "stages")] <- "Stage"
captions <- intersect(captions, colnames(table$cells)[seq_len(table$nCoordinates)])
if (length(captions)) {
ids <- .comparisonCoordinateIds(as.data.frame(table$cells), captions)
table$cells <- table$cells[order(match(ids, unique(ids))), , drop = FALSE]
}
}
return(table)
}
missing <- vapply(profiles, .comparisonMissingProfile, logical(1))
coordinateProfiles <- profiles[!missing]
if (!length(coordinateProfiles)) {
return(NULL)
}
keys <- setdiff(names(coordinateProfiles[[1L]]), "value")
if (!length(keys) || !all(vapply(profiles, function(profile) {
return(.comparisonMissingProfile(profile) ||
(nrow(profile) > 0L && setequal(setdiff(names(profile), "value"), keys)))
}, logical(1)))) {
return(NULL)
}
ids <- lapply(profiles, function(profile) {
if (.comparisonMissingProfile(profile)) {
return(character())
}
return(.comparisonCoordinateIds(profile, keys))
})
if (any(vapply(ids, anyDuplicated, integer(1)) > 0L)) {
return(NULL)
}
shownIds <- lapply(ids, utils::head, n = maxValues)
positions <- unique(unlist(shownIds, use.names = FALSE))
coordinates <- do.call(rbind, lapply(coordinateProfiles, function(profile) {
return(utils::head(profile[keys], maxValues))
}))
coordinates <- coordinates[match(positions, unlist(shownIds, use.names = FALSE)), , drop = FALSE]
display <- .comparisonCoordinateDisplay(coordinates, allProfiles)
values <- matrix("<absent>", nrow = length(positions), ncol = length(profiles),
dimnames = list(NULL, labels))
for (i in seq_along(profiles)) {
if (missing[i]) {
values[, i] <- "NA"
next
}
indices <- match(positions, ids[[i]])
present <- !is.na(indices)
displayed <- present & indices <= maxValues
values[present & !displayed, i] <- "<omitted>"
values[displayed, i] <- vapply(profiles[[i]]$value[indices[displayed]], function(value) {
return(.comparisonPreview(value, digits = digits, reference = reference, truncate = FALSE))
}, character(1))
}
cells <- cbind(as.data.frame(display$columns, check.names = FALSE,
row.names = seq_along(positions)), as.data.frame(values, check.names = FALSE))
return(list(cells = as.matrix(cells), context = display$context, nCoordinates = length(display$columns),
omitted = vapply(profiles, function(profile) {
return(max(0L, nrow(profile) - maxValues))
}, numeric(1)), absent = any(values == "<absent>"),
numeric = vapply(profiles, function(profile) {
return(is.numeric(profile$value))
}, logical(1))))
}
.comparisonTableLines <- function(table, width, indent = " ") {
cells <- rbind(colnames(table$cells), table$cells)
widths <- apply(cells, 2L, function(column) {
return(max(nchar(column, type = "width")))
})
if (sum(widths) + 2L * (ncol(cells) - 1L) + nchar(indent) > width) {
return(NULL)
}
right <- c(rep(FALSE, table$nCoordinates), table$numeric)
for (j in seq_len(ncol(cells))) {
cells[, j] <- format(cells[, j], width = widths[j], justify = if (right[j]) {
"right"
} else {
"left"
})
}
return(paste0(indent, apply(cells, 1L, paste, collapse = " ")))
}
.comparisonVerticalLines <- function(table, width, indent = " ") {
keys <- seq_len(table$nCoordinates)
columns <- seq.int(table$nCoordinates + 1L, ncol(table$cells))
labels <- colnames(table$cells)[columns]
lines <- paste0(indent, "Values: ", paste(labels, collapse = " vs. "))
for (i in seq_len(nrow(table$cells))) {
coordinate <- if (length(keys)) {
paste(paste(colnames(table$cells)[keys], table$cells[i, keys]), collapse = ", ")
} else {
"Value"
}
values <- table$cells[i, columns]
line <- paste0(indent, coordinate, ": ", paste(values, collapse = " vs. "))
if (nchar(line, type = "width") <= width) {
lines <- c(lines, line)
} else {
lines <- c(lines, paste0(indent, coordinate, ":"),
paste0(indent, " ", labels, ": ", values))
}
}
return(lines)
}
.showComparisonProfileTable <- function(table, labels, emit, emitTable, width) {
for (line in table$context) {
emit(" ", line, "\n")
}
lines <- .comparisonTableLines(table, width)
if (is.null(lines)) {
for (line in .comparisonVerticalLines(table, width)) {
emit(line, "\n")
}
} else {
# Bypass paragraph wrapping: its whitespace normalization destroys columns.
emitTable(paste0(paste(lines, collapse = "\n"), "\n"))
}
for (i in which(table$omitted > 0L)) {
emit(" ", labels[i], ": ... (+", table$omitted[i], " values)\n")
}
if (any(table$cells == "<omitted>")) {
emit(" <omitted>: value outside this profile's maxValues preview.\n")
}
}
.comparisonScalarTable <- function(profiles, labels, digits, reference) {
if (!all(vapply(profiles, function(profile) {
return(identical(names(profile), "value") && nrow(profile) == 1L)
}, logical(1)))) {
return(NULL)
}
values <- vapply(profiles, function(profile) {
return(.comparisonPreview(profile$value, digits = digits, reference = reference, truncate = FALSE))
}, character(1))
return(list(cells = matrix(values, nrow = 1L, dimnames = list(NULL, labels)),
context = character(), nCoordinates = 0L, omitted = rep(0L, length(profiles)),
absent = FALSE, numeric = vapply(profiles, function(profile) {
return(is.numeric(profile$value))
}, logical(1))))
}
.showComparisonMarkdownTable <- function(summary, table) {
emit <- function(...) {
summary$.cat(..., consoleOutputEnabled = FALSE)
}
labels <- colnames(table$cells)[seq.int(table$nCoordinates + 1L, ncol(table$cells))]
for (context in table$context) {
emit(.escapeMarkdownTableCell(context), "\n\n")
}
columns <- seq_along(labels)
blocks <- split(columns, ceiling(columns / summary$maxTableColumns))
for (b in seq_along(blocks)) {
selected <- blocks[[b]]
if (length(blocks) > 1L) {
emit("Table block ", b, " of ", length(blocks), ".\n\n")
}
cells <- table$cells[, c(seq_len(table$nCoordinates), table$nCoordinates + selected), drop = FALSE]
emit(.escapeMarkdownTableCell(colnames(cells)), tableColumns = ncol(cells))
right <- c(rep(FALSE, table$nCoordinates), table$numeric[selected])
emit(ifelse(right, "---:", ":---"), tableColumns = ncol(cells))
for (i in seq_len(nrow(cells))) {
emit(.escapeMarkdownTableCell(cells[i, ]), tableColumns = ncol(cells))
}
emit("\n")
}
for (i in which(table$omitted > 0L)) {
emit(.escapeMarkdownTableCell(labels[i]), ": ... (+", table$omitted[i], " values)\n\n")
}
if (any(table$cells == "<omitted>")) {
emit("<omitted>: value outside this profile's maxValues preview.\n\n")
}
}
.showComparisonMarkdownProfiles <- function(summary, profiles, labels, allProfiles, maxValues, reference,
registerTable = NULL) {
showTable <- function(table) {
if (!is.null(registerTable)) {
registerTable(table)
}
.showComparisonMarkdownTable(summary, table)
}
# Short references are local to this parameter and never replace the full labels silently.
long <- nchar(labels, type = "width") > 24L | grepl("[\r\n]", labels)
if (any(long)) {
short <- paste("Profile", seq_along(labels))
for (i in seq_along(labels)) {
summary$.cat(short[i], ": ", .escapeMarkdownTableCell(labels[i]), "\n\n",
consoleOutputEnabled = FALSE)
}
labels <- short
}
table <- .comparisonScalarTable(profiles, labels, summary$digits, reference)
if (is.null(table)) {
table <- .comparisonProfileTable(profiles, labels, allProfiles, maxValues, summary$digits, reference)
}
if (!is.null(table)) {
showTable(table)
return(invisible())
}
# Incompatible dimensions cannot safely share rows. Keep each exact profile intact.
for (i in seq_along(profiles)) {
table <- .comparisonScalarTable(profiles[i], labels[i], summary$digits, reference)
if (is.null(table)) {
table <- .comparisonProfileTable(profiles[i], labels[i], profiles[i],
maxValues, summary$digits, reference)
}
if (!is.null(table)) {
showTable(table)
} else {
profile <- profiles[[i]]
keys <- setdiff(names(profile), "value")
shown <- utils::head(profile, maxValues)
cells <- as.matrix(data.frame(lapply(shown, function(values) {
return(vapply(values, function(value) {
return(.comparisonPreview(value, digits = summary$digits, truncate = FALSE))
}, character(1)))
}), check.names = FALSE))
colnames(cells) <- c(vapply(keys, .comparisonCaption, character(1)), labels[i])
showTable(list(cells = cells, context = character(),
nCoordinates = length(keys), numeric = is.numeric(profile$value),
omitted = max(0L, nrow(profile) - maxValues), absent = FALSE))
}
}
}
.comparisonProfileDescription <- function(labels, captions) {
captions[is.na(captions)] <- ""
descriptions <- vapply(unique(captions), function(caption) {
members <- paste(labels[captions == caption], collapse = ", ")
if (nzchar(caption)) {
return(paste0(members, " (", caption, ")"))
}
return(members)
}, character(1))
return(paste(descriptions, collapse = ", "))
}
.showTrialComparisonSummary <- function(summary, private, consoleOutputEnabled) {
summary$.resetCat()
limits <- list(maxParameters = summary$maxParameters, maxProfiles = summary$maxProfiles,
maxObjects = summary$maxObjects, maxValues = summary$maxValues,
textMode = summary$textMode, width = summary$width, showAll = summary$showAll)
if (limits$showAll) {
limits[c("maxParameters", "maxProfiles", "maxObjects", "maxValues")] <- .Machine$integer.max
if (limits$textMode == "truncate") {
limits$textMode <- "full"
}
}
shortened <- FALSE
text <- function(value, width) {
if (!consoleOutputEnabled || limits$textMode != "truncate") {
return(value)
}
shortened <<- shortened || any(nchar(value) > width)
return(.comparisonText(value, width))
}
preview <- function(values, maxValues = 4L, digits = NA_integer_, reference = NULL) {
return(.comparisonPreview(values, maxValues, digits, reference, truncate = FALSE))
}
emit <- function(...) {
value <- paste0(..., collapse = "")
if (consoleOutputEnabled && limits$textMode == "wrap") {
lines <- strsplit(value, "\n", fixed = TRUE)[[1L]]
lines <- vapply(lines, function(line) {
indent <- nchar(line) - nchar(sub("^ *", "", line))
return(paste(strwrap(line, width = limits$width, indent = indent,
exdent = indent + 4L), collapse = "\n"))
}, character(1))
value <- paste(lines, collapse = "\n")
value <- paste0(value, "\n")
}
summary$.cat(value, consoleOutputEnabled = consoleOutputEnabled)
}
parameterIndent <- if (consoleOutputEnabled) {
" "
} else {
""
}
profileIndent <- if (consoleOutputEnabled) {
" "
} else {
" "
}
info <- summary$parameterInfo
different <- which(info$nProfiles > 1L)
common <- which(info$nProfiles == 1L & !info$isEmpty)
empty <- which(info$nProfiles == 1L & info$isEmpty)
if (summary$output %in% c("all", "title")) {
summary$.cat(summary$title, "\n\n", heading = 1, consoleOutputEnabled = consoleOutputEnabled)
}
if (summary$output %in% c("all", "overview")) {
emit(private$overview, "\n")
if (length(private$objectTypes) > 0L && (is.null(private$objectNames) ||
any(is.na(private$objectNames) | !nzchar(private$objectNames)))) {
emit(private$objectLabel, " numbers follow the comparison input order.\n")
}
overview <- .concatenateSummaryText(
paste("The comparison identifies", length(different), if (length(different) == 1L) {
"differing parameter"
} else {
"differing parameters"
}),
paste(length(common), if (length(common) == 1L) {
"shared parameter or profile"
} else {
"shared parameters or profiles"
}),
sep = " and "
)
if (length(empty)) {
overview <- paste0(overview, ". ", length(empty), if (length(empty) == 1L) {
" parameter is empty"
} else {
" parameters are empty"
})
}
emit(overview, ".\n")
if (length(common)) {
emit(
"Shared (examples): ", text(
paste(utils::head(info$paramCaption[common], if (limits$showAll) {
length(common)
} else {
6L
}), collapse = ", "), 130L),
if (length(common) > 6L && !limits$showAll) {
", ... (all shared captions: showAll = TRUE)"
} else {
"."
}, "\n"
)
}
}
if (!summary$output %in% c("all", "body")) {
if (shortened) {
emit("Text shortened; use textMode = \"wrap\" or \"full\", or increase width.\n")
}
return(invisible(summary))
}
if (!length(different)) {
emit("\nNo parameter differences between the objects.\n")
}
roles <- c("Object types and scope", "Inputs and design settings", "Results and derived parameters")
ordered <- unlist(lapply(roles, function(role) {
different[info$role[different] == role]
}), use.names = FALSE)
# Share the display budget across sections so a long input list cannot hide
# every result difference. Within each section preserve ParameterSet order.
sections <- lapply(roles, function(role) {
different[info$role[different] == role]
})
interleaved <- unlist(lapply(seq_len(max(c(0L, lengths(sections)))), function(position) {
unlist(lapply(sections, function(indices) {
indices[position][!is.na(indices[position])]
}), use.names = FALSE)
}), use.names = FALSE)
shown <- utils::head(interleaved, limits$maxParameters)
shownAbsent <- FALSE
shownNotApplicable <- FALSE
registerTable <- function(table) {
shownAbsent <<- shownAbsent || isTRUE(table$absent)
shownNotApplicable <<- shownNotApplicable || isTRUE(table$notApplicable)
}
shownNA <- FALSE
valuesOmitted <- FALSE
sectionStarted <- summary$output == "all"
for (role in roles) {
indices <- shown[info$role[shown] == role]
if (!length(indices)) {
next
}
if (sectionStarted) {
emit("\n")
}
summary$.cat(paste0(role, ":\n"), heading = 2, consoleOutputEnabled = consoleOutputEnabled)
sectionStarted <- TRUE
for (i in indices) {
row <- info[i, , drop = FALSE]
# The common descriptions supply type/role labels, without unbounded values.
labelInfo <- row
labelInfo$isBinary <- labelInfo$isSingleValue <- FALSE
labelInfo$values <- list(character())
labelInfo$paramName <- row$paramCaption
description <- if (summary$showDataType) {
getComparisonParameterDescriptions(labelInfo, digits = summary$digits)
} else {
row$paramCaption
}
if (!consoleOutputEnabled) {
description <- sub(": ", " - ", description, fixed = TRUE)
}
emit("\n")
scalarLine <- if (consoleOutputEnabled) {
.comparisonScalarLine(row, description, private, limits, summary$digits)
} else {
NULL
}
if (!is.null(scalarLine)) {
emit(scalarLine, "\n")
shownNA <- shownNA || any(vapply(row$profiles[[1L]], function(profile) {
return(anyNA(profile$value))
}, logical(1)))
next
}
if (consoleOutputEnabled) {
emit(parameterIndent, text(description, 75L), " [", row$nProfiles, " profiles]\n")
} else {
summary$.cat(parameterIndent, description, " [", row$nProfiles, " profiles]\n",
heading = 3, consoleOutputEnabled = FALSE)
}
groups <- row$profileGroups[[1L]]
profileLabels <- character()
profileDescriptions <- character()
displayedProfiles <- list()
for (group in seq_len(min(row$nProfiles, limits$maxProfiles))) {
members <- which(groups == group)
ids <- utils::head(members, limits$maxObjects)
labels <- paste(private$objectLabel, ids)
named <- rep(FALSE, length(ids))
if (!is.null(private$objectNames)) {
objectNames <- private$objectNames[ids]
named <- !is.na(objectNames) & nzchar(objectNames)
labels[named] <- text(objectNames[named], 18L)
}
captions <- row$paramCaptions[[1L]]
plainLabels <- labels
variedCaptions <- length(unique(stats::na.omit(captions))) > 1L
membersText <- if (variedCaptions) {
.comparisonProfileDescription(labels, captions[ids])
} else {
paste(labels, collapse = ", ")
}
if (!variedCaptions && !any(named) && length(members) > 1L) {
membersText <- paste(private$objectLabel, paste(ids, collapse = ", "))
}
if (length(members) > limits$maxObjects) {
omitted <- length(members) - limits$maxObjects
omittedLabel <- if (omitted == 1L) {
"object"
} else {
"objects"
}
membersText <- paste0(membersText, ", ... (+", omitted, " ", omittedLabel, "; increase maxObjects)")
}
if (variedCaptions) {
profileDescriptions <- c(profileDescriptions, membersText)
membersText <- paste(plainLabels, collapse = ", ")
}
profile <- row$profiles[[1L]][[members[1L]]]
valuesOmitted <- valuesOmitted || nrow(profile) > limits$maxValues
keys <- setdiff(names(profile), "value")
shownNA <- shownNA || anyNA(utils::head(profile$value, limits$maxValues)) ||
any(vapply(keys, function(key) {
anyNA(utils::head(profile[[key]], limits$maxValues))
}, logical(1)))
profileLabels <- c(profileLabels, membersText)
displayedProfiles[[length(displayedProfiles) + 1L]] <- profile
}
for (j in seq_along(profileDescriptions)) {
emit(profileIndent, profileDescriptions[j], "\n")
}
if (length(profileDescriptions)) {
emit("\n")
}
if (consoleOutputEnabled) {
table <- .comparisonProfileTable(displayedProfiles, profileLabels, row$profiles[[1L]],
limits$maxValues, summary$digits, row$values[[1L]])
if (!is.null(table)) {
registerTable(table)
.showComparisonProfileTable(table, profileLabels, emit,
function(value) {
summary$.cat(value, consoleOutputEnabled = TRUE)
}, limits$width)
} else {
for (j in seq_along(displayedProfiles)) {
profile <- displayedProfiles[[j]]
keys <- setdiff(names(profile), c("value",
.comparisonRedundantCoordinates(row$profiles[[1L]])))
values <- preview(profile$value, limits$maxValues, summary$digits, row$values[[1L]])
if (length(keys)) {
positions <- vapply(keys, function(key) {
return(paste0(.comparisonCaption(key), " = ",
preview(profile[[key]], limits$maxValues)))
}, character(1))
values <- paste0("[", paste(positions, collapse = "; "), "] ", values)
}
emit(profileIndent, text(paste0(profileLabels[j], ": ", values),
limits$width - nchar(profileIndent)), "\n")
}
}
} else {
.showComparisonMarkdownProfiles(summary, displayedProfiles, profileLabels,
row$profiles[[1L]], limits$maxValues, row$values[[1L]], registerTable)
}
if (row$nProfiles > limits$maxProfiles) {
emit(profileIndent, "... ", row$nProfiles - limits$maxProfiles, " more profiles; increase maxProfiles or use showAll = TRUE.\n")
}
}
}
emit("\n")
omittedParameters <- length(ordered) - length(shown)
if (omittedParameters > 0L || valuesOmitted) {
availability <- character()
controls <- character()
if (omittedParameters > 0L) {
availability <- paste0(omittedParameters, if (omittedParameters == 1L) {
" more differing parameter"
} else {
" more differing parameters"
})
controls <- "maxParameters"
}
if (valuesOmitted) {
availability <- c(availability, "More values available")
controls <- c(controls, "maxValues")
}
emit(paste(availability, collapse = ". "), "; increase ",
paste(controls, collapse = " and "), " or use showAll = TRUE.\n")
emit("\n")
}
if (length(shown)) {
summary$.cat("Legend:\n", heading = 2, consoleOutputEnabled = consoleOutputEnabled)
legendIndent <- if (consoleOutputEnabled) {
parameterIndent
} else {
profileIndent
}
emit(legendIndent, "Profiles compare exact values on their applicable coordinates.\n")
if (shownAbsent) {
marker <- if (consoleOutputEnabled) {
"<absent>"
} else {
"<absent>"
}
emit(legendIndent, marker, ": coordinate not present in this profile.\n")
}
if (shownNotApplicable) {
emit(legendIndent, "-: coordinate not applicable to this profile; values are not repeated across categories.\n")
}
if (shownNA) {
emit(legendIndent, "NA: missing/unavailable.\n")
}
if (!is.na(summary$digits)) {
emit(legendIndent, "Display values are rounded.\n")
}
emit("\n")
}
if (shortened) {
emit("Text shortened; use textMode = \"wrap\" or \"full\", or increase width.\n")
}
emit("Complete display: summary(x, showAll = TRUE).\n")
if (.getComparisonSummaryHarmonization(summary)) {
emit("Full data: as.data.frame(x). Exact profiles: summary(x)$parameterInfo.\n")
} else {
emit("Full data: as.data.frame(x, harmonizeColumnNames = FALSE).\n")
emit("Exact profiles: summary(x, harmonizeColumnNames = FALSE)$parameterInfo.\n")
}
return(invisible(summary))
}
#'
#' @title
#' Plot a Trial Comparison
#'
#' @description
#' Plots selected variables from a trial comparison.
#'
#' @param x A `TrialComparison` or its summary.
#' @param xAxis,yAxis Optional axis column names or captions. Omitted axes are
#' selected only when there is exactly one candidate: inputs/design settings
#' are preferred for x, results for y, then other varying numeric columns.
#' Identifier columns are excluded; stages remain eligible axes. `yAxis`
#' may also explicitly select multiple numeric parameters. Their axis sides
#' can be controlled through `yAxisSide` passed to [plot.TrialComparison()].
#' @param main Plot title. When omitted, generated from the original objects.
#' NULL or NA hides the title.
#' @param xlab,ylab Axis labels. NA uses automatic parameter captions; NULL hides
#' the label. `ylab` overrides the primary y-axis label, including a single
#' right-positioned axis. A secondary y axis retains its automatic caption.
#' @param category Optional column names defining categories. Multiple columns
#' define joint categories. NULL selects automatically; NA_character_ or
#' character(0) disables categories.
#' @param group Optional column name defining an additional grouping.
#' @param ... Arguments passed to [plot.TrialComparison()], including categories,
#' grouping, titles and line/point settings. Explicit axis selections prevail.
#' @param data Optional comparison data frame with additional annotation columns.
#' Rows must follow the order of `as.data.frame(x)`. Without custom data,
#' summary plots retain the summary's column-name harmonization setting.
#'
#' @return A ggplot object. Ambiguous selections raise an error listing candidate
#' descriptions and a concrete example.
#'
#' @details
#' `xAxis`, `yAxis`, `category`, and `group` accept technical column names,
#' captions from the parameter dictionary, and object-specific captions as in
#' [fetch()]. For example, `"Alternative"` and `"Alternatives"` both select
#' `alternative`. Names may also be unquoted, including inside `c(...)`.
#' Defined variables and other expressions are evaluated in the calling environment.
#' Exact column names take precedence over captions. Other names must resolve
#' unambiguously to a column present in the comparison export; harmonized names
#' are taken into account. With fixed plans alone, `"Number of subjects"` can
#' select `nFixed`. Unknown names, ambiguous captions and duplicate selections
#' (including two aliases for one column) raise selection errors.
#'
#' @examples
#' comparison <- getSampleSizeMeans(alternative = 0.22, stDev = 0.5) |>
#' compare(getSampleSizeMeans(alternative = 0.44, stDev = 1)) |>
#' compare(getSampleSizeMeans(alternative = 0.59, stDev = 1))
#' plot(comparison,
#' xAxis = "Alternative",
#' yAxis = c("Number of subjects", "Critical values (treatment effect scale)"),
#' category = "Standard deviation"
#' )
#' plot(comparison, xAxis = alternative, yAxis = numberOfSubjects, group = stDev)
#'
#' @export
#'
plot.TrialComparison <- function(
x,
xAxis = NULL,
yAxis = NULL,
...,
data = NULL,
category = NULL,
group = NULL,
main = NULL,
xlab = NA_character_,
ylab = NA_character_) {
xAxis <- .comparisonPlotColumnArgument(substitute(xAxis), parent.frame())
yAxis <- .comparisonPlotColumnArgument(substitute(yAxis), parent.frame())
category <- .comparisonPlotColumnArgument(substitute(category), parent.frame())
group <- .comparisonPlotColumnArgument(substitute(group), parent.frame())
if (missing(main)) {
main <- .toCapitalizedSingleCharacter(.getTrialComparisonTitle(x$getObjects()))
}
if (!is.null(data)) {
expectedRows <- nrow(as.data.frame(x))
if (!is.data.frame(data) || nrow(data) != expectedRows) {
stopIllegalDataInput("'data' must be a data frame with one row per comparison situation",
functionName = "plot.TrialComparison", parameter = "data", value = data,
constraint = "a data frame with one row per comparison situation",
diagnosticId = "comparison.plot_data_rows_invalid",
context = list(expectedRows = expectedRows, actualRows = NROW(data))
)
}
return(.plotComparison(data,
xAxis = xAxis,
yAxis = yAxis,
category = category, group = group,
main = main, xlab = xlab, ylab = ylab,
objects = x$getObjects(),
...
))
}
return(.plotComparison(x,
xAxis = xAxis, yAxis = yAxis,
category = category, group = group,
main = main, xlab = xlab, ylab = ylab, ...
))
}
#'
#' @title
#' Plot a Trial Comparison
#'
#' @description
#' The summary method plots the objects contained in the comparison.
#'
#' @rdname plot.TrialComparison
#'
#' @param showSummary If TRUE, also print the summary before creating its plot.
#'
#' @export
#'
plot.TrialComparisonSummary <- function(
x,
xAxis = NULL,
yAxis = NULL,
...,
showSummary = FALSE,
category = NULL,
group = NULL,
data = NULL) {
xAxis <- .comparisonPlotColumnArgument(substitute(xAxis), parent.frame())
yAxis <- .comparisonPlotColumnArgument(substitute(yAxis), parent.frame())
category <- .comparisonPlotColumnArgument(substitute(category), parent.frame())
group <- .comparisonPlotColumnArgument(substitute(group), parent.frame())
.assertIsSingleLogical(showSummary, "showSummary")
if (showSummary) {
print(x)
}
if (is.null(data) && !.getComparisonSummaryHarmonization(x)) {
data <- as.data.frame(x$object, harmonizeColumnNames = FALSE)
}
return(plot(x$object,
xAxis = xAxis, yAxis = yAxis,
category = category, group = group, data = data, ...
))
}
.comparisonHasConsumerCall <- function(calls) {
any(vapply(calls, function(call) {
if (!is.call(call)) {
return(FALSE)
}
name <- call[[1L]]
if (is.call(name) && as.character(name[[1L]]) %in% c("::", ":::")) {
name <- name[[3L]]
}
is.symbol(name) && as.character(name) %in%
c("summary", "summary.TrialComparison", "plot", "plot.TrialComparison")
}, logical(1)))
}
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.