Implement S3 classes for function outputs in dubicube

[wlangera]

Background

The dubicube package currently provides functions that operate on processed_cube objects from other packages. All functions return data frames representing bootstrapped results, confidence intervals, or effect classifications.

Currently:

• There is no standard object structure for these outputs.
• Users must inspect raw data frames to understand results.
• Method dispatch (e.g., print, summary, plot) is not available.

Goal: Introduce S3 classes for dubicube outputs to improve clarity, usability, and method dispatch.

Proposed S3 Classes

Function / Output	Proposed S3 Class	Fields / Structure	Methods
cross_validate_cube()	cube_cv	dataframe with LOO or k-fold results, metadata	print, summary, plot
bootstrap_cube()	cube_bootstrap, boot_list (when using boot::boot?)	bootstrap replicates, statistic, metadata	print, summary, plot
calculate_bootstrap_ci()	bootstrap_ci	statistic, CI bounds, method, metadata	print, summary, plot
add_effect_classification()	effect_classification	original data frame + effect class column	print, summary, plot
calculate_acceleration()	acceleration_result	dataframe with acceleration statistics	print, summary, plot

Implementation Plan

1. Define S3 Constructors

   • Example:

     new_cube_bootstrap <- function(df, statistic, n_boot, ...) {
       structure(list(data = df, statistic = statistic, n_boot = n_boot, ...),
                 class = "cube_bootstrap")
     }

2. Implement S3 Methods

   • print() → concise summary of main results.
   • summary() → high-level statistics and CI coverage.
   • plot() → visualization of bootstrap distributions, effect classes, acceleration trends, etc.

3. Update Functions to Return S3 Objects

   • Wrap data frame outputs in the appropriate S3 constructor.
   • Keep raw data frames accessible (e.g., as.data.frame() method) for compatibility.

4. Add Helper Functions

   • is_cube_bootstrap(), is_bootstrap_ci(), etc., for input validation.
   • Optional coercion methods: as.data.frame.cube_bootstrap()

5. Testing

   • Unit tests to ensure correct class assignment.
   • Validate method dispatch (print, summary, plot).

Next Steps

• Create S3 constructors for each result type.
• Implement print(), summary(), and plot() methods.
• Update dubicube functions to return S3 objects.
• Add unit tests for class handling and method dispatch.
• Update documentation and vignettes.

[wlangera]

Example generated with ChatGPT:

Constructor

• Capture the data frame of bootstrap replicates.
• Store metadata: fun, grouping_var, samples, method, ref_group, and processed_cube.
• Keep it flexible for both whole-cube/group-specific and boot::boot() outputs.
• Include a print method showing key info without printing all rows.

Here’s an improved example:

#' Constructor for cube_bootstrap S3 object
#'
#' Wraps bootstrap_cube() output into a structured S3 object
#'
#' @param data A data frame of bootstrap results, or a list of 'boot' objects
#' @param fun The function used to calculate the statistic
#' @param grouping_var Character vector of grouping variable(s)
#' @param samples Number of bootstrap replicates
#' @param method The bootstrap method used
#' @param ref_group Optional reference group
#' @param processed_cube Logical; whether the input was a processed cube
#' @return An object of class 'cube_bootstrap'
#' @export
new_cube_bootstrap <- function(
  data,
  fun,
  grouping_var,
  samples,
  method,
  ref_group = NA,
  processed_cube = TRUE
) {
  # Validate inputs
  stopifnot(is.function(fun))
  stopifnot(is.character(grouping_var))
  stopifnot(is.numeric(samples) && length(samples) == 1)
  stopifnot(is.logical(processed_cube) && length(processed_cube) == 1)

  structure(
    list(
      data = data,
      fun = fun,
      grouping_var = grouping_var,
      samples = samples,
      method = method,
      ref_group = ref_group,
      processed_cube = processed_cube
    ),
    class = "cube_bootstrap"
  )
}

#' Print method for cube_bootstrap
#' @param x cube_bootstrap object
#' @param ... additional arguments (ignored)
#' @export
print.cube_bootstrap <- function(x, ...) {
  cat("cube_bootstrap object\n")
  cat("Bootstrap method:", x$method, "\n")
  cat("Number of replicates:", x$samples, "\n")
  cat("Grouping variable(s):", paste(x$grouping_var, collapse = ", "), "\n")
  if (!is.na(x$ref_group)) cat("Reference group:", x$ref_group, "\n")
  cat("Processed cube input:", x$processed_cube, "\n")
  cat("Number of rows in results:", 
      if(is.data.frame(x$data)) nrow(x$data) else length(x$data), "\n")
  invisible(x)
}

How to use it in bootstrap_cube()

At the end of bootstrap_cube():

result <- bootstrap_cube_raw(...)  # your usual workflow

# Wrap in S3 object
new_cube_bootstrap(
  data = result,
  fun = fun,
  grouping_var = grouping_var,
  samples = samples,
  method = method,
  ref_group = ref_group,
  processed_cube = processed_cube
)