as.data.frame.TrialComparison: Trial Comparison Data Frame

View source: R/class_trial_comparison.R

as.data.frame.TrialComparisonR Documentation

Trial Comparison Data Frame

Description

Converts a trial comparison to a data frame, optionally prepared for reporting.

Usage

## S3 method for class 'TrialComparison'
as.data.frame(
  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"
)

Arguments

x

A TrialComparison.

row.names

Optional row names for the result.

optional

Unused; included for compatibility with as.data.frame().

...

Further arguments. Currently unused.

niceColumnNamesEnabled

Logical. If TRUE, nice looking column names will be used; syntactic names (variable names) otherwise (see make.names).

includeAllParameters

If TRUE, include all parameters supported by the existing data-frame methods of the individual objects.

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.

removeConstantParameters

If TRUE, retain identifiers and only parameters with different object profiles, using the same rules as summary().

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.

removeVariableParameters

If TRUE, return shared parameter profiles once, with stage and situation coordinates where needed, without object identifiers. Cannot be combined with removeConstantParameters = TRUE.

digits

Integer number of decimal places for numeric parameters, or NA to retain full precision. Parameter profiles are compared before rounding.

ceilingEnabled

If TRUE, round sample-size and event-count parameters upwards to integers, using rpact parameter metadata. Variances are excluded.

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.

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.

Value

A data.frame, unrounded and with all columns by default. Reporting modes additionally inherit from TrialComparisonTable for automatic knitr output.


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