From 603b870aed69ae609e49219dcfba2901fdef6f63 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Mon, 6 Jan 2020 13:58:57 -0500
Subject: [PATCH 1/9] updating token

remove mapbox token from ci

using correct attribute name for mapbox token

moving access token paragraph to top of mapbox-layers example

re-adding token to examples that need it
---
 .circleci/config.yml                     |  1 +
 .gitignore                               |  3 ++
 r/2017-01-19-buttons.Rmd                 | 19 +++------
 r/2017-02-27-scattermapbox.Rmd           | 54 +++++++++++++++---------
 r/2017-04-12-county-level-choropleth.Rmd | 39 ++++++++---------
 r/2018-06-22-sf.Rmd                      | 31 +++++++++-----
 r/2019-09-20-filled-area-on-mapbox.Rmd   | 13 ------
 r/2019-09-20-mapbox-layers.Rmd           | 48 +++++++--------------
 r/2019-09-23-mapbox-density.Rmd          | 13 ------
 r/2019-09-27-lines-on-mapbox.Rmd         | 13 ------
 10 files changed, 100 insertions(+), 134 deletions(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 9027b14f..bbd0ec9f 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -39,6 +39,7 @@ jobs:
       - run:
           name: build site and perform front-matter checks
           command: |
+            echo ${mapbox_token} > .mapbox_token
             rm -rf build
             mkdir build
             mkdir build/ggplot2
diff --git a/.gitignore b/.gitignore
index 26fad6fa..bf671f29 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,9 @@
 # Session Data files
 .RData
 
+#mapbox dev token
+.mapbox_token 
+
 # Example code in package build process
 *-Ex.R
 
diff --git a/r/2017-01-19-buttons.Rmd b/r/2017-01-19-buttons.Rmd
index 06356a36..a6533c2d 100644
--- a/r/2017-01-19-buttons.Rmd
+++ b/r/2017-01-19-buttons.Rmd
@@ -17,15 +17,6 @@ output:
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -339,8 +330,10 @@ When adding buttons to Plotly charts, users have the option of styling the color
 ```{r}
 library(plotly)
 
-# make sure you have a Mapbox token https://www.mapbox.com/help/create-api-access-token/
-# Sys.setenv('MAPBOX_TOKEN' = 'your mapbox token')
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
 
 # read in wind turbines and farms data
 df_wind = read.csv('data/2805.csv')
@@ -426,8 +419,8 @@ p <- plot_mapbox(df_sub, lat = ~lat_DD, lon = ~long_DD, mode = 'scattermapbox',
                 yanchor = "bottom",
                 x = 1,
                 y = 0,
-                buttons=list(dark,basic,satellite)))) 
-
+                buttons=list(dark,basic,satellite)))) %>%
+  config(accesstoken = mapboxToken)
 
 p
 ```
diff --git a/r/2017-02-27-scattermapbox.Rmd b/r/2017-02-27-scattermapbox.Rmd
index 816ce9ca..42eb01ad 100644
--- a/r/2017-02-27-scattermapbox.Rmd
+++ b/r/2017-02-27-scattermapbox.Rmd
@@ -17,15 +17,6 @@ thumbnail: thumbnail/scatter-mapbox.jpg
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -37,25 +28,37 @@ We also have a quick-reference [cheatsheet](https://images.plot.ly/plotly-docume
 
 Version 4 of Plotly's R package is now [available](https://plot.ly/r/getting-started/#installation)!<br>
 Check out [this post](http://moderndata.plot.ly/upgrading-to-plotly-4-0-and-above/) for more information on breaking changes and new features available in this version.
+
 ```{r}
 library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
+### Mapbox Access Tokens and When You Need Them
 
-To create mapbox maps with Plotly, you'll need a Mapbox account and a [Mapbox Access Token](https://www.mapbox.com/studio/) that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox). If you're using a Chart Studio Enterprise server, please see additional instructions here: https://help.plot.ly/mapbox-atlas/.
-
-```{r}
-library(plotly)
-packageVersion('plotly')
-```
+  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
+    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
+    <h6>Base Maps in `layout.mapbox.style`</h6>
+    The accepted values for `layout.mapbox.style` are one of the following tiles.
+    <ol>
+        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
+        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
+        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
+    </ol>
 
 ### Basic Example
 
 ```{r}
 library(plotly)
 
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+
+
 dat <- map_data("world", "canada") %>% group_by(group)
 
 p <- plot_mapbox(dat, x = ~long, y = ~lat) %>%
@@ -64,7 +67,8 @@ p <- plot_mapbox(dat, x = ~long, y = ~lat) %>%
   layout(mapbox = list(zoom = 0,
                        center = list(lat = ~median(lat),
                                      lon = ~median(long))
-  ))
+  )) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
@@ -74,6 +78,11 @@ p
 ```{r}
 library(plotly)
 
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+
 df = read.csv('https://raw.githubusercontent.com/bcdunbar/datasets/master/meteorites_subset.csv')
 
 p <- df %>%
@@ -88,7 +97,8 @@ p <- df %>%
                        font = list(size = 8)),
          margin = list(l = 25, r = 25,
                        b = 25, t = 25,
-                       pad = 2))
+                       pad = 2)) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
@@ -99,6 +109,11 @@ p
 library(plotly)
 library(dplyr)
 
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+
 # airport locations
 air <- read.csv('https://raw.githubusercontent.com/plotly/datasets/master/2011_february_us_airport_traffic.csv')
 
@@ -125,7 +140,8 @@ p <- plot_mapbox(mode = 'scattermapbox') %>%
     margin = list(l = 0, r = 0,
                   b = 0, t = 0,
                   pad = 0),
-    showlegend=FALSE)
+    showlegend=FALSE) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
diff --git a/r/2017-04-12-county-level-choropleth.Rmd b/r/2017-04-12-county-level-choropleth.Rmd
index 7b35582b..ac5098ff 100644
--- a/r/2017-04-12-county-level-choropleth.Rmd
+++ b/r/2017-04-12-county-level-choropleth.Rmd
@@ -16,15 +16,6 @@ thumbnail: thumbnail/county-level-choropleth.jpg
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -41,9 +32,19 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
+### Mapbox Access Tokens and When You Need Them
 
-To create mapbox maps with Plotly, you'll need a Mapbox account and a [Mapbox Access Token](https://www.mapbox.com/studio/) that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox). If you're using a Chart Studio Enterprise server, please see additional instructions here: https://help.plot.ly/mapbox-atlas/.
+  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
+    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
+    <h6>Base Maps in `layout.mapbox.style`</h6>
+    The accepted values for `layout.mapbox.style` are one of the following tiles.
+    <ol>
+        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
+        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
+        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
+    </ol>
 
 ### Creating Polygon Boundaries
 
@@ -147,18 +148,13 @@ p
 ```
 
 ### Add Polygon to Mapbox
-
-To create mapbox maps with Plotly, you'll need a Mapbox account and a [Mapbox Access Token](https://www.mapbox.com/studio/) that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox).
-
-```{r, results = 'hide'}
+```{r}
 library(plotly)
 
-Sys.setenv('MAPBOX_TOKEN' = 'your_mapbox_token_here')
-```
-
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
 
-```{r}
-library(plotly)
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
 
 p <- cali_pop %>%
   group_by(group) %>%
@@ -179,7 +175,8 @@ p <- cali_pop %>%
       zoom = 4,
       center = list(lat = ~median(lat), lon = ~median(long))),
     margin = list(l = 0, r = 0, b = 0, t = 0, pad = 0)
