R/geom_timeline.R

In avidclam/msdr5: Visualization of NOAA's Significant Earthquake Database

#' @importFrom ggplot2 ggproto Geom aes draw_key_point
#' @importFrom grid pointsGrob unit gpar
GeomTimeline <-
  ggplot2::ggproto("GeomTimeline", ggplot2::Geom,
          required_aes = c("x"),
          default_aes = ggplot2::aes(
            y = 0.1, shape = 19, size = 3, colour = "gray", alpha = 0.45, fill = NA, stroke = 0),
          draw_key = ggplot2::draw_key_point,
          draw_panel = function(data, panel_scales, coord) {
            ## Transform the data first
            coords <- coord$transform(data, panel_scales)

            ## Construct a grid grob
            grid::pointsGrob(
              x = coords$x,
              y = coords$y,
              pch = coords$shape,
              size = grid::unit(data$size, "mm"),
              gp = grid::gpar(
                col = coords$colour,
                alpha = coords$alpha
              )
            )
          })

#' Geom function for plotting a time line of earthquakes
#'
#' This ggplot2 geom should be used for plotting earthquakes as points along the date axis (x).
#' Optional aesthetics include color, size, and alpha (for transparency).
#' Optional y aesthetic is a factor indicating some stratification in which case multiple time lines
#' will be plotted for each level of the factor (e.g. country).
#'
#' @inherit ggplot2::geom_point
#'
#' @examples
#' \dontrun{
#' earthquakes %>%
#'   eq_clean_data() %>%
#'   eq_location_clean() %>%
#'   filter(YEAR >= 2000) %>%
#'   filter(COUNTRY %in% c("USA", "MEXICO")) %>%
#'   ggplot(aes(x = DATE, y = COUNTRY, color = DEATHS, size = EQ_PRIMARY)) +
#'   geom_timeline() +
#'   scale_size_continuous(name = 'Richter scale value', guide = guide_legend(order = 1)) +
#'   scale_color_continuous(name = '# of Deaths', guide = guide_colorbar(order = 2)) +
#'   theme_eq_custom()
#' }
#'
#' @importFrom ggplot2 layer
#'
#' @export
geom_timeline <- function(mapping = NULL, data = NULL, stat = "identity",
                          position = "identity", na.rm = FALSE, show.legend = NA,
                          inherit.aes = TRUE, ...) {
  ggplot2::layer(
    geom = GeomTimeline, mapping = mapping,  data = data, stat = stat,
    position = position, show.legend = show.legend, inherit.aes = inherit.aes,
    params = list(na.rm = na.rm, ...)
  )
}
#' Custom theme for earthquakes timeline plots
#'
#' Slightly customized classic theme.
#' Allows further tweating by passing ggplot2::theme parameters
#'
#' @seealso
#' In ggplot2 package: \code{\link[ggplot2]{theme}}
#'
#' @param ... Arguments to be passed to ggplot2::theme(...)
#'
#' @importFrom ggplot2 theme_classic theme element_blank element_line
#'
#' @export
theme_eq_custom <- function(...){
  ggplot2::theme_classic() +
    ggplot2::theme(
      legend.position = 'bottom',
      axis.line.y = ggplot2::element_blank(),
      axis.title.y = ggplot2::element_blank(),
      axis.ticks.y = ggplot2::element_blank(),
      axis.line.x = ggplot2::element_line(size = 1),
      panel.grid.major.y = ggplot2::element_line(color = "gray")
    ) +
    ggplot2::theme(...)
}