R/themes.R

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

#' Various UC themes for use with ggplot charts
#'
#' These functions allow you to add University of Cincinnati themes to ggplot
#' graphics using the official UC color system and digital typography
#' fallbacks.
#'
#' The main theme is \code{theme_UC}, while \code{theme_UC_hgrid} and
#' \code{theme_UC_vgrid} are used for plots that benefit from a single grid
#' direction. \code{theme_UC_nogrid} removes all gridlines.
#'
#' @param border If \code{FALSE}, removes outer border from plot.
#' @param legend_position legend position. "bottom" or "right"
#' @param legend_hide If \code{TRUE}, hides legend in final plot.
#' @param ... Additional arguments passed into \code{theme_UC}
#' @return A complete \code{ggplot2} theme object. The exported variants return
#'   horizontal-grid, vertical-grid, or no-grid versions of the base theme.
#' @author Saannidhya Rawat
#' @family themes
#' @export
#' @examples
#'
#' library(ggplot2)
#'
#' p <- ggplot(
#'   data = iris,
#'   mapping = aes(x = Petal.Width, y = Petal.Length, color = Species)
#' ) +
#'   geom_jitter(size = 1.5) +
#'   labs(
#'     x = "Petal Width",
#'     y = "Petal Length",
#'     title = "Iris Example",
#'     subtitle = "Width vs Length by Species",
#'     caption = "Note: This is a caption"
#'   ) +
#'   facet_wrap(~Species)
#'
#' p + theme_UC()
#' p + theme_UC_hgrid()
#' p + theme_UC_vgrid()
theme_UC <- function(border = TRUE,
                     legend_position = c("bottom", "right"),
                     legend_hide = FALSE) {

  legend_position <- match.arg(legend_position)

  base_family <- .uc_font_family("sans")
  display_family <- .uc_font_family("display")

  UC_theme <- ggplot2::theme_minimal(
    base_size = 11,
    base_family = base_family
  ) %+replace%
    ggplot2::theme(
      text = ggplot2::element_text(color = .uc_text_color()),
      plot.background = ggplot2::element_rect(
        fill = .uc_color("White"),
        color = NA
      ),
      panel.background = ggplot2::element_rect(
        fill = .uc_color("White"),
        color = NA
      ),
      plot.title.position = "plot",
      plot.caption.position = "plot",
      plot.margin = ggplot2::margin(12, 12, 12, 12),
      plot.title = ggplot2::element_text(
        family = display_family,
        face = "bold",
        size = 16,
        color = .uc_color("UC Red"),
        margin = ggplot2::margin(b = 6)
      ),
      plot.subtitle = ggplot2::element_text(
        size = 10.5,
        color = .uc_text_color(),
        margin = ggplot2::margin(b = 10)
      ),
      plot.caption = ggplot2::element_text(
        size = 9,
        color = .uc_reference_color()
      ),
      legend.position = legend_position,
      legend.title = ggplot2::element_text(
        family = display_family,
        face = "bold",
        size = 10,
        color = .uc_color("UC Dark Red")
      ),
      legend.text = ggplot2::element_text(
        size = 9.5,
        color = .uc_text_color()
      ),
      legend.key = ggplot2::element_rect(
        fill = .uc_color("White"),
        color = NA
      ),
      legend.background = ggplot2::element_blank(),
      legend.box.spacing = grid::unit(0.15, "cm"),
      axis.title.x = ggplot2::element_text(
        face = "bold",
        margin = ggplot2::margin(t = 8)
      ),
      axis.title.y = ggplot2::element_text(
        face = "bold",
        margin = ggplot2::margin(r = 8)
      ),
      axis.text = ggplot2::element_text(
        size = 9.5,
        color = .uc_text_color()
      ),
      axis.text.x = ggplot2::element_text(
        margin = ggplot2::margin(t = 4)
      ),
      axis.ticks = ggplot2::element_blank(),
      panel.grid.minor = ggplot2::element_blank(),
      panel.grid.major.x = ggplot2::element_line(
        color = .uc_grid_color(),
        linewidth = 0.35
      ),
      panel.grid.major.y = ggplot2::element_line(
        color = .uc_grid_color(),
        linewidth = 0.35
      ),
      panel.border = ggplot2::element_rect(
        fill = NA,
        color = .uc_border_color(),
        linewidth = 0.6
      ),
      strip.background = ggplot2::element_rect(
        fill = .uc_color("Grey"),
        color = .uc_color("UC Red"),
        linewidth = 0.6
      ),
      strip.text = ggplot2::element_text(
        family = display_family,
        face = "bold",
        size = 10,
        color = .uc_color("UC Dark Red"),
        margin = ggplot2::margin(4, 6, 4, 6)
      )
    )

  if (!border) {
    UC_theme <- UC_theme %+replace%
      ggplot2::theme(
        panel.border = ggplot2::element_blank(),
        strip.background = ggplot2::element_rect(
          fill = .uc_color("Grey"),
          color = NA
        )
      )
  }

  if (legend_hide) {
    UC_theme <- UC_theme %+replace%
      ggplot2::theme(
        legend.position = "none"
      )
  }

  UC_theme
}

