CRAN version v4.8.0

Also, clean up examples on help(add_trace)

Author: cpsievert

R/add.R

@@ -33,24 +33,115 @@ add_data <- function(p, data = NULL) {
 #' @param xend "final" x position (in this context, x represents "start")
 #' @param yend "final" y position (in this context, y represents "start")
 #' @seealso [plot_ly()]
-#' @references \url{https://plot.ly/r/reference/}
+#' @references \url{http://plotly-book.cpsievert.me/the-plotly-cookbook.html}
+#' 
+#' \url{https://plot.ly/r}
+#' 
+#' \url{https://plot.ly/r/reference/} 
 #' @author Carson Sievert
 #' @export
 #' @rdname add_trace
 #' @examples 
 #' 
+#' # the `plot_ly()` function initiates an object, and if no trace type
+#' # is specified, it sets a sensible default
 #' p <- plot_ly(economics, x = ~date, y = ~uempmed)
 #' p
-#' p %>% add_markers()
-#' p %>% add_lines()
-#' p %>% add_text(text = ".")
 #' 
-#' # attributes declared in plot_ly() carry over to downstream traces,
-#' # but can be overwritten
-#' plot_ly(economics, x = ~date, y = ~uempmed, color = I("red")) %>% 
+#' # some `add_*()` functions are a specific case of a trace type
+#' # for example, `add_markers()` is a scatter trace with mode of markers
+#' add_markers(p)
+#' 
+#' # scatter trace with mode of text
+#' add_text(p, text = "%")
+#' 
+#' # scatter trace with mode of lines 
+#' add_paths(p)
+#' 
+#' # like `add_paths()`, but ensures points are connected according to `x`
+#' add_lines(p)
+#' 
+#' # if you prefer to work with plotly.js more directly, can always
+#' # use `add_trace()` and specify the type yourself
+#' add_trace(p, type = "scatter", mode = "markers+lines")
+#' 
+#' # mappings provided to `plot_ly()` are "global", but can be overwritten
+#' plot_ly(economics, x = ~date, y = ~uempmed, color = I("red"), showlegend = FALSE) %>% 
 #'   add_lines() %>%
-#'   add_markers(color = ~pop) %>%
-#'   layout(showlegend = FALSE)
+#'   add_markers(color = ~pop)
+#' 
+#' # a number of `add_*()` functions are special cases of the scatter trace
+#' plot_ly(economics, x = ~date) %>% 
+#'   add_ribbons(ymin = ~pce - 1e3, ymax = ~pce + 1e3)
+#'
+#' # use `group_by()` (or `group2NA()`) to apply visual mapping
+#' # once per group (e.g. one line per group)
+#' txhousing %>% 
+#'   group_by(city) %>% 
+#'   plot_ly(x = ~date, y = ~median) %>%
+#'   add_lines(color = I("black"))
+#' 
+#' \dontrun{
+#' # use `add_sf()` or `add_polygons()` to create geo-spatial maps
+#' # http://blog.cpsievert.me/2018/03/30/visualizing-geo-spatial-data-with-sf-and-plotly/
+#' if (requireNamespace("sf", quietly = TRUE)) {
+#'   nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
+#'   plot_ly() %>% add_sf(data = nc)
+#' }
+#' 
+#' # univariate summary statistics
+#' plot_ly(mtcars, x = ~factor(vs), y = ~mpg) %>% 
+#'   add_boxplot()
+#' plot_ly(mtcars, x = ~factor(vs), y = ~mpg) %>% 
+#'   add_trace(type = "violin")
+#'   
+#' # `add_histogram()` does binning for you...
+#' mtcars %>%
+#'   plot_ly(x = ~factor(vs)) %>%
+#'   add_histogram()
+#'   
+#' # ...but you can 'pre-compute' bar heights in R
+#' mtcars %>%
+#'   dplyr::count(vs) %>%
+#'   plot_ly(x = ~vs, y = ~n) %>%
+#'   add_bars()
+#'
+#' # the 2d analogy of add_histogram() is add_histogram2d()/add_histogram2dcontour()
+#' library(MASS)
+#' (p <- plot_ly(geyser, x = ~waiting, y = ~duration))
+#' add_histogram2d(p)
+#' add_histogram2dcontour(p)
+#' 
+#' # the 2d analogy of add_bars() is add_heatmap()/add_contour()
+#' # (i.e., bin counts must be pre-specified)
+#' den <- kde2d(geyser$waiting, geyser$duration)
+#' p <- plot_ly(x = den$x, y = den$y, z = den$z)
+#' add_heatmap(p)
+#' add_contour(p)
+#' 
+#' # `add_table()` makes it easy to map a data frame to the table trace type
+#' plot_ly(economics) %>% 
+#'   add_table()
+#' 
+#' # pie charts!
+#' ds <- data.frame(labels = c("A", "B", "C"), values = c(10, 40, 60))
+#' plot_ly(ds, labels = ~labels, values = ~values) %>%
+#'   add_pie() %>%
+#'   layout(title = "Basic Pie Chart using Plotly")
+#'   
+#' data(wind)
+#' plot_ly(wind, r = ~r, t = ~t) %>% 
+#'   add_area(color = ~nms) %>%
+#'   layout(radialaxis = list(ticksuffix = "%"), orientation = 270)
+#' 
+#' # ------------------------------------------------------------
+#' # 3D chart types
+#' # ------------------------------------------------------------
+#' plot_ly(z = ~volcano) %>% 
+#'   add_surface()
+#' plot_ly(x = c(0, 0, 1), y = c(0, 1, 0), z = c(0, 0, 0)) %>% 
+#'   add_mesh()
+#' }
 #' 
 add_trace <- function(p, ...,
                       data = NULL, inherit = TRUE) {
@@ -143,11 +234,6 @@ add_paths <- function(p, x = NULL, y = NULL, z = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' txhousing %>% 
-#'   group_by(city) %>% 
-#'   plot_ly(x = ~date, y = ~median) %>%
-#'   add_lines(fill = "black")
 add_lines <- function(p, x = NULL, y = NULL, z = NULL, ...,
                       data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -192,15 +278,6 @@ add_segments <- function(p, x = NULL, y = NULL, xend = NULL, yend = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' 
-#' ggplot2::map_data("world", "canada") %>%
-#'   group_by(group) %>%
-#'   plot_ly(x = ~long, y = ~lat) %>%
-#'   add_polygons(hoverinfo = "none") %>%
-#'   add_markers(text = ~paste(name, "<br />", pop), hoverinfo = "text",
-#'     data = maps::canada.cities) %>%
-#'   layout(showlegend = FALSE)
 add_polygons <- function(p, x = NULL, y = NULL, ...,
                          data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -222,12 +299,6 @@ add_polygons <- function(p, x = NULL, y = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' 
-#' if (requireNamespace("sf", quietly = TRUE)) {
-#'   nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
-#'   plot_ly() %>% add_sf(data = nc)
-#' }
 add_sf <- function(p, ..., x = ~x, y = ~y, data = NULL, inherit = TRUE) {
   try_library("sf", "add_sf")
   dat <- plotly_data(add_data(p, data))
@@ -277,10 +348,6 @@ add_sf <- function(p, ..., x = ~x, y = ~y, data = NULL, inherit = TRUE) {
 #' @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))
@@ -308,11 +375,6 @@ add_table <- function(p, ..., rownames = TRUE, data = NULL, inherit = TRUE) {
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' 
-#' plot_ly(economics, x = ~date) %>% 
-#'   add_ribbons(ymin = ~pce - 1e3, ymax = ~pce + 1e3)
-
 add_ribbons <- function(p, x = NULL, ymin = NULL, ymax = NULL, ...,
                         data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -335,9 +397,6 @@ add_ribbons <- function(p, x = NULL, ymin = NULL, ymax = NULL, ...,
 #' @param r For polar chart only. Sets the radial coordinates.
 #' @param t For polar chart only. Sets the radial coordinates.
 #' @export
-#' @examples 
-#' p <- plot_ly(plotly::wind, r = ~r, t = ~t) %>% add_area(color = ~nms)
-#' layout(p, radialaxis = list(ticksuffix = "%"), orientation = 270)
 add_area <- function(p, r = NULL, t = NULL, ...,
                      data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -358,15 +417,6 @@ add_area <- function(p, r = NULL, t = NULL, ...,
 #' @param values the value to associated with each slice of the pie.
 #' @param labels the labels (categories) corresponding to `values`.
 #' @export
-#' @examples 
-#' ds <- data.frame(
-#'   labels = c("A", "B", "C"),
-#'   values = c(10, 40, 60)
-#' )
-#' 
-#' plot_ly(ds, labels = ~labels, values = ~values) %>%
-#'   add_pie() %>%
-#'   layout(title = "Basic Pie Chart using Plotly")
 add_pie <- function(p, values = NULL, labels = NULL, ...,
                      data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -385,12 +435,6 @@ add_pie <- function(p, values = NULL, labels = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' library(dplyr)
-#' mtcars %>%
-#'   count(vs) %>%
-#'   plot_ly(x = ~vs, y = ~n) %>%
-#'   add_bars()
 add_bars <- function(p, x = NULL, y = NULL, ...,
                      data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -411,9 +455,6 @@ add_bars <- function(p, x = NULL, y = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' 
-#' plot_ly(x = ~rnorm(100)) %>% add_histogram()
 add_histogram <- function(p, x = NULL, y = NULL, ...,
                           data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -434,10 +475,6 @@ add_histogram <- function(p, x = NULL, y = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(x = ~LETTERS, y = ~LETTERS) %>% add_histogram2d()
-#' z <- as.matrix(table(LETTERS, LETTERS))
-#' plot_ly(x = ~LETTERS, y = ~LETTERS, z = ~z) %>% add_histogram2d()
 add_histogram2d <- function(p, x = NULL, y = NULL, z = NULL, ...,
                             data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -460,9 +497,6 @@ add_histogram2d <- function(p, x = NULL, y = NULL, z = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(MASS::geyser, x = ~waiting, y = ~duration) %>% 
-#' add_histogram2dcontour()
 add_histogram2dcontour <- function(p, x = NULL, y = NULL, z = NULL, ...,
                                    data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -487,8 +521,6 @@ add_histogram2dcontour <- function(p, x = NULL, y = NULL, z = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(z = ~volcano) %>% add_heatmap()
 add_heatmap <- function(p, x = NULL, y = NULL, z = NULL, ..., 
                         data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -508,8 +540,6 @@ add_heatmap <- function(p, x = NULL, y = NULL, z = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(z = ~volcano) %>% add_contour()
 add_contour <- function(p, z = NULL, ..., data = NULL, inherit = TRUE) {
   if (inherit) {
     z <- z %||% p$x$attrs[[1]][["z"]]
@@ -527,8 +557,6 @@ add_contour <- function(p, z = NULL, ..., data = NULL, inherit = TRUE) {
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(mtcars, x = ~factor(vs), y = ~mpg) %>% add_boxplot()
 add_boxplot <- function(p, x = NULL, y = NULL, ..., data = NULL, inherit = TRUE) {
   if (inherit) {
     x <- x %||% p$x$attrs[[1]][["x"]]
@@ -547,8 +575,6 @@ add_boxplot <- function(p, x = NULL, y = NULL, ..., data = NULL, inherit = TRUE)
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(z = ~volcano) %>% add_surface()
 add_surface <- function(p, z = NULL, ..., data = NULL, inherit = TRUE) {
   if (inherit) {
     z <- z %||% p$x$attrs[[1]][["z"]]
@@ -565,8 +591,6 @@ add_surface <- function(p, z = NULL, ..., data = NULL, inherit = TRUE) {
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' plot_ly(x = c(0, 0, 1), y = c(0, 1, 0), z = c(0, 0, 0)) %>% add_mesh()
 add_mesh <- function(p, x = NULL, y = NULL, z = NULL, ..., 
                         data = NULL, inherit = TRUE) {
   if (inherit) {
@@ -654,30 +678,6 @@ special_attrs <- function(trace) {
 #' modified plotly object.
 #' @param ... arguments passed to `fun`.
 #' @export
-#' @examples
-#' 
-#' txhousing %>% 
-#'   group_by(city) %>%
-#'   plot_ly(x = ~date, y = ~median) %>%
-#'   add_lines(alpha = 0.2, name = "Texan Cities") %>%
-#'   add_fun(function(plot) {
-#'     plot %>% filter(city == "Houston") %>% add_lines(name = "Houston")
-#'   }) %>%
-#'   add_fun(function(plot) {
-#'     plot %>% filter(city == "San Antonio") %>% add_lines(name = "San Antonio")
-#'   })
-#'
-#' plot_ly(mtcars, x = ~wt, y = ~mpg) %>%
-#'   add_markers() %>%
-#'   add_fun(function(p) {
-#'     p %>% slice(which.max(mpg)) %>% 
-#'       add_annotations("Good mileage")
-#'   }) %>%
-#'   add_fun(function(p) {
-#'     p %>% slice(which.min(mpg)) %>% 
-#'       add_annotations(text = "Bad mileage")
-#'   })
-#'
 add_fun <- function(p, fun, ...) {
   oldDat <- p$x$cur_data
   p <- fun(p, ...)
@@ -699,19 +699,6 @@ add_fun <- function(p, fun, ...) {
 #' @param inherit inherit attributes from [plot_ly()]?
 #' @author Carson Sievert
 #' @export
-#' @examples
-#' 
-#' # single annotation
-#' plot_ly(mtcars, x = ~wt, y = ~mpg) %>%
-#'   slice(which.max(mpg)) %>%
-#'   add_annotations(text = "Good mileage")
-#'   
-#' # multiple annotations
-#' plot_ly(mtcars, x = ~wt, y = ~mpg) %>%
-#'   filter(gear == 5) %>%
-#'   add_annotations("five cylinder", ax = 40) 
-#'   
-
 add_annotations <- function(p, text = NULL, ..., data = NULL, inherit = TRUE) {
   p <- add_data(p, data)
   attrs <- list(text = text, ...)