R/result_point.R

In wavecov: Overlap-Aware Workforce Wave Comparisons

#' wavecov point-estimate result
#'
#' Internal constructor and methods for overlap-aware change estimates when
#' a point variance estimate is available (linked or reliability methods).
#'
#' @param summary List returned by summarize_panel().
#' @param var_out List returned by variance_linked() or variance_reliability().
#' @param method Character string naming the method ("linked" or "reliability").
#' @param level Confidence level for intervals.
#'
#' @return An object of class "wavecov_result".
#' @keywords internal
new_wavecov_result <- function(summary,
                               var_out,
                               method,
                               level) {
  Delta_hat <- summary$ybar1 - summary$ybar0
  
  se <- base::sqrt(var_out$var_Delta)
  z  <- stats::qnorm(1 - (1 - level) / 2)
  
  ci <- c(Delta_hat - z * se, Delta_hat + z * se)
  
  structure(
    list(
      estimate = Delta_hat,
      se       = se,
      ci       = ci,
      level    = level,
      N0       = summary$N0,
      N1       = summary$N1,
      nS       = summary$nS,
      overlap  = summary$nS / base::min(summary$N0, summary$N1),
      method   = method,
      # mean-level moments
      V0_bar   = var_out$V0_bar,
      V1_bar   = var_out$V1_bar,
      C01_bar  = var_out$C01_bar,
      # individual-level moments
      V0_ind   = summary$V0_ind,
      V1_ind   = summary$V1_ind,
      C01_ind  = var_out$C01_ind,
      # extras when present
      sigma2    = var_out[["sigma2"]],
      reliability = var_out[["reliability"]]
    ),
    class = "wavecov_result"
  )
}

#' @export
print.wavecov_result <- function(x, ...) {
  cat("Wave change estimate:", sprintf("%.4f", x$estimate),
      " (SE =", sprintf("%.4f", x$se), ")\n")
  cat(" ", 100 * x$level, "% CI: [",
      sprintf("%.4f", x$ci[1]), ",",
      sprintf("%.4f", x$ci[2]), "]\n", sep = "")
  cat(" Method:", x$method,
      "| N0 =", x$N0, "N1 =", x$N1,
      "| overlap proportion =", sprintf("%.3f", x$overlap), "\n")
  invisible(x)
}

#' @export
coef.wavecov_result <- function(object, ...) object$estimate

#' @export
vcov.wavecov_result <- function(object, ...) matrix(object$se^2, 1L, 1L)

#' @export
confint.wavecov_result <- function(object, level = object$level, ...) {
  z   <- stats::qnorm(1 - (1 - level) / 2)
  est <- object$estimate
  se  <- object$se
  c(est - z * se, est + z * se)
}

#' Tidy output for wavecov point-estimate results
#'
#' @param x A "wavecov_result" object.
#' @param ... Unused.
#'
#' @return A one-row data frame with change estimates and diagnostics.
#' @export
#' @method tidy wavecov_result
tidy.wavecov_result <- function(x, ...) {
  sigma2_val <- if (is.null(x$sigma2)) NA_real_ else x$sigma2
  rel_val    <- if (is.null(x$reliability)) NA_real_ else x$reliability
  
  data.frame(
    change_estimate       = x$estimate,
    change_variance       = x$se^2,
    change_standard_error = x$se,
    V0_bar = x$V0_bar,
    V1_bar = x$V1_bar,
    C01_bar = x$C01_bar,
    V0_ind  = x$V0_ind,
    V1_ind  = x$V1_ind,
    C01_ind = x$C01_ind,
    N_0     = x$N0,
    N_1     = x$N1,
    n_S     = x$nS,
    overlap = x$overlap,
    method  = x$method,
    sigma2      = sigma2_val,
    reliability = rel_val
  )
}