#' @rdname theme_UC
#' @importFrom ggplot2 `%+replace%`
#' @export
theme_UC_hgrid <- function(border = FALSE, ...) {
  theme_UC(border, ...) %+replace%
    ggplot2::theme(
      panel.grid.major.x = ggplot2::element_blank(),
      panel.border = ggplot2::element_blank(),
      strip.background = ggplot2::element_rect(
        fill = .uc_color("Grey"),
        color = NA
      )
    )
}

#' @rdname theme_UC
#' @importFrom ggplot2 `%+replace%`
#' @export
theme_UC_vgrid <- function(border = FALSE, ...) {
  theme_UC(border, ...) %+replace%
    ggplot2::theme(
      panel.grid.major.y = ggplot2::element_blank()
    )
}

#' @rdname theme_UC
#' @importFrom ggplot2 `%+replace%`
#' @export
theme_UC_nogrid <- function(border = FALSE, ...) {
  theme_UC(border, ...) %+replace%
    ggplot2::theme(
      panel.grid.major.x = ggplot2::element_blank(),
      panel.grid.major.y = ggplot2::element_blank()
    )
}

#' @title UC default geoms
#' @description Apply UC default colors to ggplot2 geoms. Note: only applies during session.
#' @return No return value, called for side effects on \code{ggplot2} geom
#'   defaults for the current R session.
#' @author Saannidhya Rawat
#' @export
set_UC_geoms <- function() {

  ggplot2::update_geom_defaults("line", list(
    color = .uc_color("UC Red"),
    linewidth = 0.9
  ))

  ggplot2::update_geom_defaults("point", list(
    color = .uc_color("Bearcats Black"),
    size = 1.8
  ))

  ggplot2::update_geom_defaults("smooth", list(
    fill = scales::alpha(.uc_color("UC Red"), 0.16),
    color = .uc_color("UC Dark Red"),
    linewidth = 0.9
  ))

  ggplot2::update_geom_defaults("vline", list(
    linetype = "dashed",
    color = .uc_reference_color(),
    linewidth = 0.7
  ))

  ggplot2::update_geom_defaults("hline", list(
    linetype = "dashed",
    color = .uc_reference_color(),
    linewidth = 0.7
  ))

  ggplot2::update_geom_defaults("abline", list(
    linetype = "dashed",
    color = .uc_reference_color(),
    linewidth = 0.7
  ))

  ggplot2::update_geom_defaults("bar", list(
    color = .uc_color("White"),
    fill = .uc_color("UC Red")
  ))

  ggplot2::update_geom_defaults("col", list(
    color = .uc_color("White"),
    fill = .uc_color("UC Red")
  ))

  ggplot2::update_geom_defaults("ribbon", list(
    fill = .uc_ribbon_fill(),
    color = .uc_color("Steger Silver"),
    linewidth = 0.2
  ))

  ggplot2::update_geom_defaults("errorbar", list(
    color = .uc_color("UC Dark Red"),
    linewidth = 0.6
  ))

  invisible(NULL)
}