provide scaling escape hatch via I(); add alpha argument; get missing values + group_by() working; various bug fixes and tests

Author: cpsievert

NEWS

@@ -5,23 +5,25 @@ BREAKING CHANGES & IMPROVEMENTS:
 * Formulas (instead of plain expressions) are now required when using variable mappings. For example, `plot_ly(mtcars, x = wt, y = mpg, color = vs)` should now be `plot_ly(mtcars, x = ~wt, y = ~mpg, color = ~vs)`. This is a major breaking change, but it is necessary to ensure that evaluation is correct in all contexts (as a result, `evaluate` argument is now deprecated as it is no longer needed). It also has the benefit of being easier to program with (i.e., writing your own custom functions that wrap `plot_ly()`). For more details, see the [lazyeval vignette](https://github.com/hadley/lazyeval/blob/master/vignettes/lazyeval.Rmd)
 * The data structure used to represent plotly objects is now an htmlwidget object (instead of a data frame with a special attribute tracking visual mappings). As a result, the `as.widget()` function has been deprecated, and [serialization/memory leak problems](https://github.com/rstudio/shiny/issues/1151) are no longer an issue. This change also implies that arbitrary data manipulation functions can no longer be intermingled inside a plot pipeline, but plotly methods for dplyr's data manipulation verbs are now provided (see `?plotly_data` for examples).
 * The `group` variable mapping no longer create multiple traces, but instead defines "gaps" within a trace (fixes #418, #381, #577). Groupings should be declared via the new `group_by()` function (see `help(plotly_data)` for examples) instead of the `group` argument (which is now deprecated).
-* `plot_ly()` now _initializes_ a plotly object (i.e., won't add a scatter trace by default), meaning that something like `plot_ly(x = 1:10, y = 1:10) %>% add_trace(y = 10:1)` will create one trace, instead of two. However, `plot_ly()` will draw a trace if you manually specify a trace type, for example, `plot_ly(x = 1:10, y = 1:10, type = "scatter") %>% add_trace(y = 10:1)` will draw two scatter traces. If no trace type is provided, a sensible type is inferred from the supplied data, and automatically added (i.e., `plot_ly(x = rnorm(100))` now creates a histogram).
+* `plot_ly()` now _initializes_ a plotly object (i.e., won't add a scatter trace by default), meaning that something like `plot_ly(x = 1:10, y = 1:10) %>% add_trace(y = 10:1)` creates one trace, instead of two. That being said, if you manually specify a trace type in `plot_ly()`, it will add a layer with that trace type (e.g. `plot_ly(x = 1:10, y = 1:10, type = "scatter") %>% add_trace(y = 10:1)` draws two scatter traces). If no trace type is provided, a sensible type is inferred from the supplied data, and automatically added (i.e., `plot_ly(x = rnorm(100))` now creates a histogram).
 * The `inherit` argument is deprecated. Any arguments/attributes specified in `plot_ly()` will automatically be passed along to additional traces added via `add_trace()` (or any of it's `add_*()` siblings).
-* Scales for aesthetics (e.g., `color`, `symbol`, `linetype`) are now applied at the plot-level, instead of the trace level. To avoid scaling, wrap the aesthetic value with `I()`, for example: `plot_ly(x = 1:10, y = 1:10, color = I("red"))`.
+* Aesthetic scaling (e.g., `color`, `symbol`, `size`) is applied at the plot-level, instead of the trace level. 
 
 NEW FEATURES & IMPROVEMENTS:
 
-* Error checking for trace and layout attributes.
-* New `add_polygons()`/`add_ribbons()`/`add_area()`/`add_segments()`/`add_lines()`/`add_markers()`/`add_paths()`/`add_text()` functions provide a shorthand for common visual markings.
-* New `plotly_data()` function for returning/inspecting data frame(s) associated with a plotly object.
-* New `plotly_json()` function for inspecting the data sent to plotly.js (as an R list or JSON).
-* Added `linetype`/`linetypes` arguments for mapping discrete variables to line types (this works very much like the `symbol`/`symbols`).
+* Added `linetype`/`linetypes` arguments for mapping discrete variables to line types (works very much like the `symbol`/`symbols`).
+* Scaling for aesthetics can be avoided via `I()` (closes #428). This is mainly useful for changing default appearance (e.g. `plot_ly(x = 1:10, y = 1:10, color = I(rainbow(10)))`).
+* Symbols and linetypes now recognize `pch` and `lty` values (e.g. `plot_ly(x = 1:25, y = 1:25, symbol = I(0:24))`)
+* A new `alpha` argument controls the alpha transparency of `color` (e.g. `plot_ly(x = 1:10, y = 1:10, color = I("red"), alpha = 0.1)`).
 * Added a `sizes` argument for controlling the range of marker size scaling.
+* New `add_polygons()`/`add_ribbons()`/`add_area()`/`add_segments()`/`add_lines()`/`add_markers()`/`add_paths()`/`add_text()` functions provide a shorthand for common special cases of `add_trace()`.
 * New `toWebGL()` function for easy conversion from SVG to WebGL.
 * New `export()` function makes it easy to save plots as png/jpeg/pdf (fixes #311).
+* Misspecified trace/layout attributes produce a warning.
+* New `plotly_data()` function for returning/inspecting data frame(s) associated with a plotly object.
+* New `plotly_json()` function for inspecting the data sent to plotly.js (as an R list or JSON).
 * `layout()` is now a generic function and uses method dispatch to avoid conflicts with `graphics:layout()` (fixes #464).
 
-
 OTHER CHANGES:
 
 * Upgraded to plotly.js v1.14.1 -- https://github.com/plotly/plotly.js/releases/tag/v1.14.1

R/add.R

@@ -30,6 +30,7 @@ add_data <- function(p, data = NULL) {
 #' @param ymin a variable used to define the lower boundary of a polygon.
 #' @param ymax a variable used to define the upper boundary of a polygon.
 #' @param color Either a variable name or a vector to use for color mapping.
+#' @param alpha alpha channel applied to color (on 0-1 scale).
 #' @param symbol Either a variable name or a (discrete) vector to use for symbol encoding.
 #' @param size A variable name or numeric vector to encode the size of markers.
 #' @param linetype Either a variable name or a (discrete) vector to use for linetype encoding.
@@ -84,34 +85,26 @@ add_trace <- function(p, ...,
 
 #' @inheritParams add_trace
 #' @rdname add_trace
-#' @param fill fill color. Supplies defaults for 
-#' \url{https://plot.ly/r/reference/#scatter-marker-color}
-#' @param stroke stroke color. Supplies defaults for 
-#' \url{https://plot.ly/r/reference/#scatter-marker-line-color}
-#' @param alpha alpha channel for fill/stroke (on 0-1 scale).
 #' @export
-add_markers <- function(p, x = NULL, y = NULL, fill = "rgba(31, 119, 180, 1)", 
-                        stroke = "rgba(31, 119, 180, 1)", alpha = 1, ...) {
+add_markers <- function(p, x = NULL, y = NULL, z = NULL, ...) {
   if (is.null(x <- x %||% p$x$attrs[[1]][["x"]])) {
     stop("Must supply `x` attribute", call. = FALSE)
   }
   if (is.null(y <- y %||% p$x$attrs[[1]][["y"]])) {
     stop("Must supply `y` attribute", call. = FALSE)
   }
-  # TODO: should stroke/fill inherit from the top-level?
-  marker <- modify_list(p$x$attrs[[1]][["marker"]], list(...)[["marker"]])
-  marker <- modify_list(marker, list(color = toRGB(fill, alpha)))
-  marker$line <- modify_list(marker$line, list(color = toRGB(stroke, alpha)))
+  hasZ <- !is.null(z <- z %||% p$x$attrs[[1]][["z"]])
+  type <- if (hasZ) "scatter3d" else "scatter"
   add_trace(
-    p, x = x, y = y, marker = marker, type = "scatter", mode = "markers", ...
+    p, x = x, y = y, type = type, mode = "markers", ...
   )
 }
 
 
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-add_text <- function(p, x = NULL, y = NULL, text = NULL, ...) {
+add_text <- function(p, x = NULL, y = NULL, z = NULL, text = NULL, ...) {
   if (is.null(x <- x %||% p$x$attrs[[1]][["x"]])) {
     stop("Must supply `x` attribute", call. = FALSE)
   }
@@ -121,22 +114,26 @@ add_text <- function(p, x = NULL, y = NULL, text = NULL, ...) {
   if (is.null(text <- text %||% p$x$attrs[[1]][["text"]])) {
     stop("Must supply `text` attribute", call. = FALSE)
   }
-  add_trace(p, x = x, y = y, text = text, type = "scatter", mode = "text",  ...)
+  hasZ <- !is.null(z <- z %||% p$x$attrs[[1]][["z"]])
+  type <- if (hasZ) "scatter3d" else "scatter"
+  add_trace(p, x = x, y = y, text = text, type = type, mode = "text",  ...)
 }
 
 
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-add_paths <- function(p, x = NULL, y = NULL, ...) {
+add_paths <- function(p, x = NULL, y = NULL, z = NULL, ...) {
   if (is.null(x <- x %||% p$x$attrs[[1]][["x"]])) {
     stop("Must supply `x` attribute", call. = FALSE)
   }
   if (is.null(y <- y %||% p$x$attrs[[1]][["y"]])) {
     stop("Must supply `y` attribute", call. = FALSE)
   }
+  hasZ <- !is.null(z <- z %||% p$x$attrs[[1]][["z"]])
+  type <- if (hasZ) "scatter3d" else "scatter"
   add_trace_classed(
-    p, x = x, y = y, class = "plotly_path", type = "scatter", mode = "lines", ...
+    p, x = x, y = y, class = "plotly_path", type = type, mode = "lines", ...
   )
 }
 
@@ -148,19 +145,18 @@ add_paths <- function(p, x = NULL, y = NULL, ...) {
 #'   group_by(city) %>% 
 #'   plot_ly(x = ~date, y = ~median) %>%
 #'   add_lines(fill = "black")
-add_lines <- function(p, x = NULL, y = NULL, stroke = NULL, alpha = 1, ...) {
+add_lines <- function(p, x = NULL, y = NULL, z = NULL, ...) {
   if (is.null(x <- x %||% p$x$attrs[[1]][["x"]])) {
     stop("Must supply `x` attribute", call. = FALSE)
   }
   if (is.null(y <- y %||% p$x$attrs[[1]][["y"]])) {
     stop("Must supply `y` attribute", call. = FALSE)
   }
-  
-  line <- modify_list(p$x$attrs[[1]][["line"]], list(...)[["line"]])
-  line <- modify_list(line, list(color = toRGB(stroke, alpha)))
+  hasZ <- !is.null(z <- z %||% p$x$attrs[[1]][["z"]])
+  type <- if (hasZ) "scatter3d" else "scatter"
 
   add_trace_classed(
-    p, x = x, y = y, line = line, class = "plotly_line", type = "scatter", mode = "lines", ...
+    p, x = x, y = y, class = "plotly_line", type = type, mode = "lines", ...
   )
 }
 
@@ -223,9 +219,7 @@ add_polygons <- function(p, x = NULL, y = NULL, ...) {
 #' plot_ly(economics, x = ~date) %>% 
 #'   add_ribbons(ymin = ~pce - 1e3, ymax = ~pce + 1e3)
 
-add_ribbons <- function(p, x = NULL, ymin = NULL, ymax = NULL, 
-                        fill = "rgba(31, 119, 180, 1)", 
-                        stroke = "transparent", alpha = 1, ...) {
+add_ribbons <- function(p, x = NULL, ymin = NULL, ymax = NULL, ...) {
   if (is.null(x <- x %||% p$x$attrs[[1]][["x"]])) {
     stop("Must supply `x` attribute", call. = FALSE)
   }
@@ -235,15 +229,11 @@ add_ribbons <- function(p, x = NULL, ymin = NULL, ymax = NULL,
   if (is.null(ymax <- ymax %||% p$x$attrs[[1]][["ymax"]])) {
     stop("Must supply `ymax` attribute", call. = FALSE)
   }
-  # TODO: should stroke/fill inherit from the top-level?
-  # probably not, since fill conflicts with scatter's fill attribute!
-  line <- modify_list(p$x$attrs[[1]][["line"]], list(...)[["line"]])
-  line <- modify_list(line, list(color = toRGB(stroke, alpha)))
 
   add_trace_classed(
     p, class = c("plotly_ribbon", "plotly_polygon"), 
     x = x, ymin = ymin, ymax = ymax, type = "scatter", mode = "lines",
-    line = line, fillcolor = toRGB(fill, alpha), fill = "toself",  ...
+    fill = "toself",  ...
   )
 }
 
@@ -426,9 +416,9 @@ add_surface <- function(p, z = NULL, ...) {
 #' @export
 #' @examples 
 #' plot_ly() %>% add_scattergeo()
-add_scattergeo <- function(p, ...) {
+add_scattergeo <- function(p, geo = "geo", ...) {
   add_trace_classed(
-    p, class = "plotly_scattergeo", type = "scattergeo", ...
+    p, class = "plotly_scattergeo", type = "scattergeo", geo = geo, ...
   )
 }
 
@@ -450,9 +440,6 @@ add_choropleth <- function(p, z = NULL, ...) {
   )
 }
 
-
-
-
 # attach a class to a trace which informs data processing in plotly_build
 add_trace_classed <- function(p, class = "plotly_polygon", ...) {
   p <- add_trace(p, ...)

R/layers2traces.R

@@ -723,7 +723,12 @@ pch2symbol <- function(x) {
     "O" = "circle-open",
     "+" = "cross-thin-open"
   )
-  as.character(lookup[as.character(x)])
+  x <- as.character(x)
+  idx <- x %in% names(lookup)
+  if (any(idx)) {
+    x[idx] <- lookup[x[idx]]
+  }
+  as.character(x)
 }
 
 # Convert R lty line type codes to plotly "dash" codes.
@@ -756,5 +761,10 @@ lty2dash <- function(x) {
     "224282F2" = "dash",
     "F1" = "dash"
   )
-  as.character(lookup[as.character(x)])
+  x <- as.character(x)
+  idx <- x %in% names(lookup)
+  if (any(idx)) {
+    x[idx] <- lookup[x[idx]]
+  }
+  as.character(x)
 }

R/plotly.R

@@ -10,16 +10,25 @@
 #' Note that acceptable arguments depend on the value of \code{type}.
 #' @param type A character string describing the type of trace. If \code{NULL}
 #' (the default), the initial trace type is determined by \code{add_trace}
-#' @param color Either a variable name or a vector to use for color mapping.
+#' @param color A formula containing a name or expression. 
+#' Values are scaled and mapped to color codes based on the value of 
+#' \code{colors} and \code{alpha}. To avoid scaling, wrap with \code{\link{I}()},
+#' and provide value(s) that can be converted to rgb color codes by 
+#' \code{\link[grDevices]{col2rgb}()}.
 #' @param colors Either a colorbrewer2.org palette name (e.g. "YlOrRd" or "Blues"), 
 #' or a vector of colors to interpolate in hexadecimal "#RRGGBB" format, 
 #' or a color interpolation function like \code{colorRamp()}.
-#' @param symbol Either a variable name or a (discrete) vector to use for symbol encoding.
+#' @param alpha A number between 0 and 1 specifying the alpha channel applied to color.
+#' @param symbol A formula containing a name or expression. 
+#' Values are scaled and mapped to symbols based on the value of \code{symbols}.
+#' To avoid scaling, wrap with \code{\link{I}()}, and provide valid 
+#' \code{\link{pch}()} values and/or valid plotly symbol(s) as a string
+#' \url{}
 #' @param symbols A character vector of symbol types. For possible values, see \link{schema}.
 #' @param linetype Either a variable name or a (discrete) vector to use for linetype encoding.
 #' @param linetypes A character vector of line types. For possible values, see \link{schema}.
 #' @param size A variable name or numeric vector to encode the size of markers.
-#' @param sizes a numeric vector of length 2 used to scale sizes to pixels.
+#' @param sizes A numeric vector of length 2 used to scale sizes to pixels.
 #' @param width	Width in pixels (optional, defaults to automatic sizing).
 #' @param height Height in pixels (optional, defaults to automatic sizing).
 #' @param source Only relevant for \link{event_data}.
@@ -35,15 +44,15 @@
 #' plot_ly(economics, x = ~date, y = ~pop)
 #' # plot_ly() doesn't require data frame(s), which allows one to take 
 #' # advantage of trace type(s) designed specifically for numeric matrices
-#' plot_ly(z = volcano)
-#' plot_ly(z = volcano, type = "surface")
+#' plot_ly(z = ~volcano)
+#' plot_ly(z = ~volcano, type = "surface")
 #' 
 #' # plotly has a functional interface: every plotly function takes a plotly
 #' # object as it's first input argument and returns a modified plotly object
-#' add_points(plot_ly(economics, x = ~date, y = ~unemploy/pop))
+#' add_lines(plot_ly(economics, x = ~date, y = ~unemploy/pop))
 #' 
 #' # To make code more readable, plotly imports the pipe operator from magrittr
-#' economics %>% plot_ly(x = ~date, y = ~unemploy/pop) %>% add_points()
+#' economics %>% plot_ly(x = ~date, y = ~unemploy/pop) %>% add_lines()
 #' 
 #' # Attributes defined via plot_ly() set 'global' attributes that 
 #' # are carried onto subsequent traces
@@ -66,9 +75,12 @@
 #' }
 #' 
 plot_ly <- function(data = data.frame(), ..., type = NULL, group,
-                    color, colors = NULL, symbol, symbols = NULL, 
+                    color, colors = NULL, alpha = 1, symbol, symbols = NULL, 
                     size, sizes = c(10, 100), linetype, linetypes = NULL,
                     width = NULL, height = NULL, source = "A") {
+  if (!is.data.frame(data)) {
+    stop("First argument, `data`, must be a data frame.", call. = FALSE)
+  }
   # "native" plotly arguments
   attrs <- list(...)
   # warn about old arguments that are no longer supported
@@ -96,6 +108,7 @@ plot_ly <- function(data = data.frame(), ..., type = NULL, group,
   attrs$size <- if (!missing(size)) size
 
   attrs$colors <- colors
+  attrs$alpha <- alpha
   attrs$symbols <- symbols
   attrs$linetypes <- linetypes
   attrs$sizes <- sizes