-  )
+  ) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
\ No newline at end of file
diff --git a/r/2018-06-22-sf.Rmd b/r/2018-06-22-sf.Rmd
index 52ef0f98..1d9d6a52 100644
--- a/r/2018-06-22-sf.Rmd
+++ b/r/2018-06-22-sf.Rmd
@@ -16,15 +16,6 @@ thumbnail: thumbnail/sf.jpg
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -49,6 +40,20 @@ In order to complete the examples below, you'll require installing additional pa
 
 The examples below use the library [simple features](https://r-spatial.github.io/sf/) to read in the shape files before plotting the features with Plotly.
 
+### Mapbox Access Tokens and When You Need Them
+
+  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
+    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
+    <h6>Base Maps in `layout.mapbox.style`</h6>
+    The accepted values for `layout.mapbox.style` are one of the following tiles.
+    <ol>
+        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
+        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
+        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
+        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
+    </ol>
+
 ### Basic sf 
 
 ``` {r}
@@ -81,6 +86,11 @@ Or `plot_mapbox`:
 library(plotly)
 library(sf)
 
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
 
 p <- plot_mapbox(nc, split=~NAME) %>%
@@ -88,7 +98,8 @@ p <- plot_mapbox(nc, split=~NAME) %>%
     mapbox = list(
       zoom = 6
     )
-  )
+  ) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
diff --git a/r/2019-09-20-filled-area-on-mapbox.Rmd b/r/2019-09-20-filled-area-on-mapbox.Rmd
index 37fb9355..dba58f17 100644
--- a/r/2019-09-20-filled-area-on-mapbox.Rmd
+++ b/r/2019-09-20-filled-area-on-mapbox.Rmd
@@ -17,15 +17,6 @@ thumbnail: thumbnail/area.jpg
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -42,10 +33,6 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly you `may` need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio), that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
-
 ### How to Show an Area on a Map
 
 There are three different ways to show an area in a mapbox:
diff --git a/r/2019-09-20-mapbox-layers.Rmd b/r/2019-09-20-mapbox-layers.Rmd
index 82bda885..3522d56b 100644
--- a/r/2019-09-20-mapbox-layers.Rmd
+++ b/r/2019-09-20-mapbox-layers.Rmd
@@ -33,34 +33,6 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
-
-To create mapbox maps with Plotly, you'll need a Mapbox account and a [Mapbox Access Token](https://www.mapbox.com/studio/) that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox). If you're using a Chart Studio Enterprise server, please see additional instructions here: https://help.plot.ly/mapbox-atlas/.
-
-```{r, results = 'hide'}
-library(plotly)
-Sys.setenv('MAPBOX_TOKEN' = 'your_mapbox_token_here')
-```
-
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
-### How Layers work in Mapbox Maps
-
-  If your figure contains one or more traces of type `Scattermapbox`, `Choroplethmapbox` or `Densitymapbox`, the `layout` object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types.
-    <ol>
-        <li> `layout.mapbox.style` defines the lowest layers, also known as your "base map"</li>
-        <li> The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).</li>
-        <li> `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
-    </ol>
-
-
 ### Mapbox Access Tokens and When You Need Them
 
   The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
@@ -75,6 +47,15 @@ Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
         <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
     </ol>
 
+### How Layers work in Mapbox Maps
+
+  If your figure contains one or more traces of type `Scattermapbox`, `Choroplethmapbox` or `Densitymapbox`, the `layout` object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types.
+    <ol>
+        <li> `layout.mapbox.style` defines the lowest layers, also known as your "base map"</li>
+        <li> The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).</li>
+        <li> `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
+    </ol>
+
 ### OpenStreetMap Tiles, no Token Needed
 
    Here is a simple map rendered with "open-street-map" tiles, without needing a Mapbox Access Token.
@@ -95,7 +76,7 @@ p <- us_cities %>%
     mapbox = list(
       style = 'open-street-map',
       zoom =2.5,
-      center = list(lon = -88, lat = 34)))
+      center = list(lon = -88, lat = 34))) 
 
 p
 ```
