R/bcat_plt_hist.R

In Rbearcat: University of Cincinnati Themes and Utilities for Econometrics and Data Science

#' Histogram utility
#'
#' Create a histogram using ggplot2 graphics with UC styling. Includes optional
#' density curve overlay and mean reference line.
#'
#' @param df The data to be displayed.
#' @param x Variable to map to the x-axis.
#' @param bins Number of bins. If NULL (default), uses ggplot2's automatic selection.
#' @param fill Fill color for bars. Default is UC Steger Silver.
#' @param facet Facetting variable(s). Wrap in \code{vars()}.
#' @param density Logical. Overlay density curve? Default is FALSE.
#' @param mean_line Logical. Draw dashed vertical line at mean? Default is TRUE.
#' @param rug Logical. Add rug plot at bottom? Default is FALSE.
#' @param x_lab Label for x-axis.
#' @param y_lab Label for y-axis.
#' @param title Plot title.
#' @param subtitle Plot subtitle.
#' @param caption Plot caption.
#' @param legend_position Legend position: \code{"bottom"} or \code{"right"}.
#' @param legend_hide Logical. Hide legend?
#' @param x_scale \code{scale_x_} function.
#' @param y_scale \code{scale_y_} function.
#' @param facet_scale Facet scales: \code{"fixed"}, \code{"free"}, \code{"free_x"}, \code{"free_y"}.
#' @param nrow Number of facet rows.
#' @param ncol Number of facet columns.
#' @param x_refline Vector of x-values for vertical reference lines.
#' @param y_refline Vector of y-values for horizontal reference lines.
#' @return A ggplot object.
#' @author Saannidhya Rawat
#' @family plots
#' @export
#'
#' @examples
#' library(ggplot2)
#'
#' # Basic histogram
#' bcat_plt_hist(mtcars, x = mpg)
#'
#' # With density curve and mean line
#' bcat_plt_hist(mtcars, x = mpg, density = TRUE, mean_line = TRUE)
#'
#' # Faceted by cylinders
#' bcat_plt_hist(mtcars, x = mpg, facet = vars(cyl), facet_scale = "free_x")
bcat_plt_hist <- function(df,
                          x,
                          bins = NULL,
                          fill = palette_UC[["Steger Silver"]],
                          facet = NULL,
                          density = FALSE,
                          mean_line = TRUE,
                          rug = FALSE,
                          x_lab = ggplot2::waiver(),
                          y_lab = ggplot2::waiver(),
                          title = ggplot2::waiver(),
                          subtitle = ggplot2::waiver(),
                          caption = ggplot2::waiver(),
                          legend_position = "bottom",
                          legend_hide = FALSE,
                          x_scale = NULL,
                          y_scale = NULL,
                          facet_scale = c("fixed", "free_y", "free_x", "free"),
                          nrow = NULL,
                          ncol = NULL,
                          x_refline = NULL,
                          y_refline = NULL) {

  facet_scale <- match.arg(facet_scale)

  p <- ggplot2::ggplot(data = df, mapping = ggplot2::aes(x = {{ x }}))

  # Histogram layer
  hist_args <- list(fill = fill, color = "white", alpha = 0.85)
  if (!is.null(bins)) hist_args$bins <- bins
  if (density) hist_args$mapping <- ggplot2::aes(y = ggplot2::after_stat(density))

  p <- p + do.call(ggplot2::geom_histogram, hist_args)

  # Density curve
  if (density) {
    p <- p + ggplot2::geom_density(color = .uc_color("UC Dark Red"), linewidth = 1)
  }

  # Mean line
  if (mean_line) {
    p <- p + ggplot2::geom_vline(
      ggplot2::aes(xintercept = mean({{ x }}, na.rm = TRUE)),
      linetype = "dashed", color = .uc_reference_color(), linewidth = 0.75
    )
  }

  if (rug) p <- p + ggplot2::geom_rug(alpha = 0.3)

  p <- p + x_scale + y_scale

  if (!is.null(facet)) {
    p <- p + ggplot2::facet_wrap(facets = facet, nrow = nrow, ncol = ncol,
                                 scales = facet_scale)
  }

  p <- p + ggplot2::labs(x = x_lab, y = y_lab, title = title,
                         subtitle = subtitle, caption = caption)

  if (!is.null(x_refline)) p <- p + ggplot2::geom_vline(xintercept = x_refline)
  if (!is.null(y_refline)) p <- p + ggplot2::geom_hline(yintercept = y_refline)

  p + theme_UC_hgrid(legend_position = legend_position, legend_hide = legend_hide)
}