R/plot_line.R

In tscv: Functions and Utilities for Tidy Time Series Forecasting and Time Series Cross-Validation

#' @title Plot data as a line chart
#'
#' @description
#' Create a line chart for one or more time series or grouped numeric variables.
#'
#' @details
#' \code{plot_line()} is a convenience wrapper around \code{ggplot2::geom_line()}
#' for plotting data in long format. It supports optional grouping by color,
#' optional faceting, and the default \code{tscv} theme.
#'
#' The arguments \code{x}, \code{y}, \code{facet_var}, and \code{color} are
#' passed as unquoted column names.
#'
#' If \code{color} is supplied, line colors are mapped to that variable and
#' \code{line_color} is ignored. If \code{color} is not supplied, all lines are
#' drawn using \code{line_color}.
#'
#' Additional theme settings can be supplied through \code{theme_config}. This
#' should be a named list of arguments passed to \code{ggplot2::theme()}.
#'
#' @param data A \code{data.frame}, \code{tibble}, or \code{tsibble} in long
#'   format.
#' @param x Unquoted column in \code{data} used on the x-axis.
#' @param y Unquoted column in \code{data} containing numeric values shown on
#'   the y-axis.
#' @param facet_var Optional unquoted column in \code{data} used for faceting.
#' @param facet_scale Character value defining facet axis scaling. Common values
#'   are \code{"free"}, \code{"fixed"}, \code{"free_x"}, and \code{"free_y"}.
#' @param facet_nrow Optional integer. Number of rows in the facet layout.
#' @param facet_ncol Optional integer. Number of columns in the facet layout.
#' @param color Optional unquoted column in \code{data} used to map line color.
#' @param title Character value. Plot title.
#' @param subtitle Character value. Plot subtitle.
#' @param xlab Character value. Label for the x-axis.
#' @param ylab Character value. Label for the y-axis.
#' @param caption Character value. Plot caption.
#' @param line_size Numeric value defining the line width.
#' @param line_type Character or numeric value defining the line type.
#' @param line_color Character value defining the line color. Ignored when
#'   \code{color} is supplied.
#' @param line_alpha Numeric value between \code{0} and \code{1} defining line
#'   transparency.
#' @param theme_set A complete \code{ggplot2} theme.
#' @param theme_config A named \code{list} with additional arguments passed to
#'   \code{ggplot2::theme()}.
#' @param ... Currently not used.
#'
#' @return
#' An object of class \code{ggplot}.
#'
#' @family data visualization
#' @export
#'
#' @examples
#' library(dplyr)
#'
#' data <- M4_monthly_data |>
#'   filter(series %in% c("M23100", "M14395"))
#'
#' plot_line(
#'   data = data,
#'   x = index,
#'   y = value,
#'   facet_var = series,
#'   title = "M4 Monthly Time Series",
#'   subtitle = "Selected monthly series from the M4 forecasting competition",
#'   xlab = "Time",
#'   ylab = "Value",
#'   caption = "Data: M4 Forecasting Competition"
#' )
#'
#' plot_line(
#'   data = data,
#'   x = index,
#'   y = value,
#'   color = series,
#'   title = "M4 Monthly Time Series",
#'   xlab = "Time",
#'   ylab = "Value",
#'   line_size = 1.5
#' )

plot_line <- function(data,
                      x,
                      y,
                      facet_var = NULL,
                      facet_scale = "free",
                      facet_nrow = NULL,
                      facet_ncol = NULL,
                      color = NULL,
                      title = NULL,
                      subtitle = NULL,
                      xlab = NULL,
                      ylab = NULL,
                      caption = NULL,
                      line_size = 0.75,
                      line_type = "solid",
                      line_color = "grey35",
                      line_alpha = 1,
                      theme_set = theme_tscv(),
                      theme_config = list(),
                      ...) {

  # Create initial ggplot object
  p <- ggplot(data = data)

  # Create line
  if (quo_is_null(enquo(color))) {
    p <- p + geom_line(
      aes(
        x = {{x}},
        y = {{y}}),
      color = line_color,
      linewidth = line_size,
      linetype = line_type,
      alpha = line_alpha
    )
  } else {
    p <- p + geom_line(
      aes(
        x = {{x}},
        y = {{y}},
        color = {{color}}),
      linewidth = line_size,
      linetype = line_type,
      alpha = line_alpha
    )
  }

  # Create facet
  if (!quo_is_null(enquo(facet_var))) {
    p <- p + facet_wrap(
      facets = vars({{facet_var}}),
      scales = facet_scale,
      nrow = facet_nrow,
      ncol = facet_ncol
    )
  }

  # Adjust annotations
  p <- p + labs(title = title)
  p <- p + labs(subtitle = subtitle)
  p <- p + labs(x = xlab)
  p <- p + labs(y = ylab)
  p <- p + labs(caption = caption)

  # Adjust ggplot2 theme
  p <- p + eval(theme_set)
  p <- p + do.call(theme, theme_config)

  return(p)
}