highlight_key() is a better name than highlight_unit()

Author: cpsievert

Diff for: NAMESPACE

@@ -142,7 +142,7 @@ export(hide_colorbar)
 export(hide_guides)
 export(hide_legend)
 export(highlight)
-export(highlight_unit)
+export(highlight_key)
 export(knit_print.api_grid)
 export(knit_print.api_grid_local)
 export(knit_print.api_plot)

Diff for: NEWS.md

@@ -21,9 +21,10 @@
 * 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). For an example, run `plotly_example("shiny", "async")`.
+* 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
 

Diff for: R/ggplotly.R

@@ -47,7 +47,7 @@
 #' ggplotly(viz, tooltip = c("text", "size"))
 #' 
 #' # linked scatterplot brushing
-#' d <- highlight_unit(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") %>%
@@ -58,7 +58,7 @@
 #' demo("crosstalk-highlight-ggplotly", package = "plotly")
 #' 
 #' # client-side linked brushing in a scatterplot matrix
-#' highlight_unit(iris) %>%
+#' highlight_key(iris) %>%
 #'   GGally::ggpairs(aes(colour = Species), columns = 1:4) %>%
 #'   ggplotly(tooltip = c("x", "y", "colour")) %>%
 #'   highlight("plotly_selected")

Diff for: 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)

Diff for: R/plotly_data.R

@@ -88,16 +88,19 @@ print.plotly_data <- function(x, ...) {
   x
 }
 
-#' Shared data
+#' Highlight/query data based on primary key
 #' 
-#' This is simply a wrapper around `crosstalk::SharedData$new()` to make it easier
-#' to use and explain conceptually. It also makes it more discoverable if one
+#' This function simply creates an object of class [crosstalk::SharedData].
+#' The reason it exists is to make it easier to teach others how to leverage
+#' it's functionality in plotly. It also makes it more discoverable if one
 #' is already aware of [highlight].
 #' 
-#' @param ... arguments passed to crosstalk::SharedData$new()
+#' @param ... arguments passed to `crosstalk::SharedData$new()`
 #' @export
+#' @author Carson Sievert
 #' @return An object of class [crosstalk::SharedData]
