Plot Inversion of Simultaneous Confidence Bands (SCBs) into Inner and Outer Simultaneous Confidence Regions (SCRs)

Visualizes simultaneous confidence regions of upper and lower excursion sets for discrete, 1D or 2D data, using contour or band plots. Supports plotting confidence regions at multiple levels and labeling contours.

Usage

plot_cs(
  SCB,
  levels,
  type = "upper",
  x,
  y = NULL,
  mu_hat = NULL,
  mu_true = NULL,
  together = TRUE,
  xlab = "X1",
  ylab = "X2",
  level_label = TRUE,
  min.size = 5,
  palette = "gray",
  color_level_label = "black"
)

Arguments

SCB: A numeric list returned by regression_outcome_scb(), functional_outcome_scb() or a custom list with two arrays of the same dimension: scb_up and scb_low, representing the upper and lower confidence bounds respectively. SCB$scb_up and SCB$scb_low should be numeric vectors (1D) or matrices (2D) containing the upper simultaneous confidence interval. Dimensions of SCB$scb_up and SCB$scb_low must match.
levels: A numeric vector or list of scalers for different levels or matrix containing interval sets to construct the confidence regions. If type = "upper" or "lower", levels should be a vector. "upper" represents upper excursion sets, and "lower" represents lower excursion sets.
type: A character specifying the type of inverse sets to fit. Choices are "upper" and "lower". Default is "upper".
x: A numerical vector of x-axis coordinates for 1D and 2D cases. For discrete coordinates, use a character vector. The order of x should correspond to the order of scb_up and scb_low in SCB.
y: Optional vector of y-axis coordinates for 2D data.
mu_hat: A numeric array (1D) or matrix (2D) of estimated means. If mu_true is provided, this will be overwritten by the true mean. Default is NULL. An input must be provided for either mu_hat or mu_true.
mu_true: Optional numeric array (1D) or matrix (2D) of true means, which overrides mu_hat if provided. Default is NULL.
together: Optional logical value for plotting option. If TRUE, plots all confidence levels on the same figure; otherwise, generates one plot per level. Default is TRUE.
xlab: Optional character for the label of the x-axis. Default is "x1".
ylab: Optional character for the label of the y-axis. Default is "x2".
level_label: Optional logical input for level displaying option. If TRUE, displays numeric level labels on contour lines for 2D confidence sets. Default is TRUE.
min.size: Optional logical input for minimum number of points required for a contour to be labeled. Default is 5.
palette: Optional character value for the name of the HCL color palette to use when plotting multiple levels together. Default is "gray".
color_level_label: Optional character value for the color used for contour level labels. Default is "black".

Value

A ggplot2 object that includes both simultaneous confidence intervals and simultaneous confidence region of excursion sets corresponding to levels assigned.

References

Ren, J., Telschow, F. J. E., & Schwartzman, A. (2024). Inverse set estimation and inversion of simultaneous confidence intervals. Journal of the Royal Statistical Society: Series C (Applied Statistics), 73(4), 1082–1109. doi:10.1093/jrsssc/qlae027

Examples


# \donttest{
if (requireNamespace("mgcv", quietly = TRUE)) {
# example using pupil data
data(pupil)
pupil_fpca <- prepare_pupil_fpca(pupil)

fosr_mod <- mgcv::bam(percent_change ~ s(seconds, k=30, bs="cr") +
  s(seconds, by = use, k=30, bs = "cr") +
  s(id, by = Phi1, bs="re") +
  s(id, by = Phi2, bs="re") +
  s(id, by = Phi3, bs="re") +
  s(id, by = Phi4, bs="re"),
  method = "fREML", data = pupil_fpca, discrete = TRUE)

pupil_multiplier <- SCB_functional_outcome(data = pupil_fpca, object = fosr_mod,
                                   method = "multiplier",
                                   outcome = "percent_change",
                                   domain = "seconds", subset= c("use = 1"),
                                   id = "id")

pupil_multiplier <- tibble::as_tibble(pupil_multiplier)

plot_cs(pupil_multiplier,levels = c(-18), x = pupil_multiplier$domain,
        mu_hat = pupil_multiplier$mu_hat, xlab = "", ylab = "",
        level_label = T, min.size = 40, palette = "Spectral",
        color_level_label = "black")
}

# }

x <- rnorm(50)
epsilon <- rnorm(50,0,sqrt(2))
y <- -1 + x + epsilon
df <- data.frame(x = x, y = y)
grid <- data.frame(x = seq(-1, 1, length.out = 50))
model <- "y ~ x"
results <- SCB_linear_outcome(df_fit = df, model = model, grid_df = grid)

results <- tibble::as_tibble(results)
plot_cs(results, levels = c(0), x = seq(-1, 1, length.out = 50), mu_hat = results$Mean,
       xlab = "x1", ylab = "y", level_label = T, min.size = 40, palette = "Spectral",
       color_level_label = "black")
#> Warning: Removed 42 rows containing missing values or values outside the scale range
#> (`geom_line()`).