@@ -171,7 +152,10 @@ Here is a map rendered with the `"dark"` style from the Mapbox service, which re
 ```{r}
 library(plotly)
 
-#mapboxToken <- paste(readLines(".mapbox_token"), collapse="")    # You need your own token
+mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
+
+# Setting mapbox token for R environment 
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
 
 us_cities = read.csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
 
@@ -185,9 +169,9 @@ p <- us_cities %>%
   layout(
     mapbox = list(
       style = 'dark',
-      accesstoken = mapboxToken,
       zoom =2.5,
-      center = list(lon = -88, lat = 34)))
+      center = list(lon = -88, lat = 34))) %>%
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
diff --git a/r/2019-09-23-mapbox-density.Rmd b/r/2019-09-23-mapbox-density.Rmd
index 14a674c6..c373e367 100644
--- a/r/2019-09-23-mapbox-density.Rmd
+++ b/r/2019-09-23-mapbox-density.Rmd
@@ -17,15 +17,6 @@ thumbnail: thumbnail/mapbox-density.png
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -42,10 +33,6 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information.
-
 #### Stamen Terrain Tile, no Token Needed
 
 ```{r}
diff --git a/r/2019-09-27-lines-on-mapbox.Rmd b/r/2019-09-27-lines-on-mapbox.Rmd
index ed2fdf5b..24706b72 100644
--- a/r/2019-09-27-lines-on-mapbox.Rmd
+++ b/r/2019-09-27-lines-on-mapbox.Rmd
@@ -17,15 +17,6 @@ thumbnail: thumbnail/line_mapbox.jpg
 knitr::opts_chunk$set(message = FALSE, warning=FALSE)
 ```
 
-```{r, echo = FALSE}
-# Mapbox token for plotly | this one is for plot_mapbox figure
-mapboxToken <- paste("pk.eyJ1IjoicGxvdGx5bWFwYm94IiwiYSI6ImNqdnBvNDMyaT",
-                "AxYzkzeW5ubWdpZ2VjbmMifQ.TXcBE-xg9BFdV2ocecc_7g", sep = "")
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
-```
-
 ### New to Plotly?
 
 Plotly's R library is free and open source!<br>
@@ -42,10 +33,6 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly you `may` need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio), that you can add to your [Plotly Settings](https://plot.ly/settings/mapbox). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
-
 ### How to draw a Line on a Map
 
 To draw a line on your map, you either can use [Scattermapbox](https://plot.ly/r/reference/#scattermapbox) or [scattergeo](https://plot.ly/r/reference/#scattergeo) trace type in plotly. This example uses scattermapbox and defines the drawing [mode](https://plot.ly/python/reference/#scattermapbox-mode) to the combination of markers and line.

From 8ff0958eb9c48b8cb2fc97495abbf96363106ee9 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Thu, 9 Jan 2020 15:25:41 -0500
Subject: [PATCH 2/9] changes in response to PR review- reorg structure of maps
 docs

---
 r/2017-01-19-buttons.Rmd                 |  6 +-
 r/2017-02-27-scattermapbox.Rmd           | 34 +++------
 r/2017-04-12-county-level-choropleth.Rmd | 22 ++----
 r/2018-06-22-sf.Rmd                      | 26 ++-----
 r/2019-09-20-filled-area-on-mapbox.Rmd   |  8 ++-
 r/2019-09-20-mapbox-layers.Rmd           | 87 +++++++++++++-----------
 r/2019-09-23-mapbox-density.Rmd          |  5 ++
 r/2019-09-27-lines-on-mapbox.Rmd         |  6 +-
 8 files changed, 91 insertions(+), 103 deletions(-)

diff --git a/r/2017-01-19-buttons.Rmd b/r/2017-01-19-buttons.Rmd
index a6533c2d..c127de14 100644
--- a/r/2017-01-19-buttons.Rmd
+++ b/r/2017-01-19-buttons.Rmd
@@ -327,6 +327,10 @@ Animations are currently only available in the [development package](https://plo
 
 When adding buttons to Plotly charts, users have the option of styling the color, font, padding, and position of the buttons. The example below demostrates hot to apply different styling options. See all updatemenus styling attributes here: https://plot.ly/r/reference/#layout-updatemenus. 
 
+#### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+
 ```{r}
 library(plotly)
 
@@ -420,7 +424,7 @@ p <- plot_mapbox(df_sub, lat = ~lat_DD, lon = ~long_DD, mode = 'scattermapbox',
                 x = 1,
                 y = 0,
                 buttons=list(dark,basic,satellite)))) %>%
