merge conflicts

Author: cpsievert

DESCRIPTION

@@ -68,7 +68,10 @@ Suggests:
     rgeos,
     png,
     IRdisplay,
-    processx
+    processx,
+    plotlyGeoAssets,
+    rstudioapi,
+    forcats
 LazyData: true
 RoxygenNote: 6.0.1.9000
 Encoding: UTF-8

NAMESPACE

@@ -81,6 +81,7 @@ S3method(to_basic,default)
 S3method(transmute_,plotly)
 S3method(ungroup,plotly)
 export("%>%")
+export(TeX)
 export(add_annotations)
 export(add_area)
 export(add_bars)
@@ -104,6 +105,7 @@ export(add_scattergeo)
 export(add_segments)
 export(add_sf)
 export(add_surface)
+export(add_table)
 export(add_text)
 export(add_trace)
 export(animation_button)
@@ -141,6 +143,7 @@ export(hide_colorbar)
 export(hide_guides)
 export(hide_legend)
 export(highlight)
+export(highlight_key)
 export(knit_print.api_grid)
 export(knit_print.api_grid_local)
 export(knit_print.api_plot)

NEWS.md

@@ -4,7 +4,7 @@
 
 ### plotly.js and `plot_ly()` specific improvements
 
-* Upgraded to plotly.js v1.38.2. A _huge_ amount of features and improvements have been made since v1.29.2 (i.e., the version included in the last CRAN release of the R package - v4.7.1). Highlights include a complete re-write of `scattergl` to make it nearly feature complete with `scatter`, localization of text rendering (i.e., international translations), and six new trace types (`cone`, `scatterpolar`, `scatterpolargl`, `splom`, `table`, & `violin`)! See [here](https://github.com/plotly/plotly.js/releases) for a complete list of plotly.js-specific improvements.
+* Upgraded to plotly.js v1.38.3. A _huge_ amount of features and improvements have been made since v1.29.2 (i.e., the version included in the last CRAN release of the R package - v4.7.1). Highlights include a complete re-write of `scattergl` to make it nearly feature complete with `scatter`, localization of text rendering (i.e., international translations), and six new trace types (`cone`, `scatterpolar`, `scatterpolargl`, `splom`, `table`, & `violin`)! See [here](https://github.com/plotly/plotly.js/releases) for a complete list of plotly.js-specific improvements.
 * Support for **sf** (simple feature) data structures was added to `plot_ly()`, `plot_mapbox()`, and `plot_geo()` (via the new `add_sf()` function). See [this blog post](https://blog.cpsievert.me/2018/03/30/visualizing-geo-spatial-data-with-sf-and-plotly) for an overview.
 * Better control over the stroke (i.e., outline) appearance of various filled graphical marks via the new "special arguments" (`stroke`, `strokes`, `alpha_stroke`, `span`, and `spans`). For an overview, see the **sf** blog post linked to in the bullet point above and the new package demos (list all demos with `demo(package = "plotly")`).
 
@@ -15,13 +15,16 @@
 
 ### Other improvements relevant for all **plotly** objects
 
+* LaTeX rendering via MathJax is now supported and the new `TeX()` function may be used to flag a character vector as LaTeX (#375). Use the new `mathjax` argument in `config()` to specify either external (`mathjax="cdn"`) or local (`mathjax="local"`) MathJaX. If `"cdn"`, mathjax is loaded externally (meaning an internet connection is needed for TeX rendering). If `"local"`, the PLOTLY_MATHJAX_PATH environment variable must be set to the location (a local file path) of MathJax. IMPORTANT: **plotly** uses SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering (e.g., **rmarkdown** documents and **shiny** apps). To leverage both types of rendering, you must `<iframe>` your plotly graph(s) into the larger document (see [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for an **rmarkdown** example  and [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for a **shiny** example).
 * The selection (i.e., linked-brushing) mode can now switch from 'transient' to 'persistent' by holding the 'shift' key. It's still possible to _force_ persistent selection by setting `persistent = TRUE` in `highlight()`, but `persistent = FALSE` (the default) is now recommended since it allows one to switch between [persistent/transient selection](https://plotly-book.cpsievert.me/linking-views-without-shiny.html#transient-versus-persistent-selection) in the browser, rather than at the command line.
 * The `highlight()` function gains a `debounce` argument for throttling the rate at which `on` events may be fired. This is mainly useful for improving user experience when `highlight(on = "plotly_hover")` and mousing over relevant markers at a rapid rate (#1277)
 * The new `partial_bundle()` function makes it easy to leverage [partial bundles of plotly.js](https://github.com/plotly/plotly.js#partial-bundles) for reduced file sizes and faster render times.
 * The `config()` function gains a `locale` argument for easily changing localization defaults (#1270). This makes it possible localize date axes, and in some cases, modebar buttons (#1270).
+* The `plot_geo()` function gains a `offline` argument for rendering `"scattergeo"` traces with or without an internet connection (#356). Leveraging this argument requires the new **plotlyGeoAssets** package.
+* Support for async rendering of inside **shiny** apps using the [promises](https://rstudio.github.io/promises/) package (#1209). For an example, run `plotly_example("shiny", "async")`.
 * Instead of an error, `ggplotly(NULL, "message")` and `plotly_build(NULL, "message")` now returns `htmltools::div("message")`, making it easier to relay messages in shiny when data isn't yet ready to plot (#1116).
 * The `animation_button()` function gains a `label` argument, making it easier to control the label of an animation button generated through the `frame` API (#1205).
-* Support for async rendering of inside **shiny** apps using the [promises](https://rstudio.github.io/promises/) package (#1209).
+* The new `highlight_key()` function provides a wrapper around `crosstalk::SharedData$new()`, making it easier to teach others how to leverage `SharedData` objects with **plotly** and **crosstalk**.
 
 ## CHANGES
 
@@ -35,6 +38,7 @@
 
 ### Other changes relevant for all **plotly** objects
 
+* All axis objects now default to `automargin = TRUE`. The majority of the time this should make axis labels more readable, but may have un-intended consequences in some rare cases (#1252). 
 * The `elementId` field is no longer populated, which fixes the "Ignoring explicitly provided widget ID" warning in shiny applications (#985).
 
 ## BUG FIXES
@@ -52,6 +56,7 @@
 
 ### Other fixes relevant for all **plotly** objects
 
+* Marker sizes (i.e., `marker.size`) are now _always_ based on the area when `marker.sizemode='area'` (which is the default sizemode when using the `size` argument). Previously, traces with one just one value supplied to `marker.size` were being sized by their diameter (#1133).
 * Bug fix for linking views with crosstalk where the source of the selection is an aggregated trace (#1218).
 * Resizing behavior, after updating `height`/`width` via **shiny** reactive values, is now correct (#1068).
 * Fixed algorithm for coercing the proposed layout to the plot schema (#1156).

R/add.R

@@ -273,6 +273,38 @@ add_sf <- function(p, ..., x = ~x, y = ~y, data = NULL, inherit = TRUE) {
 }
 
 
+#' @inheritParams add_trace
+#' @param rownames whether or not to display the rownames of `data`.
+#' @rdname add_trace
+#' @export
+#' @examples 
+#' 
+#' plot_ly(economics) %>% 
+#'   add_table()
+add_table <- function(p, ..., rownames = TRUE, data = NULL, inherit = TRUE) {
+  attrs <- list(...)
+  dat <- plotly_data(add_data(p, data))
+  if (is.data.frame(dat)) {
+    vals <- lapply(names(dat), function(x) list(x))
+    if (isTRUE(rownames)) vals <- c(list(""), vals)
+    header_defaults <- list(
+      values = vals,
+      align = "right"
+    )
+    vals <- setNames(as.list(dat), NULL)
+    if (isTRUE(rownames)) vals <- c(list(row.names(dat)), vals)
+    cell_defaults <- list(
+      values = vals,
+      align = "right"
+    )
+    attrs$header <- modify_list(header_defaults, attrs$header)
+    attrs$cells <- modify_list(cell_defaults, attrs$cells)
+  }
+  
+  do.call(add_trace_classed, c(list(p = p, class = "plotly_table", type = "table"), attrs))
+}
+
+
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export

R/ggplotly.R

@@ -47,8 +47,7 @@
 #' ggplotly(viz, tooltip = c("text", "size"))
 #' 
 #' # linked scatterplot brushing
-#' library(crosstalk)
-#' d <- SharedData$new(mtcars)
+#' d <- highlight_key(mtcars)
 #' qplot(data = d, x = mpg, y = wt) %>%
 #'   subplot(qplot(data = d, x = mpg, y = vs)) %>% 
 #'   layout(title = "Click and drag to select points") %>%
@@ -59,7 +58,7 @@
 #' demo("crosstalk-highlight-ggplotly", package = "plotly")
 #' 
 #' # client-side linked brushing in a scatterplot matrix
-#' SharedData$new(iris) %>%
+#' highlight_key(iris) %>%
 #'   GGally::ggpairs(aes(colour = Species), columns = 1:4) %>%
 #'   ggplotly(tooltip = c("x", "y", "colour")) %>%
 #'   highlight("plotly_selected")

R/highlight.R

@@ -57,9 +57,8 @@
 #' # These examples are designed to show you how to highlight/brush a *single*
 #' # view. For examples of multiple linked views, see `demo(package = "plotly")` 
 #' 
-#' 
 #' library(crosstalk)
-#' d <- SharedData$new(txhousing, ~city)
+#' d <- highlight_key(txhousing, ~city)
 #' p <- ggplot(d, aes(date, median, group = city)) + geom_line()
 #' gg <- ggplotly(p, tooltip = "city") 
 #' highlight(gg, dynamic = TRUE)

R/layout.R

@@ -91,33 +91,47 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' @param collaborate include the collaborate mode bar button (unique to the R pkg)?
 #' @param cloud include the send data to cloud button?
 #' @param locale locale to use. See [here](https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization) for more info.
+#' @param mathjax add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
+#' If `"cdn"`, mathjax is loaded externally (meaning an internet connection is needed for 
+#' TeX rendering). If `"local"`, the PLOTLY_MATHJAX_PATH environment variable must be
+#' set to the location (a local file path) of MathJax. IMPORTANT: **plotly** uses SVG-based 
+#' mathjax rendering which doesn't play nicely with HTML-based rendering 
+#' (e.g., **rmarkdown** documents and **shiny** apps). To leverage both types of rendering, 
+#' you must `<iframe>` your plotly graph(s) into the larger document 
+#' (see [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) 
+#' for an **rmarkdown** example and 
+#' [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for a **shiny** example).
 #' @author Carson Sievert
 #' @export
 #' @examples
 #' 
+#' # remove the plotly logo and collaborate button from modebar
+#' config(plot_ly(), displaylogo = FALSE, collaborate = FALSE)
+#' 
+#' # enable mathjax
+#' # see more examples at https://plot.ly/r/LaTeX/
+#' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
+#'   layout(title = TeX("\\text{Some mathjax: }\\alpha+\\beta x")) %>%
+#'   config(mathjax = "cdn")
+#' 
+#' # change the language used to render date axes and on-graph text 
+#' # (e.g., modebar buttons)
 #' today <- Sys.Date()
 #' x <- seq.Date(today, today + 360, by = "day")
 #' p <- plot_ly(x = x, y = rnorm(length(x))) %>%
 #'   add_lines()
 #' 
-#' # remove the plotly logo and collaborate button from modebar
-#' config(p, displaylogo = FALSE, collaborate = FALSE)
-#' 
 #' # japanese
 #' config(p, locale = "ja")
 #' # german
 #' config(p, locale = "de")
-#' # swiss-german
-#' config(p, locale = "de-CH")
 #' # spanish
 #' config(p, locale = "es")
-#' # french
-#' config(p, locale = "fr")
 #' # chinese
 #' config(p, locale = "zh-CN")
 #' 
 
-config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL) {
+config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = NULL) {
 
   if (!is.null(locale)) {
     p$dependencies <- c(
@@ -127,6 +141,21 @@ config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL) {
     p$x$config$locale <- locale
   }
 
+  if (!is.null(mathjax)) {
+    mj <- switch(
+      match.arg(mathjax, c("cdn", "local")),
+      cdn = mathjax_cdn(),
+      local = mathjax_local()
+    )
+    # if mathjax is already supplied overwrite it; otherwise, prepend it
+    depNames <- sapply(p$dependencies, "[[", "name")
+    if (any(idx <- depNames %in% "mathjax")) {
+      p$dependencies[[which(idx)]] <- mathjax
+    } else {
+      p$dependencies <- c(list(mj), p$dependencies)
+    }
+  }
+  
   p$x$config <- modify_list(p$x$config, list(...))
 
   nms <- sapply(p$x$config[["modeBarButtonsToAdd"]], "[[", "name")

R/mathjax.R

@@ -0,0 +1,78 @@
+#' Render TeX in a plotly graph using MathJax
+#' 
+#' This function makes it slightly easier to render TeX in a plotly graph --
+#' it ensures that MathJax is included with the final result and also
+#' ensures the provided string is surrounded with `$` (this is what plotly.js
+#' uses to declare a string as TeX).
+#' 
+#' @param x a character vector
+#' @export
+#' @seealso [config]
+#' @examples 
+#' 
+#' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
+#'   layout(title = TeX("\\text{Some mathjax: }\\alpha+\\beta x")) %>%
+#'   config(mathjax = "cdn")
+
+TeX <- function(x) {
+  startsWithDollar <- grepl("^\\$", x)
+  endsWithDollar <- grepl("\\$$", x)
+  x <- paste0(if (!startsWithDollar) "$", x, if (!endsWithDollar) "$")
+  prefix_class(x, "TeX")
+}
+
+is.TeX <- function(x) {
+  inherits(x, "TeX")
+}
+
+mathjax_cdn <- function() {
+  htmltools::htmlDependency(
+    name = "mathjax",
+    version = "2.7.4",
+    src = c(file = depPath("mathjax")),
+    script = "cdn.js"
+  )
+}
+
+# TODO: wait until there is a more official way to include query parameters?
+# https://github.com/rstudio/htmltools/issues/98
+mathjax_local <- function() {
+  path <- mathjax_path()
+  
+  mj <- file.path(path, "MathJax.js")
+  if (!file.exists(mj)) stop("Couldn't locate MathJax.js")
+  
+  # parse the version
+  mathjax <- readLines(mj)
+  pat <- 'MathJax.fileversion="[0-9].[0-9].[0-9]'
+  ver <- regmatches(mathjax, regexpr(pat, mathjax))
+  ver <- sub('"', '', strsplit(ver, "=")[[1]][2])
+  
+  # make sure we have access to the right config
+  config <- file.path(path, "config", "TeX-AMS-MML_SVG.js")
+  if (!file.exists(config)) stop("Couldn't locate necessary MathJax config: TeX-AMS-MML_SVG")
+  
+  htmltools::htmlDependency(
+    name = "mathjax", 
+    version = ver, 
+    src = path,
+    script = c("MathJax.js", "config/TeX-AMS-MML_SVG.js")
+  )
+}
+
+
+mathjax_path <- function() {
+  path <- Sys.getenv("PLOTLY_MATHJAX_PATH", NA)
+  
+  if (!is.na(path)) {
+    mj <- file.path(path, "MathJax.js")
+    if (!file.exists(mj)) stop("Couldn't find 'MathJax.js' file in local directory")
+    return(path)
+  }
+  
+  stop(
+    "To use a local version of MathJax with plotly, set the PLOTLY_MATHJAX_PATH",
+    "environment variable to the location of MathJax.",
+    call. = FALSE
+  )
+}

R/orca.R

@@ -11,9 +11,10 @@
 #' Applies to all output images.
 #' @param height Sets the image height. If not set, defaults to `layout.height` value. 
 #' Applies to all output images.
-#' @param mathjax whether or not to specify a path to mathjax (required to export LaTeX characters).
-#' This should 'just work' in RStudio, but outside RStudio, you may have to set 
-#' the PLOTLY_MATHJAX_PATH environment variable to the location of MathJax.
+#' @param mathjax whether or not to include MathJax (required to render [TeX]).
+#' If `TRUE`, the PLOTLY_MATHJAX_PATH environment variable must be set and point 
+#' to the location of MathJax (this variable is also used to render [TeX] in 
+#' interactive graphs, see [config]).
 #' @param parallel_limit Sets the limit of parallel tasks run.
 #' @param verbose Turn on verbose logging on stdout.
 #' @param debug Starts app in debug mode and turn on verbose logs on stdout.
@@ -25,9 +26,7 @@
 #' 
 #' \dontrun{
 #' p <- plot_ly(z = ~volcano) %>% add_surface()
-#' orca(p, "surface-plot.png")
 #' orca(p, "surface-plot.svg")
-#' orca(p, "surface-plot.pdf")
 #' }
 #' 
 
@@ -65,25 +64,9 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
   if (!is.null(height)) args <- c(args, "--height", height)
   if (!is.null(parallel_limit)) args <- c(args, "--parallel-limit", parallel_limit)
   if (!is.na(mapbox_token())) args <- c(args, "--mapbox-access-token", mapbox_token())
-  if (isTRUE(mathjax)) args <- c(args, "--mathjax", mathjax_path())
+  if (isTRUE(mathjax)) args <- c(args, "--mathjax", file.path(mathjax_path(), "MathJax.js"))
 
   # TODO: point to local topojson? Should this only work if plot_geo(standalone = TRUE)?
   try_library("processx", "orca")
   invisible(processx::run("orca", args, echo = TRUE, spinner = TRUE))
 }
-
-
-mathjax_path <- function() {
-  if (is_rstudio()) {
-    try_library("rmarkdown", "orca")
-    return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")())
-  }
-  path <- Sys.getenv("PLOTLY_MATHJAX_PATH", Sys.getenv("RMARKDOWN_MATHJAX_PATH", NA))
-  if (!is.na(path)) return(normalizePath(path, mustWork = TRUE))
-  stop(
-    "Please set either the RMARKDOWN_MATHJAX_PATH or PLOTLY_MATHJAX_PATH ",
-    "environment variable to the location of MathJax. ",
-    "On Linux systems you can also install MathJax using your system package manager.",
-    call. = FALSE
-  )
-}

R/plotly.R

@@ -257,6 +257,9 @@ plot_mapbox <- function(data = data.frame(), ...) {
 #' 
 #' @param data A data frame (optional).
 #' @param ... arguments passed along to [plot_ly()].
+#' @param offline whether or not to include geo assets so that the map
+#' can be viewed with or without an internet connection. The plotlyGeoAssets
+#' package is required for this functionality.
 #' @export
 #' @author Carson Sievert
 #' @seealso [plot_ly()], [plot_mapbox()], [ggplotly()] 
@@ -267,8 +270,22 @@ plot_mapbox <- function(data = data.frame(), ...) {
 #'   plot_geo(x = ~long, y = ~lat) %>%
 #'   add_markers(size = I(1))
 #' 
-plot_geo <- function(data = data.frame(), ...) {
+plot_geo <- function(data = data.frame(), ..., offline = FALSE) {
   p <- plot_ly(data, ...)
+  
+  if (isTRUE(offline)) {
+    if (system.file(package = "plotlyGeoAssets") == "") {
+      stop(
+        "The plotlyGeoAssets package is required to make 'offline' maps. ",
+        "Please install and try again.",
+        call. = FALSE
+      )
+    }
+    p$dependencies <- c(
+      list(plotlyGeoAssets::geo_assets()),
+      p$dependencies
+    )
+  }
   # not only do we use this for is_geo(), but also setting the layout attr
   # https://plot.ly/r/reference/#layout-geo
   p$x$layout$mapType <- "geo"
@@ -429,7 +446,7 @@ typedArrayPolyfill <- function() {
 plotlyMainBundle <- function() {
   htmltools::htmlDependency(
     "plotly-main", 
-    version = "1.38.2",
+    version = "1.38.3",
     src = depPath("plotlyjs"),
     script = "plotly-latest.min.js",
     all_files = FALSE