R/sdt.R

In dcorBSS: Distance-Correlation Based Methods for Blind Source Separation and Dependence Analysis

#' Serial Dependence Test Objects and Dependograms
#'
#' Objects of class \code{"sdt"} are returned by [dcor_serial_test()],
#' [hsic_serial_test()] and [dacf_curve()]. They contain components for lagwise
#' dependence measures, which can be plotted as dependograms using [plot()].
#' The objects returned by the two tests also inherit from class \code{"htest"}.
#'
#' The objects returned by the two tests contain the usual \code{"htest"}
#' components. All objects of class \code{"sdt"} contain:
#' \describe{
#'   \item{estimate}{Named vector of lagwise dependence values.}
#'   \item{lags}{Integer vector of lags used.}
#'   \item{measure_name}{Character string naming the dependence measure, for
#'   example \code{"dCor"} or \code{"HSIC"}.}
#' }
#'
#' The plot method displays the lagwise dependence values either as a barplot
#' or as a line plot. For kernel-weighted tests such as \code{type = "H96"},
#' the plot shows the unweighted lagwise dependence values, not the weighted
#' contributions to the test statistic.
#'
#' @param x An object of class \code{"sdt"}.
#' @param type Type of dependogram. Either \code{"bar"} for a barplot or
#'   \code{"line"} for a line plot.
#' @param xlab Label for the x-axis.
#' @param ylab Label for the y-axis. If omitted, a default based on the stored
#'   dependence measure is used.
#' @param main Main title. If omitted, a default title is used.
#' @param add_h0 Logical; if \code{TRUE}, add a horizontal reference line at
#'   zero.
#' @param pch Plotting character used for \code{type = "line"}.
#' @param lty Line type used for \code{type = "line"}.
#' @param ... Further arguments passed to [graphics::barplot()] or
#'   [graphics::plot()].
#'
#' @return
#' The plot method is called for its side effect of producing a plot and returns
#' the object invisibly.
#'
#' @examples
#' x <- as.numeric(arima.sim(list(ar = 0.6), n = 100))
#' fit <- dcor_serial_test(x, B = 99, lags = 1:10)
#' plot(fit)
#'
#' fit2 <- hsic_serial_test(x, B = 99, lags = 1:10)
#' plot(fit2, type = "line")
#'
#' @name sdt
NULL

#' @rdname sdt
#' @export
plot.sdt <- function(x,
                     type = c("bar", "line"),
                     xlab = "Lag",
                     ylab = NULL,
                     main = NULL,
                     add_h0 = TRUE,
                     pch = 19,
                     lty = 1,
                     ...) {
  type <- match.arg(type)
  
  if (is.null(x$estimate) || is.null(x$lags)) {
    stop("Object does not contain lagwise dependence estimates.", call. = FALSE)
  }
  
  vals <- as.numeric(x$estimate)
  lags <- as.integer(x$lags)
  
  if (is.null(ylab)) {
    ylab <- if (!is.null(x$measure_name)) x$measure_name else "Dependence measure"
  }
  
  if (is.null(main)) {
    main <- paste("Dependogram based on", ylab)
  }
  
  if (type == "bar") {
    mids <- graphics::barplot(
      height = vals,
      names.arg = lags,
      xlab = xlab,
      ylab = ylab,
      main = main,
      ...
    )
    if (isTRUE(add_h0)) {
      graphics::abline(h = 0)
    }
    invisible(x)
  } else {
    dots <- list(...)
    if (is.null(dots$ylim)) {
      dots$ylim <- range(c(vals, 0), na.rm = TRUE)
    }
    do.call(
      graphics::plot,
      c(
        list(
          x = lags,
          y = vals,
          type = "b",
          pch = pch,
          lty = lty,
          xlab = xlab,
          ylab = ylab,
          main = main
        ),
        dots
      )
    )
    if (isTRUE(add_h0)) {
      graphics::abline(h = 0)
    }
    invisible(x)
  }
}