-  config(accesstoken = mapboxToken)
+  config(mapboxAccessToken = mapboxToken)
 
 p
 ```
diff --git a/r/2017-02-27-scattermapbox.Rmd b/r/2017-02-27-scattermapbox.Rmd
index 42eb01ad..2d900cef 100644
--- a/r/2017-02-27-scattermapbox.Rmd
+++ b/r/2017-02-27-scattermapbox.Rmd
@@ -34,19 +34,9 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Tokens and When You Need Them
-
-  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
-    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
-    <h6>Base Maps in `layout.mapbox.style`</h6>
-    The accepted values for `layout.mapbox.style` are one of the following tiles.
-    <ol>
-        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
-        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
-        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
-    </ol>
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Basic Example
 
@@ -54,9 +44,7 @@ packageVersion('plotly')
 library(plotly)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 
 dat <- map_data("world", "canada") %>% group_by(group)
@@ -68,7 +56,7 @@ p <- plot_mapbox(dat, x = ~long, y = ~lat) %>%
                        center = list(lat = ~median(lat),
                                      lon = ~median(long))
   )) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
@@ -79,9 +67,7 @@ p
 library(plotly)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 df = read.csv('https://raw.githubusercontent.com/bcdunbar/datasets/master/meteorites_subset.csv')
 
@@ -98,7 +84,7 @@ p <- df %>%
          margin = list(l = 25, r = 25,
                        b = 25, t = 25,
                        pad = 2)) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
@@ -110,9 +96,7 @@ library(plotly)
 library(dplyr)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 # airport locations
 air <- read.csv('https://raw.githubusercontent.com/plotly/datasets/master/2011_february_us_airport_traffic.csv')
@@ -141,7 +125,7 @@ p <- plot_mapbox(mode = 'scattermapbox') %>%
                   b = 0, t = 0,
                   pad = 0),
     showlegend=FALSE) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
diff --git a/r/2017-04-12-county-level-choropleth.Rmd b/r/2017-04-12-county-level-choropleth.Rmd
index ac5098ff..3015fc10 100644
--- a/r/2017-04-12-county-level-choropleth.Rmd
+++ b/r/2017-04-12-county-level-choropleth.Rmd
@@ -32,19 +32,9 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Tokens and When You Need Them
-
-  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
-    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
-    <h6>Base Maps in `layout.mapbox.style`</h6>
-    The accepted values for `layout.mapbox.style` are one of the following tiles.
-    <ol>
-        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
-        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
-        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
-    </ol>
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Creating Polygon Boundaries
 
@@ -152,9 +142,7 @@ p
 library(plotly)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 p <- cali_pop %>%
   group_by(group) %>%
@@ -176,7 +164,7 @@ p <- cali_pop %>%
       center = list(lat = ~median(lat), lon = ~median(long))),
     margin = list(l = 0, r = 0, b = 0, t = 0, pad = 0)
   ) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
\ No newline at end of file
diff --git a/r/2018-06-22-sf.Rmd b/r/2018-06-22-sf.Rmd
index 1d9d6a52..21625699 100644
--- a/r/2018-06-22-sf.Rmd
+++ b/r/2018-06-22-sf.Rmd
@@ -40,21 +40,11 @@ In order to complete the examples below, you'll require installing additional pa
 
 The examples below use the library [simple features](https://r-spatial.github.io/sf/) to read in the shape files before plotting the features with Plotly.
 
-### Mapbox Access Tokens and When You Need Them
-
-  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
-    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
-    <h6>Base Maps in `layout.mapbox.style`</h6>
-    The accepted values for `layout.mapbox.style` are one of the following tiles.
-    <ol>
-        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
-        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
-        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
-    </ol>
-
-### Basic sf 
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+
+### Basic sf
 
 ``` {r}
 library(plotly)
@@ -87,9 +77,7 @@ library(plotly)
 library(sf)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
 
@@ -99,7 +87,7 @@ p <- plot_mapbox(nc, split=~NAME) %>%
       zoom = 6
     )
   ) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
