getComparison: Compare Existing Trial Planning Objects

View source: R/class_trial_comparison.R

getComparisonR Documentation

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.

length() returns the number of objects in the comparison.

names() returns the supplied names of the comparison objects.

Usage

getComparison(..., objects = NULL)

## S3 method for class 'TrialComparison'
length(x)

## S3 method for class 'TrialComparison'
names(x)

Arguments

...

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.

objects

Optional objects, lists of objects, TrialComparison objects, or TrialComparisonSummary objects. NULL is treated as an empty list.

x

A TrialComparison.

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.

Value

An R6 TrialComparison inheriting from ParameterSet. For a single TrialComparisonSummary, its underlying comparison is returned by reference; otherwise a new collection is created.

Returns a TrialComparison object. The following generics (R generic functions) are available for this result object:

  • add() to obtain the field names,

  • delete() to obtain the field names,

  • fetch() to obtain the field names,

  • compare() to obtain the field names,

  • names() to obtain the field names,

  • length() to obtain the field names,

  • print() to print the object,

  • summary() to display a summary of the object,

  • plot() to plot the object,

  • as.data.frame() to coerce the object to a data.frame,

  • as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

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")
## Not run: 
plot(comparison,
    xAxis = "objectNumber",
    yAxis = "criticalValues",
    plotLineEnabled = FALSE
)

## End(Not run)


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