-highlight_unit <- function(...) {
+#' @seealso [highlight]
+highlight_key <- function(...) {
   crosstalk::SharedData$new(...)
 }
 

Diff for: data-raw/res-us.R

@@ -9,7 +9,7 @@ res <- sf::st_read("~/Downloads/tl_2017_us_aiannh/tl_2017_us_aiannh.shp")
 # (2) crosstalk highlight should set fillcolor...
 
 res %>%
-  highlight_unit(~NAME) %>%
+  highlight_key(~NAME) %>%
   plot_ly(text = ~NAME) %>%
   highlight(selectize = TRUE, dynamic = TRUE)
 

Diff for: demo/animation-tour-USArrests.R

@@ -45,7 +45,7 @@ ax <- list(
 # for nicely formatted slider labels
 options(digits = 3)
 
-tour_dat <- highlight_unit(tour_dat, ~state, group = "A")
+tour_dat <- highlight_key(tour_dat, ~state, group = "A")
 
 tour <- proj_dat %>%
   plot_ly(x = ~x, y = ~y, frame = ~step, color = I("black")) %>%

Diff for: demo/crosstalk-filter-dynamic-axis.R

@@ -3,7 +3,7 @@ library(tidyr)
 library(crosstalk)
 
 m <- gather(mtcars, variable, value, -vs)
-msd <- highlight_unit(m, ~variable)
+msd <- highlight_key(m, ~variable)
 gg <- ggplot(msd, aes(factor(vs), value)) + 
   geom_jitter(alpha = 0.3)
 

Diff for: demo/crosstalk-filter-lines.R

@@ -3,7 +3,7 @@ library(ggplot2)
 library(gapminder)
 library(plotly)
 
-sd <- highlight_unit(gapminder)
+sd <- highlight_key(gapminder)
 
 g <- ggplot(sd, aes(year, lifeExp, color = country, group = country)) +
   geom_line()

Diff for: demo/crosstalk-highlight-binned-target-a.R

@@ -1,7 +1,7 @@
 # These examples demonstrate ways to display binned/aggregated selections
 library(plotly)
 
-d <- highlight_unit(mpg)
+d <- highlight_key(mpg)
 dots <- plot_ly(d, colors = "Set1", color = ~class, x = ~displ, y = ~cyl) %>%
   layout(
     xaxis = list(title = "Engine displacement"),

Diff for: demo/crosstalk-highlight-binned-target-b.R

@@ -1,7 +1,7 @@
 # These examples demonstrate ways to display binned/aggregated selections
 library(plotly)
 
-d <- highlight_unit(mtcars)
+d <- highlight_key(mtcars)
 sp <- plot_ly(d, x = ~mpg, y = ~disp) %>%
   add_markers(color = I("black"))
 

Diff for: demo/crosstalk-highlight-binned-target-c.R

@@ -1,7 +1,7 @@
 # These examples demonstrate ways to display binned/aggregated selections
 library(plotly)
 
-tx <- highlight_unit(txhousing, ~city)
+tx <- highlight_key(txhousing, ~city)
 p1 <- ggplot(tx, aes(date, median, group = city)) + geom_line() + xlab(NULL)
 gg1 <- ggplotly(p1, tooltip = c("city", "date", "median"))
 p2 <- plot_ly(tx, x = ~median, color = I("black")) %>% 

Diff for: demo/crosstalk-highlight-epl-2.R

@@ -20,7 +20,7 @@ dat <- england %>%
   mutate(meanP = mean(cumpts)) %>%
   filter(Season > 2006)
 
-sd <- highlight_unit(dat, ~team, "Select a team")
+sd <- highlight_key(dat, ~team, "Select a team")
 
 # a 'wormchart' like fig 8 here http://www.gradaanwr.net/wp-content/uploads/2016/06/dataApr16.pdf
 p <- ggplot(sd, aes(x = gameno, y = cumpts - meanP)) + 

Diff for: demo/crosstalk-highlight-epl.R

@@ -16,7 +16,7 @@ dat <- england %>%
   group_by(Season, team) %>% 
   mutate(gameno = row_number(), cumpts = cumsum(pts))
 
-sd <- highlight_unit(dat, ~Season, "Select a season")
+sd <- highlight_key(dat, ~Season, "Select a season")
 
 p <- ggplot(sd, aes(x = gameno, y = cumpts)) + 
   geom_line(aes(color = Season, group = Season), alpha = 0.5) + 

Diff for: demo/crosstalk-highlight-ggpairs.R

@@ -1,5 +1,5 @@
 library(GGally)
-d <- highlight_unit(iris)
+d <- highlight_key(iris)
 p <- ggpairs(d, aes(colour = Species), columns = 1:5)
 ggplotly(p) %>% 
   highlight("plotly_selected")

Diff for: demo/crosstalk-highlight-ggplotly.R

@@ -1,7 +1,7 @@
 library(plotly)
 
 # see https://vimeo.com/202647310
-d <- highlight_unit(txhousing, ~city, "Select a city")
+d <- highlight_key(txhousing, ~city, "Select a city")
 p <- ggplot(d, aes(date, median, group = city)) + geom_line()
 ggplotly(p, tooltip = "city") %>%
   layout(title = "Click on a line to highlight a year") %>%
@@ -18,7 +18,7 @@ ggplotly(p) %>%
   layout(title = "Click on a line to highlight a year")
 
 # perhaps a more useful example
-sd <- highlight_unit(txhousing, ~year)
+sd <- highlight_key(txhousing, ~year)
 p <- ggplot(sd, aes(month, median)) +
   geom_line(aes(group = year)) + 
   geom_smooth(data = txhousing, method = "gam") + 

Diff for: demo/crosstalk-highlight-intro.R

@@ -10,7 +10,7 @@ df <- data.frame(
 )
 
 # delare the patient variable as the "unit of interest"
-sd <- highlight_unit(df, ~patient)
+sd <- highlight_key(df, ~patient)
 
 p <- plot_ly(sd, x = ~visit, y = ~perc, color = I("black"),
              text = ~paste("Patient:", patient)) %>%

Diff for: demo/crosstalk-highlight-pipeline.R

@@ -1,6 +1,6 @@
 library(plotly)
 
-sd <- highlight_unit(txhousing, ~city, "Select a city")
+sd <- highlight_key(txhousing, ~city, "Select a city")
 
 base <- plot_ly(sd, color = I("black"), height = 400) %>%
   group_by(city)

Diff for: demo/crosstalk-highlight-subplot.R

@@ -1,6 +1,6 @@
 library(plotly)
 
-d <- highlight_unit(mtcars)
+d <- highlight_key(mtcars)
 s <- subplot(
   qplot(data = d, x = mpg, y = wt),
   qplot(data = d, x = mpg, y = vs)

Diff for: demo/custom-javascript.R

@@ -57,7 +57,7 @@ onRender(p, "
 
 # combine highlight() api with custom javascript
 mtcars %>%
-  highlight_unit() %>%
+  highlight_key() %>%
   plot_ly(x = ~wt, y = ~mpg, customdata = ~url) %>%
   highlight(color = "red") %>%
   onRender("

Diff for: demo/sf-dt.R

@@ -2,7 +2,7 @@ library(plotly)
 library(crosstalk)
 
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
-ncsd <- highlight_unit(nc)
+ncsd <- highlight_key(nc)
 
 map <- plot_ly(ncsd, split = ~NAME, color = I("gray"), hoveron = "fills") %>%
   highlight(persistent = TRUE, color = "red", opacityDim = 1) %>%

Diff for: demo/sf-mapbox-data.R

@@ -10,7 +10,7 @@ plot_mapbox(res_mn, split = ~INDRESNAME, span = I(1))
 plot_mapbox(res_mn, split = ~INDRESNAME, color = ~AREA, stroke = ~PERIMETER, span = I(1))
 
 # linking with DT
-mn <- highlight_unit(res_mn)
+mn <- highlight_key(res_mn)
 bscols(
   plot_mapbox(mn, split = ~INDRESNAME, text = ~INDRESNAME, hoverinfo = "text", hoveron = "fills") %>%
     layout(title = "Click a reservation", showlegend = FALSE),
@@ -19,7 +19,7 @@ bscols(
 
 # linking with plotly
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
-ncsd <- highlight_unit(nc)
+ncsd <- highlight_key(nc)
 
 # note that brushing counties is currently possible with plot_ly(), but isn't quite working 
 # yet with plot_mapbox() -- https://github.com/plotly/plotly.js/issues/2512

Diff for: demo/sf-plotly-3D-globe.R

@@ -42,7 +42,7 @@ globe <- plot_ly(height = 500) %>%
     hoverinfo = "none"
   ) %>%
   add_sf(
-    data = highlight_unit(storms, group = "storm paths"),
+    data = highlight_key(storms, group = "storm paths"),
     name = "storm paths",
     x = ~ 1.001 * cos(degrees2radians(x)) * cos(degrees2radians(y)),
     y = ~ 1.001 * sin(degrees2radians(x)) * cos(degrees2radians(y)),
@@ -97,7 +97,7 @@ distanceByAlt <- storms %>%
   group_by(L1) %>%
   mutate(dist = arc_dist(X, Y)) %>%
   rename(altitude = Z) %>%
-  highlight_unit(~L1, group = "storm paths") %>%
+  highlight_key(~L1, group = "storm paths") %>%
   plot_ly(x = ~dist, y = ~altitude, height = 400) %>%
   # plotly.js doesn't support color gradient along *2D* lines
   add_lines(color = I("gray")) %>%

Diff for: demo/sf-plotly-storms.R

@@ -1,7 +1,7 @@
 library(plotly)
 
 storms <- sf::st_read(system.file("shape/storms_xyz.shp", package = "sf"), quiet = TRUE)
-stormz <- highlight_unit(storms)
+stormz <- highlight_key(storms)
 
 xy <- plot_ly(stormz, color = ~z, mode = "markers+lines", line = list(color = "gray"), hoverinfo = "none")
 xz <- add_sf(xy, y = ~z, color = ~y)