R/range-selector.R

In rstudio/dygraphs: Interface to 'Dygraphs' Interactive Time Series Charting Library

#' dygraph interactive range selection and zooming
#'
#' Add a range selector to the bottom of the chart that allows users to pan and
#' zoom to various date ranges.
#'
#' @inheritParams dyOptions
#'
#' @param dygraph Dygraph to add range selector to
#' @param dateWindow Initially zoom in on a section of the graph. Is a two
#'   element vector [earliest, latest], where earliest/latest objects
#'   convertible via \code{as.POSIXct}.
#' @param height Height, in pixels, of the range selector widget.
#' @param fillColor The range selector mini plot fill color. This can be of the
#'   form "#AABBCC" or "rgb(255,100,200)" or "yellow". You can also specify ""
#'   to turn off fill.
#' @param strokeColor The range selector mini plot stroke color. This can be of
#'   the form "#AABBCC" or "rgb(255,100,200)" or "yellow". You can also specify
#'   "" to turn off stroke.
#' @param keepMouseZoom Keep mouse zoom when adding a range selector
#'
#' @return A dygraph that displays a range selector
#'
#' @examples
#' library(dygraphs)
#'
#' dygraph(nhtemp, main = "New Haven Temperatures") %>%
#'   dyRangeSelector()
#'
#' dygraph(nhtemp, main = "New Haven Temperatures") %>%
#'   dyRangeSelector(dateWindow = c("1920-01-01", "1960-01-01"))
#'
#' dygraph(nhtemp, main = "New Haven Temperatures") %>%
#'   dyRangeSelector(height = 20, strokeColor = "")
#' @note See the
#' \href{https://rstudio.github.io/dygraphs/gallery-range-selector.html}{online
#' documentation} for additional details and examples.
#'
#' Shiny applications can respond to changes in the \code{dateWindow}
#' via a special date window shiny input value. For example, if the
#' output id of a dygraph is `series` then the current date window
#' can be read from \code{input$series_date_window} as an array of
#' two date values (from and to).
#'
#' @export
dyRangeSelector <- function(dygraph,
                            dateWindow = NULL,
                            height = 40,
                            fillColor = " #A7B1C4",
                            strokeColor = "#808FAB",
                            keepMouseZoom = TRUE,
                            retainDateWindow = FALSE) {
  selector <- list()
  selector$showRangeSelector <- TRUE
  if (!is.null(dateWindow)) {
    if (length(dateWindow) != 2) {
      stop("dateWindow must be vector of length 2 that is convertible to POSIXct")
    }
    if (dygraph$x$format == "date") {
      selector$dateWindow <- sapply(USE.NAMES = FALSE, dateWindow, asISO8601Time)
    } else {
      selector$dateWindow <- dateWindow
    }
  }
  selector$rangeSelectorHeight <- height
  selector$rangeSelectorPlotFillColor <- fillColor
  selector$rangeSelectorPlotStrokeColor <- strokeColor
  if (!missing(retainDateWindow)) {
    selector$retainDateWindow <- retainDateWindow
  }

  if (keepMouseZoom) {
    selector$interactionModel <- JS("Dygraph.Interaction.defaultModel")
  }

  # merge selector
  dygraph$x$attrs <- mergeLists(dygraph$x$attrs, selector)

  # return modified dygraph
  dygraph
}