deprecate add_choropleth(); rename geo() -> plot_geo(); rename mapbox -> plot_mapbox()

Author: cpsievert

R/add.R

@@ -85,14 +85,14 @@ add_trace <- function(p, ..., color, symbol, size, linetype,
   if (is_mapbox(p) || is_geo(p)) {
     attrs[["x"]] <- attrs[["x"]] %||% attrs[["lat"]]
     attrs[["y"]] <- attrs[["y"]] %||% attrs[["lon"]]
-    if (!grepl("scatter", attrs[["type"]])) {
+    if (!grepl("scatter|choropleth", attrs[["type"]] %||% "scatter")) {
       stop("Cant add a '", attrs[["type"]], "' trace to a map object", call. = FALSE)
     }
     if (is_mapbox(p)) {
       attrs[["type"]] <- "scattermapbox"
     }
     if (is_geo(p)) {
-      attrs[["type"]] <- "scattergeo"
+      attrs[["type"]] <- if (!is.null(attrs[["z"]])) "choropleth" else "scattergeo"
     }
   }
 
@@ -528,7 +528,6 @@ add_mesh <- function(p, x = NULL, y = NULL, z = NULL, ...,
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' 
 add_scattergeo <- function(p, ...) {
   .Deprecated("geo")
   p
@@ -537,24 +536,10 @@ add_scattergeo <- function(p, ...) {
 #' @inheritParams add_trace
 #' @rdname add_trace
 #' @export
-#' @examples 
-#' density <- state.x77[, "Population"] / state.x77[, "Area"]
-#' plot_ly(z = ~density) %>% 
-#'   add_choropleth(locations = state.abb, locationmode = 'USA-states') %>%
-#'   layout(geo = list(scope = "usa"))
 add_choropleth <- function(p, z = NULL, geo = NULL, ..., 
                            data = NULL, inherit = TRUE) {
-  if (inherit) {
-    z <- z %||% p$x$attrs[[1]][["z"]]
-    geo <- geo %||% p$x$attrs[[1]][["geo"]] %||% "geo"
-  }
-  if (is.null(z)) {
-    stop("Must supply `z` attribute", call. = FALSE)
-  }
-  add_trace_classed(
-    p, class = "plotly_choropleth", z = z, type = "choropleth", geo = geo,
-    ..., data = data, inherit = inherit
-  )
+  .Deprecated("geo")
+  p
 }
 
 # attach a class to a trace which informs data processing in plotly_build

R/plotly.R

@@ -34,8 +34,14 @@
 #' @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}.
-#' @seealso \code{\link{layout}()}, \code{\link{add_trace}()}, \code{\link{style}()}
 #' @author Carson Sievert
+#' @seealso \itemize{
+#'  \item For initializing a plotly-geo object: \code{\link{plot_geo}()}.
+#'  \item For initializing a plotly-mapbox object: \code{\link{plot_mapbox}()}.
+#'  \item For translating a ggplot2 object to a plotly object: \code{\link{ggplotly}()}.
+#'  \item For modifying any plotly object: \code{\link{layout}()}, \code{\link{add_trace}()}, \code{\link{style}()}
+#'  \item
+#' }
 #' @export
 #' @examples
 #' \dontrun{
@@ -153,11 +159,14 @@ plot_ly <- function(data = data.frame(), ..., type = NULL,
 #' valid scattermapbox attributes - \url{https://plot.ly/r/reference/#scattermapbox}.
 #' Note that x/y can also be used in place of lat/lon.
 #' @export
+#' @author Carson Sievert
+#' @seealso \code{\link{plot_ly}()}, \code{\link{plot_geo}()}, \code{\link{ggplotly}()} 
+#' 
 #' @examples \dontrun{
 #' 
 #' map_data("world", "canada") %>%
 #'   group_by(group) %>%
-#'   mapbox(x = ~lat, y = ~long) %>%
+#'   plot_mapbox(x = ~lat, y = ~long) %>%
 #'   add_polygons() %>%
 #'   layout(
 #'     mapbox = list(
@@ -166,11 +175,12 @@ plot_ly <- function(data = data.frame(), ..., type = NULL,
 #'   )
 #' }
 #' 
-mapbox <- function(data = data.frame(), ...) {
-  p <- plot_ly(data, ...)
-  p <- config(p, mapboxAccessToken = mapbox_token())
-  p$x$mapType <- "mapbox"
-  p
+plot_mapbox <- function(data = data.frame(), ...) {
+  p <- config(plot_ly(data), mapboxAccessToken = mapbox_token())
+  # not only do we use this for is_mapbox(), but also setting the layout attr
+  # https://plot.ly/r/reference/#layout-mapbox
+  p$x$layout$mapType <- "mapbox"
+  add_trace(p, ...)
 }
 
 #' Initiate a plotly-geo object
@@ -182,17 +192,21 @@ mapbox <- function(data = data.frame(), ...) {
 #' 
 #' @param ... arguments passed along to \code{\link{plot_ly}()}.
 #' @export
+#' @author Carson Sievert
+#' @seealso \code{\link{plot_ly}()}, \code{\link{plot_mapbox}()}, \code{\link{ggplotly}()} 
 #' @examples
 #' 
 #' map_data("world", "canada") %>%
 #'   group_by(group) %>%
-#'   geo(x = ~lat, y = ~long) %>%
+#'   plot_geo(x = ~lat, y = ~long) %>%
 #'   add_polygons()
 #' 
-geo <- function(data = data.frame(), ...) {
-  p <- plot_ly(data, ...)
-  p$x$mapType <- "geo"
-  p
+plot_geo <- function(data = data.frame(), ...) {
+  p <- plot_ly(data)
+  # 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"
+  add_trace(p, ...)
 }