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.
getComparison(..., objects = NULL)# S3 method for TrialComparison
length(x)
# S3 method for TrialComparison
names(x)
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.
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.
Optional objects, lists of objects, TrialComparison objects,
or TrialComparisonSummary objects.
NULL is treated as an empty list.
A TrialComparison.
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.
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.
compare(), add(), delete(), fetch.TrialComparison(), getObjects()
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")
if (FALSE) {
plot(comparison,
xAxis = "objectNumber",
yAxis = "criticalValues",
plotLineEnabled = FALSE
)
}
Run the code above in your browser using DataLab