R/compare_waves_summary_stats.R

In wavecov: Overlap-Aware Workforce Wave Comparisons

#' Compare two waves using summary statistics only
#'
#' When individual-level data are not available, this function computes
#' overlap-aware variance for the change in means using either a reliability
#' assumption or Cauchy-based bounds from supplied summary statistics.
#'
#' @param N0 Workforce size at wave 0.
#' @param N1 Workforce size at wave 1.
#' @param nS Number of stayers (present in both waves).
#' @param sigma2 Common individual-level variance for the relevant population
#'   (used with the reliability method).
#' @param reliability Same-person cross-wave reliability (used with the
#'   reliability method).
#' @param V0_bar Variance of the wave-0 mean (used with the bounds method).
#' @param V1_bar Variance of the wave-1 mean (used with the bounds method).
#' @param method "reliability" or "bounds".
#' @param cov_sign Covariance sign restriction for bounds: "unrestricted" or
#'   "nonnegative".
#' @param overlap_mode Whether to use generic Cauchy bounds or overlap-aware
#'   tightening. Overlap-aware bounds additionally use \code{nS} and
#'   \code{sigma2S} when supplied.
#' @param sigma2S Optional pooled individual-level stayer variance for
#'   overlap-aware bounds.
#' @param level Confidence level for point-estimate intervals or sensitivity
#'   envelopes.
#'
#' @return A "wavecov_result" (reliability) or "wavecov_bounds_result"
#'   (bounds) object. Use \code{print()}, \code{tidy()}, and \code{confint()}
#'   for summaries.
#' @export
compare_waves_summary_stats <- function(N0, N1, nS,
                                        sigma2 = NULL,
                                        reliability = NULL,
                                        V0_bar = NULL,
                                        V1_bar = NULL,
                                        method = c("reliability", "bounds"),
                                        cov_sign = c("unrestricted", "nonnegative"),
                                        overlap_mode = c("generic", "overlap_aware"),
                                        sigma2S = NULL,
                                        level = 0.95) {
  method       <- base::match.arg(method)
  cov_sign     <- base::match.arg(cov_sign)
  overlap_mode <- base::match.arg(overlap_mode)
  
  # Minimal summary shell used by result constructors
  summary <- list(
    N0 = N0,
    N1 = N1,
    nS = nS,
    ybar0 = NA_real_,
    ybar1 = NA_real_,
    V0_ind = NA_real_,
    V1_ind = NA_real_
  )
  
  if (identical(method, "reliability")) {
    
    var_out <- variance_reliability(
      N0        = N0,
      N1        = N1,
      nS        = nS,
      V0_ind    = NULL,
      V1_ind    = NULL,
      sigma2    = sigma2,
      reliability = reliability
    )
    
    res <- new_wavecov_result(
      summary = summary,
      var_out = var_out,
      method  = "reliability",
      level   = level
    )
    
  } else {  # bounds
    
    if (is.null(V0_bar) || is.null(V1_bar)) {
      stop("Bounds method requires V0_bar and V1_bar when using summary statistics.")
    }
    
    bounds <- variance_bounds(
      N0      = N0,
      N1      = N1,
      V0_bar  = V0_bar,
      V1_bar  = V1_bar,
      nS      = if (identical(overlap_mode, "overlap_aware")) nS else NULL,
      V0S_ind = NULL,
      V1S_ind = NULL,
      sigma2S = if (identical(overlap_mode, "overlap_aware")) sigma2S else NULL,
      cov_sign     = cov_sign,
      overlap_mode = overlap_mode
    )
    
    res <- new_wavecov_bounds_result(
      summary = summary,
      bounds  = bounds,
      level   = level
    )
  }
  
  res
}