R/plots.R

In CompRiskRel: Reliability and Competing Risks Analysis under Hybrid Censoring

#' Diagnostic Plots for Censored Data Schemes
#'
#' Produces 3 diagnostic plots (Histogram with PDF overlay, Dot plot, and ACF plot) to verify sample distributional properties and independence.
#'
#' @param data Object of class \code{comp_risk_rel_data} or a numeric vector of failure times.
#' @param pdf Optional probability density function to overlay on histogram.
#' @param main Overall plot title.
#'
#' @return No return value, called for side effects (renders diagnostic plots).
#' @export
#'
#' @examples
#' dat <- gen_type1_hybrid(
#'   pdf = function(x) dexp(x, rate = 1), cdf = function(x) pexp(x, rate = 1),
#'   lower = 0, upper = 10, n = 20, r = 10, T_star = 1.5, seed = 123
#' )
#' plot_diagnostics(dat, pdf = function(x) dexp(x, rate = 1))
plot_diagnostics <- function(data, pdf = NULL, main = "Censoring Diagnostic Plots") {
  old_par <- graphics::par(mfrow = c(1, 3))
  on.exit(graphics::par(old_par))
  
  if (inherits(data, "comp_risk_rel_data")) {
    obs_t <- data$observed_times
    status <- data$censor_status
    scheme_title <- data$scheme
  } else if (is.numeric(data)) {
    obs_t <- data
    status <- rep(1, length(obs_t))
    scheme_title <- "Sample Diagnostics"
  } else {
    stop("Input data must be of class 'comp_risk_rel_data' or numeric.")
  }
  
  # Plot 1: Histogram with optional theoretical PDF curve
  h <- graphics::hist(obs_t, prob = TRUE, main = paste("Histogram:", scheme_title),
                      xlab = "Observed Time", col = "lightcyan", border = "navy")
  if (!is.null(pdf)) {
    x_grid <- seq(min(obs_t), max(obs_t), length.out = 200)
    y_grid <- sapply(x_grid, pdf)
    graphics::lines(x_grid, y_grid, col = "red", lwd = 2)
  }
  
  # Plot 2: Dot Plot (Stripchart)
  graphics::stripchart(obs_t ~ status, method = "jitter", pch = 19, col = c("darkorange", "darkgreen"),
                       main = "Dot Plot (Observed vs Censored)", xlab = "Time", ylab = "Status (0=Cens, 1=Fail)")
  graphics::grid()
  
  # Plot 3: ACF Plot (Autocorrelation Function)
  stats::acf(obs_t, main = "ACF Plot (Sample Independence)", col = "blue", lwd = 2)
  
  invisible(NULL)
}

#' Plot Method for Objects of Class comp_risk_rel_data
#'
#' @param x Object of class \code{comp_risk_rel_data}.
#' @param ... Additional graphical parameters.
#'
#' @return No return value, called for side effects.
#' @export
plot.comp_risk_rel_data <- function(x, ...) {
  plot_diagnostics(x, ...)
}