R/bcat_plt_area.R

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

#' Area plot utility
#'
#' Create an area plot using ggplot2 graphics. This function is a wrapper to create
#' commonly used styles of area plots. Additional layers can be added to this plot
#' as needed. More complicated plots can be creating using individual ggplot2 layers.
#'
#' @param df The data to be displayed
#' @param x variable to map to the x-axis
#' @param y Variable to map to the y-axis
#' @param fill Variable to map to the fill aesthetic
#' @param facet Facetting variable(s). Note: must wrap in \code{vars}, e.g, \code{facet = vars(var1, var2)}
#' @param position  Either stack values in cumulative fashion (\code{position = "stack"}) or stack such that proportions
#' at each value of \code{x} sum to 1 (\code{position = "fill"}).
#' @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_lab Legend title
#' @param legend_position legend position. "bottom" or "right"
#' @param legend_hide Set to \code{TRUE} to hide the legend
#' @param x_scale \code{scale_x_} function to apply to x-axis. If \code{position = "fill"}, it is recommended to
#' use the \code{expand = c(0,0)} option in the x_scale.
#' @param y_scale \code{scale_y_} function to apply to y-axis. If \code{position = "fill"}, it is recommended to
#' use the \code{expand = c(0,0)} option in the y_scale.
#' @param fill_scale \code{scale_fill_} function to apply to colors.
#' @param facet_scale Shoud facet scales be fixed ("fixed", the default), free ("free"),
#'                    or free in one dimension ("free_x", "free_y")
#' @param nrow Number of facet rows
#' @param ncol Number of facet columns
#' @param x_refline Vector of x-values at which to draw vertical reference lines
#' @param y_refline Vector of y-values at which to draw horizontal reference lines
#' @return A \code{ggplot2} plot object.
#' @author Saannidhya Rawat
#' @family plots
#' @export
#' @examples
#' set.seed(1234)
#'
#' d <- data.frame(t=rep(0:23,each=4),var=rep(LETTERS[1:4],4),val=round(runif(4*24,0,50)))
#'
#' # stacked area plot
#' bcat_plt_area(df = d, x = t, y = val, fill = var,
#'               position = "stack",
#'               fill_scale = ggplot2::scale_fill_viridis_d(),
#'               legend_lab = NULL)
#'
#' # filled area plot
#' bcat_plt_area(df = d, x = t, y = val, fill = var,
#'               position = "fill",
#'               fill_scale = ggplot2::scale_fill_viridis_d(),
#'               legend_lab = NULL)
#'
bcat_plt_area <- function(df,
                          x = NULL,
                          y = NULL,
                          fill = NULL,
                          facet = NULL,
                          position = c("stack", "fill"),
                          x_lab = ggplot2::waiver(),
                          y_lab = ggplot2::waiver(),
                          title = ggplot2::waiver(),
                          subtitle = ggplot2::waiver(),
                          caption = ggplot2::waiver(),
                          legend_lab = ggplot2::waiver(),
                          legend_position = "right",
                          legend_hide = FALSE,
                          x_scale = NULL,
                          y_scale = NULL,
                          fill_scale = Rbearcat::scale_fill_UC(),
                          facet_scale = c("fixed", "free_y", "free_x", "free"),
                          nrow = NULL,
                          ncol = NULL,
                          x_refline = NULL,
                          y_refline = NULL){

  # validation --------------------------------------------------------------

  .validate_df(df)

  # prelims -----------------------------------------------------------------

  position    <- match.arg(position)
  facet_scale <- match.arg(facet_scale)

  # plot-base ---------------------------------------------------------------

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

  # area-layer --------------------------------------------------------------

  if(is.null(x_scale) & position == "fill"){

    x_scale <- ggplot2::scale_x_continuous(expand = c(0,0))

  }

  if(is.null(y_scale) & position == "fill"){

    y_scale <- ggplot2::scale_y_continuous(labels = scales::percent_format(),
                                           expand = c(0,0))

  }

  p <- p + ggplot2::geom_area(position = position) +
    # scale options
    x_scale +
    y_scale +
    fill_scale

  # facets ------------------------------------------------------------------

  if(!is.null(facet)){

    p <- p + ggplot2::facet_wrap(facets = facet,
                                 nrow = nrow,
                                 ncol = ncol,
                                 scales = facet_scale)

  }

  # labels ------------------------------------------------------------------

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

  # reference-lines ---------------------------------------------------------

  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)

  }

  # add-theme-and-print -----------------------------------------------------

  if(position == "stack"){

    p +
      Rbearcat::theme_UC_hgrid(legend_position = "right",
                              legend_hide = legend_hide)


  } else{

    p +
      Rbearcat::theme_UC_nogrid(legend_position = "right",
                               legend_hide = legend_hide)

  }

}