diff --git a/r/2019-09-20-filled-area-on-mapbox.Rmd b/r/2019-09-20-filled-area-on-mapbox.Rmd
index dba58f17..65706d28 100644
--- a/r/2019-09-20-filled-area-on-mapbox.Rmd
+++ b/r/2019-09-20-filled-area-on-mapbox.Rmd
@@ -32,6 +32,9 @@ Check out [this post](http://moderndata.plot.ly/upgrading-to-plotly-4-0-and-abov
 library(plotly)
 packageVersion('plotly')
 ```
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### How to Show an Area on a Map
 
@@ -41,7 +44,8 @@ There are three different ways to show an area in a mapbox:
     <li> Use [Scattermapbox](https://plot.ly/r/reference/#scattermapbox) trace and define the corresponding geojson</li>
     <li> Use the new trace type: [Choroplethmapbox](https://plot.ly/r/mapbox-county-choropleth/) for mapbox cases, or [Choropleth](https://plot.ly/r/choropleth-maps/) trace for non-mapbox ones.</li>
 </ol>
-The following example uses `Scattermapbox` and sets `fill = 'toself'`
+
+The following example uses the `Scattermapbox` trace and sets `fill = 'toself'`
 
 ```{r}
 library(plotly)
@@ -89,7 +93,7 @@ p
 
 ### Use the Corresponding Geojson
 
-The second way is using Scattermapbox trace with the corresponding geojson.
+The second way is using the `scattermapbox` trace with the corresponding geojson.
 
 ```{r}
 library(plotly)
diff --git a/r/2019-09-20-mapbox-layers.Rmd b/r/2019-09-20-mapbox-layers.Rmd
index 3522d56b..a4adda05 100644
--- a/r/2019-09-20-mapbox-layers.Rmd
+++ b/r/2019-09-20-mapbox-layers.Rmd
@@ -35,30 +35,47 @@ packageVersion('plotly')
 
 ### Mapbox Access Tokens and When You Need Them
 
-  The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided either in `mapboxAccessToken`  in `setPlotConfig` function, or as a variable that would be passed as an argument of `newPlot`.
-    If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
-    <h6>Base Maps in `layout.mapbox.style`</h6>
-    The accepted values for `layout.mapbox.style` are one of the following tiles.
-    <ol>
-        <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
-        <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
-        <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
-        <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
-    </ol>
-
-### How Layers work in Mapbox Maps
-
-  If your figure contains one or more traces of type `Scattermapbox`, `Choroplethmapbox` or `Densitymapbox`, the `layout` object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types.
-    <ol>
-        <li> `layout.mapbox.style` defines the lowest layers, also known as your "base map"</li>
-        <li> The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).</li>
-        <li> `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
-    </ol>
+The [`plot_ly(layout(mapbox()))`](https://plot.ly/r/reference/#layout-mapbox) call signature contains base maps which are collected from the [MapBox](https://mapbox.com) API.
+
+If the base map you specify in the `plot_ly(layout(mapbox(style())))` call signature uses data from the Mapbox *service* that requires a MapBox Access Token, then you will need to register for a free account at https://mapbox.com/ and obtain and use your own Mapbox Access token. 
+
+If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+
+#### - The following values of the `style` attribute **DO** require an Access Token:
+<ol>
+  <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
+  <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
+  <li> A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/ </li>
+</ol>
+
+- We recommend setting your MapBox Access Token as an environment variable in your R environment. That way, your token will not be committed to version control. See [Basemap Requiring MapBox Access Token](#basemap-requiring-mapbox-access-token)
+
+#### - The following values of the style attribute **DO NOT** require an Access Token:
+<ol>
+  <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
+  <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
+</ol>
+
+### How Layers Work in Mapbox Maps
+
+If your figure contains one or more traces of type `scattermapbox`, `choroplethmapbox` or `densitymapbox`, the `layout` call signature of your figure contains configuration information for the map itself. 
+
+The map is composed of layers of three different types.
+<ol>
+  <li> `layout(mapbox(style))` call signature defines the lowest layers, also known as your "base map"</li>
+  <li> The various traces in the `plot_ly` call signature are by default rendered above the base map (this can be controlled via the use of `below` attribute).</li>
+  <li> `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
+</ol>
+
+#### Using the `plot_ly(layout(mapbox(layers())))` to Specify a Base Map
+
+If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set use the `layout(mapbox(style()))` call signature to `"white-bg"` and then the use `layout(mapbox(layers()))` call signature with the `below` attribute to specify a custom base map.
+
+> If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
 
 ### OpenStreetMap Tiles, no Token Needed
 
-   Here is a simple map rendered with "open-street-map" tiles, without needing a Mapbox Access Token.
+This chart demonstrates how to use "open-street-map" tiles as the base map for a chart. A Mapbox Access Token is not required.
 
 ```{r}
 library(plotly)
@@ -81,15 +98,9 @@ p <- us_cities %>%
 p
 ```
 
-### Using `layout.mapbox.layers` to Specify a Base Map
+### Base Map Below A Trace: No Token Needed
 
-If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set `layout.mapbox.style` to `"white-bg"` and to use `layout.mapbox.layers` with `below` to specify a custom base map.
-
-> If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
-
-### Base Tiles from the USGS: no Token Needed
-
-Here is an example of a map which uses a public USGS imagery map, specified in `layout.mapbox.layers`, and which is rendered *below* the `data` layer.
+This chart demonstrates how to use a public USGS imagery map as a base map, specified in the `layout(mapbox(layers()))` call signature, and which is rendered *below* the trace.
 
 ```{r}
 library(plotly)
@@ -115,9 +126,9 @@ p <-  us_cities %>%
 p
 ```
 
-#### Base Tiles from the USGS, Radar Overlay from Environment Canada: no Token Needed
+#### Maps Below and Above A Trace: No Token Needed
 
-Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the `go.Scattermapbox` trace, as is the default:
+This example uses the same basemap as the one above. However, in this case, partly-transparent raster tiles are rendered above the trace as well.
 
 ```{r}
 library(plotly)
@@ -145,17 +156,17 @@ p <- us_cities %>%
 p
 ```
 
-#### Dark Tiles from Mapbox Service: Free Token Needed
+#### Map Requiring MapBox Access Token
 
-Here is a map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
+This example demonstrates how to use a MapBox Access token in order to use a "dark" base map from MapBox, which requires API authentication. 
+
+In this case, the Access Token is stored in an environment variable which is then passed to the chart configuration call signature. 
 
 ```{r}
 library(plotly)
 
 mapboxToken <- paste(readLines("../.mapbox_token"), collapse="")    # You need your own token
-
-# Setting mapbox token for R environment 
-Sys.setenv("MAPBOX_TOKEN" = mapboxToken)
+Sys.setenv("MAPBOX_TOKEN" = mapboxToken) # for Orca
 
 us_cities = read.csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
 
@@ -171,11 +182,11 @@ p <- us_cities %>%
       style = 'dark',
       zoom =2.5,
       center = list(lon = -88, lat = 34))) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```
 
 #Reference
 
-See [https://plot.ly/r/reference/#scattermapbox](https://plot.ly/r/reference/#scattermapbox) for more information and options!
\ No newline at end of file
+See [https://plot.ly/r/reference/#scattermapbox](https://plot.ly/r/reference/#scattermapbox) for more information and options!
diff --git a/r/2019-09-23-mapbox-density.Rmd b/r/2019-09-23-mapbox-density.Rmd
index c373e367..881fe5b3 100644
--- a/r/2019-09-23-mapbox-density.Rmd
+++ b/r/2019-09-23-mapbox-density.Rmd
@@ -33,6 +33,11 @@ library(plotly)
 packageVersion('plotly')
 ```
 
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+
+
 #### Stamen Terrain Tile, no Token Needed
 
 ```{r}
diff --git a/r/2019-09-27-lines-on-mapbox.Rmd b/r/2019-09-27-lines-on-mapbox.Rmd
index 24706b72..5d6905cb 100644
--- a/r/2019-09-27-lines-on-mapbox.Rmd
+++ b/r/2019-09-27-lines-on-mapbox.Rmd
@@ -33,6 +33,10 @@ library(plotly)
 packageVersion('plotly')
 ```
 
+### Mapbox Access Token
+
+To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+
 ### How to draw a Line on a Map
 
 To draw a line on your map, you either can use [Scattermapbox](https://plot.ly/r/reference/#scattermapbox) or [scattergeo](https://plot.ly/r/reference/#scattergeo) trace type in plotly. This example uses scattermapbox and defines the drawing [mode](https://plot.ly/python/reference/#scattermapbox-mode) to the combination of markers and line.
@@ -62,7 +66,7 @@ p <- plot_ly(
 p
 ```
 
-This example uses scattermapbox trace and shows how to customize hoverinfo in Mapbox.
+This example uses `scattermapbox` trace and shows how to customize hoverinfo in Mapbox.
 
 ```{r}
 library(plotly)

From b3bf29e054ca7bdc96ce78c274c10d6f44bcbd5f Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Thu, 9 Jan 2020 15:35:41 -0500
Subject: [PATCH 3/9] typo

---
 r/2019-09-20-mapbox-layers.Rmd | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/r/2019-09-20-mapbox-layers.Rmd b/r/2019-09-20-mapbox-layers.Rmd
index a4adda05..57112d29 100644
--- a/r/2019-09-20-mapbox-layers.Rmd
+++ b/r/2019-09-20-mapbox-layers.Rmd
@@ -62,14 +62,14 @@ If your figure contains one or more traces of type `scattermapbox`, `choroplethm
 
 The map is composed of layers of three different types.
 <ol>
-  <li> `layout(mapbox(style))` call signature defines the lowest layers, also known as your "base map"</li>
+  <li> the `layout(mapbox(style))` call signature defines the lowest layers, also known as your "base map"</li>
   <li> The various traces in the `plot_ly` call signature are by default rendered above the base map (this can be controlled via the use of `below` attribute).</li>
-  <li> `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
+  <li> the `layout(mapbox(layers()))` call signature is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
 </ol>
 
-#### Using the `plot_ly(layout(mapbox(layers())))` to Specify a Base Map
+#### Using `plot_ly(layout(mapbox(layers())))` to Specify a Base Map
 
-If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set use the `layout(mapbox(style()))` call signature to `"white-bg"` and then the use `layout(mapbox(layers()))` call signature with the `below` attribute to specify a custom base map.
+If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set use the `layout(mapbox(style()))` call signature to `"white-bg"` and then the use the `layout(mapbox(layers()))` call signature with the `below` attribute to specify a custom base map.
 
 > If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
 

From 38037c691b514be4d41171869d2de0ba0c3e1e91 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Thu, 9 Jan 2020 15:37:25 -0500
Subject: [PATCH 4/9] use env variable

---
 r/2017-01-19-buttons.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/r/2017-01-19-buttons.Rmd b/r/2017-01-19-buttons.Rmd
index c127de14..101d36c0 100644
--- a/r/2017-01-19-buttons.Rmd
+++ b/r/2017-01-19-buttons.Rmd
@@ -424,7 +424,7 @@ p <- plot_mapbox(df_sub, lat = ~lat_DD, lon = ~long_DD, mode = 'scattermapbox',
                 x = 1,
                 y = 0,
                 buttons=list(dark,basic,satellite)))) %>%
-  config(mapboxAccessToken = mapboxToken)
+  config(mapboxAccessToken = Sys.getenv("MAPBOX_TOKEN"))
 
 p
 ```

From 9bdb1378a0e31cdbffa7ae92c739cd6a9f89ea3f Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Thu, 9 Jan 2020 16:48:11 -0500
Subject: [PATCH 5/9] add listviewer to dependencies

---
 DESCRIPTION | 1 +
 1 file changed, 1 insertion(+)

diff --git a/DESCRIPTION b/DESCRIPTION
index a09e976c..a136db61 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -22,6 +22,7 @@ Imports:
     forcats,
     ggplot2,
     haven,
+    listviewer,
     hms,
     httr,
     jsonlite,

From 1ed3847537ebdecbb77033a883820bed7918cda9 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Fri, 10 Jan 2020 07:48:37 -0500
Subject: [PATCH 6/9] removing block mistakenly added to resolve merge conflict

---
 r/2019-09-27-lines-on-mapbox.Rmd | 32 --------------------------------
 1 file changed, 32 deletions(-)

diff --git a/r/2019-09-27-lines-on-mapbox.Rmd b/r/2019-09-27-lines-on-mapbox.Rmd
index 1837d607..f4faf8aa 100644
--- a/r/2019-09-27-lines-on-mapbox.Rmd
+++ b/r/2019-09-27-lines-on-mapbox.Rmd
@@ -63,38 +63,6 @@ p <- plot_ly(
       zoom = 1),
     margin =list(l=0,t=0,b=0,r=0))
 
-p
-```
-
-This example uses `scattermapbox` trace and shows how to customize hoverinfo in Mapbox.
-
-```{r}
-library(plotly)
-
-us_cities = read.csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
-
-df = us_cities[us_cities$State == c('Washington'),]
-
-
-p <- plot_ly(
-    df,
-    lat= ~lat,
-    lon= ~lon,
-    type = 'scattermapbox',
-    mode='markers+lines',
-    marker=list(
-      color = 'fuchsia',
-      size = 10,
-      opacity =0.8),
-    color = list('color'),
-    hovertext = ~City,
-    hoverinfo = "lat+lon+text") %>%
-  layout(
-    mapbox=list(style = 'stamen-terrain',
-                center = list(lat =47, lon = -122),
-                zoom =5),
-    margin=list(r = 0,t = 0, l = 0, b = 0))
-
 p
 ```
 #Reference

From 8f0624df3aa0271468060aef294656ffce85cbfe Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Fri, 10 Jan 2020 07:50:19 -0500
Subject: [PATCH 7/9] replaying may in quotes with italics

---
 r/2017-01-19-buttons.Rmd                 | 2 +-
 r/2017-02-27-scattermapbox.Rmd           | 2 +-
 r/2017-04-12-county-level-choropleth.Rmd | 2 +-
 r/2018-06-22-sf.Rmd                      | 2 +-
 r/2019-09-20-filled-area-on-mapbox.Rmd   | 2 +-
 r/2019-09-23-mapbox-density.Rmd          | 2 +-
 r/2019-09-27-lines-on-mapbox.Rmd         | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/r/2017-01-19-buttons.Rmd b/r/2017-01-19-buttons.Rmd
index 101d36c0..8ce72eeb 100644
--- a/r/2017-01-19-buttons.Rmd
+++ b/r/2017-01-19-buttons.Rmd
@@ -329,7 +329,7 @@ When adding buttons to Plotly charts, users have the option of styling the color
 
 #### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ```{r}
 library(plotly)
diff --git a/r/2017-02-27-scattermapbox.Rmd b/r/2017-02-27-scattermapbox.Rmd
index 2d900cef..eb8d6116 100644
--- a/r/2017-02-27-scattermapbox.Rmd
+++ b/r/2017-02-27-scattermapbox.Rmd
@@ -36,7 +36,7 @@ packageVersion('plotly')
 
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Basic Example
 
diff --git a/r/2017-04-12-county-level-choropleth.Rmd b/r/2017-04-12-county-level-choropleth.Rmd
index 3015fc10..94be13d6 100644
--- a/r/2017-04-12-county-level-choropleth.Rmd
+++ b/r/2017-04-12-county-level-choropleth.Rmd
@@ -34,7 +34,7 @@ packageVersion('plotly')
 
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Creating Polygon Boundaries
 
diff --git a/r/2018-06-22-sf.Rmd b/r/2018-06-22-sf.Rmd
index 21625699..a33a9127 100644
--- a/r/2018-06-22-sf.Rmd
+++ b/r/2018-06-22-sf.Rmd
@@ -42,7 +42,7 @@ The examples below use the library [simple features](https://r-spatial.github.io
 
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Basic sf
 
diff --git a/r/2019-09-20-filled-area-on-mapbox.Rmd b/r/2019-09-20-filled-area-on-mapbox.Rmd
index 65706d28..8a8467cb 100644
--- a/r/2019-09-20-filled-area-on-mapbox.Rmd
+++ b/r/2019-09-20-filled-area-on-mapbox.Rmd
@@ -34,7 +34,7 @@ packageVersion('plotly')
 ```
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### How to Show an Area on a Map
 
diff --git a/r/2019-09-23-mapbox-density.Rmd b/r/2019-09-23-mapbox-density.Rmd
index 881fe5b3..cad78787 100644
--- a/r/2019-09-23-mapbox-density.Rmd
+++ b/r/2019-09-23-mapbox-density.Rmd
@@ -35,7 +35,7 @@ packageVersion('plotly')
 
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 
 #### Stamen Terrain Tile, no Token Needed
diff --git a/r/2019-09-27-lines-on-mapbox.Rmd b/r/2019-09-27-lines-on-mapbox.Rmd
index f4faf8aa..4c027054 100644
--- a/r/2019-09-27-lines-on-mapbox.Rmd
+++ b/r/2019-09-27-lines-on-mapbox.Rmd
@@ -35,7 +35,7 @@ packageVersion('plotly')
 
 ### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you "may" need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
+To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/r/mapbox-layers/) documentation for more information. If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
 ### Lines on Mapbox maps using "Scattermapbox" traces
 

From dedeb6fc36c3ae6b5341d55dc69cbc207b04ab20 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Fri, 10 Jan 2020 09:43:26 -0500
Subject: [PATCH 8/9] reorganizing mapbox-layers doc

---
 r/2019-09-20-mapbox-layers.Rmd | 32 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/r/2019-09-20-mapbox-layers.Rmd b/r/2019-09-20-mapbox-layers.Rmd
index 57112d29..8d858f1c 100644
--- a/r/2019-09-20-mapbox-layers.Rmd
+++ b/r/2019-09-20-mapbox-layers.Rmd
@@ -33,15 +33,24 @@ library(plotly)
 packageVersion('plotly')
 ```
 
-### Mapbox Access Tokens and When You Need Them
+### How Layers Work in Mapbox Maps
 
-The [`plot_ly(layout(mapbox()))`](https://plot.ly/r/reference/#layout-mapbox) call signature contains base maps which are collected from the [MapBox](https://mapbox.com) API.
+If your figure contains one or more traces of type `scattermapbox`, `choroplethmapbox` or `densitymapbox`, the `layout` call signature of your figure contains configuration information for the map itself. 
+
+The map is composed of layers of three different types.
+<ol>
+  <li> `layout(mapbox(style))` defines the lowest layers, also known as your "base map"</li>
+  <li> the various traces in the `plot_ly` call signature are by default rendered above the base map (this can be controlled via the use of `below` attribute).</li>
+  <li> `layout(mapbox(layers()))` accepts an array that defines layers that are by default rendered above the traces in the `plot_ly` call signature (although this can also be controlled via the `below` attribute).</li>
+</ol>
+
+### Mapbox Access Tokens and When You Need Them
 
-If the base map you specify in the `plot_ly(layout(mapbox(style())))` call signature uses data from the Mapbox *service* that requires a MapBox Access Token, then you will need to register for a free account at https://mapbox.com/ and obtain and use your own Mapbox Access token. 
+The word "mapbox" in the trace names and `layout(mapbox())` refers to the Mapbox.js open-source library. If the basemap you define in `layout(mapbox(style()))` uses data from the Mapbox *service* that requires API authentication, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token.
 
 If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
-#### - The following values of the `style` attribute **DO** require an Access Token:
+#### - The following values of `layout(mapbox(style()))` **DO** require an Access Token:
 <ol>
   <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
   <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
@@ -50,23 +59,12 @@ If you're using a Chart Studio Enterprise server, please see additional instruct
 
 - We recommend setting your MapBox Access Token as an environment variable in your R environment. That way, your token will not be committed to version control. See [Basemap Requiring MapBox Access Token](#basemap-requiring-mapbox-access-token)
 
-#### - The following values of the style attribute **DO NOT** require an Access Token:
+#### - The following values of `layout(mapbox(style()))` **DO NOT** require an Access Token:
 <ol>
   <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
   <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
 </ol>
 
-### How Layers Work in Mapbox Maps
-
-If your figure contains one or more traces of type `scattermapbox`, `choroplethmapbox` or `densitymapbox`, the `layout` call signature of your figure contains configuration information for the map itself. 
-
-The map is composed of layers of three different types.
-<ol>
-  <li> the `layout(mapbox(style))` call signature defines the lowest layers, also known as your "base map"</li>
-  <li> The various traces in the `plot_ly` call signature are by default rendered above the base map (this can be controlled via the use of `below` attribute).</li>
-  <li> the `layout(mapbox(layers()))` call signature is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).</li>
-</ol>
-
 #### Using `plot_ly(layout(mapbox(layers())))` to Specify a Base Map
 
 If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set use the `layout(mapbox(style()))` call signature to `"white-bg"` and then the use the `layout(mapbox(layers()))` call signature with the `below` attribute to specify a custom base map.
@@ -128,7 +126,7 @@ p
 
 #### Maps Below and Above A Trace: No Token Needed
 
-This example uses the same basemap as the one above. However, in this case, partly-transparent raster tiles are rendered above the trace as well.
+This example uses the same base map as the one above. In addition, a WMS layer from Environment Canada (which displays near-real-time radar imagery in partly-transparent raster tiles) is rendered above the `scattermapbox` trace, as is the default:
 
 ```{r}
 library(plotly)

From 99fabef0d1e6c15e826257543371b692ee0d5ef5 Mon Sep 17 00:00:00 2001
From: Joseph Damiba <joseph.damiba@plot.ly>
Date: Fri, 10 Jan 2020 10:06:59 -0500
Subject: [PATCH 9/9] using dot notation for attributes

---
 r/2019-09-20-mapbox-layers.Rmd | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/r/2019-09-20-mapbox-layers.Rmd b/r/2019-09-20-mapbox-layers.Rmd
index 8d858f1c..b70452f9 100644
--- a/r/2019-09-20-mapbox-layers.Rmd
+++ b/r/2019-09-20-mapbox-layers.Rmd
@@ -35,22 +35,22 @@ packageVersion('plotly')
 
 ### How Layers Work in Mapbox Maps
 
-If your figure contains one or more traces of type `scattermapbox`, `choroplethmapbox` or `densitymapbox`, the `layout` call signature of your figure contains configuration information for the map itself. 
+If your figure contains one or more traces of type `scattermapbox`, `choroplethmapbox` or `densitymapbox`, the `layout` of your figure contains configuration information for the map itself. 
 
 The map is composed of layers of three different types.
 <ol>
-  <li> `layout(mapbox(style))` defines the lowest layers, also known as your "base map"</li>
+  <li> `layout.mapbox.style` defines the lowest layers, also known as your "base map"</li>
   <li> the various traces in the `plot_ly` call signature are by default rendered above the base map (this can be controlled via the use of `below` attribute).</li>
-  <li> `layout(mapbox(layers()))` accepts an array that defines layers that are by default rendered above the traces in the `plot_ly` call signature (although this can also be controlled via the `below` attribute).</li>
+  <li> the `layout.mapbox.layers` attribute accepts an array that defines layers that are by default rendered above the traces in the `plot_ly` call signature (this can be controlled via the `below` attribute).</li>
 </ol>
 
 ### Mapbox Access Tokens and When You Need Them
 
-The word "mapbox" in the trace names and `layout(mapbox())` refers to the Mapbox.js open-source library. If the basemap you define in `layout(mapbox(style()))` uses data from the Mapbox *service* that requires API authentication, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token.
+The word "mapbox" in trace names and the `layout.mapbox` attribute refers to the Mapbox.js open-source library. If the basemap you define using `layout.mapbox.style` uses data from the Mapbox *service* that requires API authentication, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token.
 
 If you're using a Chart Studio Enterprise server, please see additional instructions [here](https://help.plot.ly/mapbox-atlas).
 
-#### - The following values of `layout(mapbox(style()))` **DO** require an Access Token:
+#### - The following values of `layout.mapbox.style` **DO** require an Access Token:
 <ol>
   <li> `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation. </li>
   <li> A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation. </li>
@@ -59,17 +59,17 @@ If you're using a Chart Studio Enterprise server, please see additional instruct
 
 - We recommend setting your MapBox Access Token as an environment variable in your R environment. That way, your token will not be committed to version control. See [Basemap Requiring MapBox Access Token](#basemap-requiring-mapbox-access-token)
 
-#### - The following values of `layout(mapbox(style()))` **DO NOT** require an Access Token:
+#### - The following values of `layout.mapbox.style` **DO NOT** require an Access Token:
 <ol>
   <li> `"white-bg"` yields an empty white canvas which results in no external HTTP requests </li>
   <li> `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens </li>
 </ol>
 
-#### Using `plot_ly(layout(mapbox(layers())))` to Specify a Base Map
+#### Using `layout.mapbox.layers` to Specify a Base Map
 
-If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set use the `layout(mapbox(style()))` call signature to `"white-bg"` and then the use the `layout(mapbox(layers()))` call signature with the `below` attribute to specify a custom base map.
+If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to first set `layout.mapbox.style` to `"white-bg"` and then set `layout.mapbox.layers` to `below` to specify a custom base map.
 
-> If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
+> If you omit setting `layout.mapbox.layers` to `below`, when using this approach, your data will likely be hidden by fully-opaque raster tiles!
 
 ### OpenStreetMap Tiles, no Token Needed
 
@@ -98,7 +98,7 @@ p
 
 ### Base Map Below A Trace: No Token Needed
 
-This chart demonstrates how to use a public USGS imagery map as a base map, specified in the `layout(mapbox(layers()))` call signature, and which is rendered *below* the trace.
+This chart demonstrates how to use a public USGS imagery map as a base map using `layout.mapbox.layers`. The map is rendered *below* the trace.
 
 ```{r}
 library(plotly)
@@ -126,7 +126,9 @@ p
 
 #### Maps Below and Above A Trace: No Token Needed
 
-This example uses the same base map as the one above. In addition, a WMS layer from Environment Canada (which displays near-real-time radar imagery in partly-transparent raster tiles) is rendered above the `scattermapbox` trace, as is the default:
+This example uses the same base map *below* the trace as the one above. 
+
+In addition, a WMS layer map from Environment Canada (which displays near-real-time radar imagery in partly-transparent raster tiles) is rendered *above* the `scattermapbox` trace, as is the default:
 
 ```{r}
 library(plotly)