highlight_key() is a better name than highlight_unit()

Author: cpsievert

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)

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
 

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")

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/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(...)
 }
 

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)
 

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")) %>%

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)
 

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()

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"),