update map layers doc

LiamConnors · LiamConnors · commit 8e2538de3cfa · 2024-08-02T23:19:45.000-04:00
diff --git a/doc/python/mapbox-layers.md b/doc/python/mapbox-layers.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.6
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,63 +20,83 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.0
   plotly:
-    description: How to make Mapbox maps in Python with various base layers, with
-      or without needing a Mapbox Access token.
+    description: How to make tile-based maps in Python with various base layers.
     display_as: maps
     language: python
     layout: base
-    name: Mapbox Map Layers
+    name: Tile Map Layers
     order: 8
     page_type: u-guide
-    permalink: python/mapbox-layers/
+    permalink: /python/tile-map-layers/
+    redirect_from: /python/mapbox-layers/
     thumbnail: thumbnail/mapbox-layers.png
 ---
 
 <!-- #region -->
 
-### Mapbox Maps vs Geo Maps
+## Tile Maps vs Outline Maps
 
 Plotly supports two different kinds of maps:
 
-1. **Mapbox maps** are [tile-based maps](https://en.wikipedia.org/wiki/Tiled_web_map). If your figure is created with a `px.scatter_mapbox`, `px.line_mapbox`, `px.choropleth_mapbox` or `px.density_mapbox` function or otherwise contains one or more traces of type `go.Scattermapbox`, `go.Choroplethmapbox` or `go.Densitymapbox`, the `layout.mapbox` object in your figure contains configuration information for the map itself.
-2. **Geo maps** are outline-based maps. If your figure is created with a `px.scatter_geo`, `px.line_geo` or `px.choropleth` function or otherwise contains one or more traces of type `go.Scattergeo` or `go.Choropleth`, the `layout.geo` object in your figure contains configuration information for the map itself.
+- **[Tile-based maps](https://en.wikipedia.org/wiki/Tiled_web_map)**
 
-This page documents Mapbox tile-based maps, and the [Geo map documentation](/python/map-configuration/) describes how to configure outline-based maps.
+If your figure is created with a `px.scatter_map`, `px_scatter_mapbox`, `px.line_map`, `px.line_mapbox`, `px.choropleth_map`, `px.choropleth_mapbox`, `px.density_map`, or `px.density_mapbox` function or otherwise contains one or more traces of type `go.Scattermap`, `go.Scattermapbox`,`go.Choroplethmap`, `go.Choroplethmapbox`, `go.Densitymap`, or `go.Densitymapbox` the `layout.map` or `layout.mapbox` object in your figure contains configuration information for the map itself.
 
-#### How Layers Work in Mapbox Tile Maps
+- **Outline-based maps**
 
-Mapbox tile maps are composed of various layers, of three different types:
+Geo maps are outline-based maps. If your figure is created with a `px.scatter_geo`, `px.line_geo` or `px.choropleth` function or otherwise contains one or more traces of type `go.Scattergeo` or `go.Choropleth`, the `layout.geo` object in your figure contains configuration information for the map itself.
 
-1. `layout.mapbox.style` defines is the lowest layers, also known as your "base map"
-2. The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
-3. `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).
+> This page documents tile-based maps, and the [Geo map documentation](/python/map-configuration/) describes how to configure outline-based maps.
 
-#### Mapbox Access Tokens and When You Need Them
+## Tile Map Renderers
 
-The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox GL JS open-source library, which is integrated into Plotly.py. 
+Tile-based traces in Plotly use Maplibre or Mapbox.
 
-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 in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
+Maplibre-based traces (new in 5.24) are ones generated in Plotly Express using `px.scatter_map`, `px.line_map`, `px.choropleth_map`, `px.density_map`, or Graph Objects using `go.Scattermap`, `go.Choroplethmap`, or `go.Densitymap`.
 
-If you basemap in `layout.mapbox.style` uses maps from the [Stadia Maps service](https://www.stadiamaps.com) (see below for details), you'll need to register for a Stadia Maps account and token. 
+Mapbox-based traces are suffixed with `mapbox`, for example `go.Scattermapbox`. These are deprecated as of version 5.24 and we recommend using the Maplibre-based traces.
 
+### Maplibre
 
-#### Base Maps in `layout.mapbox.style`
+*New in 5.24*
 
-The accepted values for `layout.mapbox.style` are one of:
+Maplibre-based tile maps have three different types of layers:
 
-- `"white-bg"` yields an empty white canvas which results in no external HTTP requests
-- `"open-street-map"`, `"carto-positron"`, and `"carto-darkmatter"` yield maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens.
-- `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yield maps composed of _vector_ tiles from the Mapbox service, and _do_ require a Mapbox Access Token or an on-premise Mapbox installation.
-- `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yield maps composed of _raster_ tiles from the [Stadia Maps service](https://www.stadiamaps.com), and require a Stadia Maps account and token. 
-- A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
-- A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
+- `layout.map.style` defines the lowest layers of the map, also known as the "base map".
+- The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
+- `layout.map.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.
 
-#### OpenStreetMap tiles: no token needed
 
-Here is a simple map rendered with OpenStreetMaps tiles, without needing a Mapbox Access Token:
+#### Base Maps in `layout.map.style`.
+
+The accepted values for `layout.map.style` are one of:
+
+- "basic"
+- "carto-darkmatter"
+- "carto-darkmatter-nolabels"
+- "carto-positron"
+- "carto-positron-nolabels"
+- "carto-voyager"
+- "carto-voyager-nolabels"
+- "dark"
+- "light"
+- "open-street-map"
+- "outdoors"
+- "satellite"
+- "satellite-streets"
+- "streets"
+- "white-bg" - an empty white canvas which results in no external HTTP requests
+
+- A custom style URL. For example: https://tiles.stadiamaps.com/styles/stamen_watercolor.json?api_key=YOUR-API-KEY
+
+- A Map Style object as defined at https://maplibre.org/maplibre-style-spec/
 
+
+#### OpenStreetMap tiles
+
+Here is a simple map rendered with OpenStreetMaps tiles.
 <!-- #endregion -->
 
 ```python
@@ -85,36 +105,34 @@ us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/maste
 
 import plotly.express as px
 
-fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+fig = px.scatter_map(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
                         color_discrete_sequence=["fuchsia"], zoom=3, height=300)
-fig.update_layout(mapbox_style="open-street-map")
+fig.update_layout(map_style="open-street-map")
 fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
+#### Using `layout.map.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 `layout.mapbox.style` to `"white-bg"` and to use `layout.mapbox.layers` with `below` 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 `layout.map.style` to `"white-bg"` and to use `layout.map.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.
-
+Here is an example of a map which uses a public USGS imagery map, specified in `layout.map.layers`, and which is rendered _below_ the `data` layer.
 
 ```python
 import pandas as pd
 us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
 
 import plotly.express as px
 
-fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+fig = px.scatter_map(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
                         color_discrete_sequence=["fuchsia"], zoom=3, height=300)
 fig.update_layout(
-    mapbox_style="white-bg",
-    mapbox_layers=[
+    map_style="white-bg",
+    map_layers=[
         {
             "below": 'traces',
             "sourcetype": "raster",
@@ -129,9 +147,9 @@ fig.show()
 ```
 
 
-#### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
+#### Base Tiles from the USGS, radar overlay from Environment Canada
 
-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:
+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.Scattermap` trace, as is the default:
 
 
 ```python
@@ -140,11 +158,11 @@ us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/maste
 
 import plotly.express as px
 
-fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+fig = px.scatter_map(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
                         color_discrete_sequence=["fuchsia"], zoom=3, height=300)
 fig.update_layout(
-    mapbox_style="white-bg",
-    mapbox_layers=[
+    map_style="white-bg",
+    map_layers=[
         {
             "below": 'traces',
             "sourcetype": "raster",
@@ -166,32 +184,127 @@ fig.show()
 ```
 
 
-#### Dark tiles from Mapbox service: free token needed
+#### Dark tiles example
 
-Here is a map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
+Here is a map rendered with the `"dark"` style.
+
+```python
+import pandas as pd
+us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
 
+import plotly.express as px
+
+fig = px.scatter_map(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+                        color_discrete_sequence=["fuchsia"], zoom=3, height=300)
+fig.update_layout(map_style="dark")
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+<!-- #region -->
+### Mapbox
+
+#### How Layers Work in Mapbox Tile Maps
+
+Mapbox tile maps are composed of various layers, of three different types:
+
+1. `layout.mapbox.style` defines is the lowest layers, also known as your "base map"
+2. The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
+3. `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).
+
+#### Mapbox Access Tokens and When You Need Them
+
+The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox GL JS open-source library, which is integrated into Plotly.py. 
+
+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 in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
+
+If you basemap in `layout.mapbox.style` uses maps from the [Stadia Maps service](https://www.stadiamaps.com) (see below for details), you'll need to register for a Stadia Maps account and token. 
+
+
+#### Base Maps in `layout.mapbox.style`
+
+The accepted values for `layout.mapbox.style` are one of:
+
+- `"white-bg"` yields an empty white canvas which results in no external HTTP requests
+- `"open-street-map"`, `"carto-positron"`, and `"carto-darkmatter"` yield maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens.
+- `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yield maps composed of _vector_ tiles from the Mapbox service, and _do_ require a Mapbox Access Token or an on-premise Mapbox installation.
+- `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yield maps composed of _raster_ tiles from the [Stadia Maps service](https://www.stadiamaps.com), and require a Stadia Maps account and token. 
+- A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
+- A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
+
+#### OpenStreetMap tiles: no token needed
+
+Here is a simple map rendered with OpenStreetMaps tiles, without needing a Mapbox Access Token:
+<!-- #endregion -->
 
 ```python
-token = open(".mapbox_token").read() # you will need your own token
+import pandas as pd
+us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
+
+import plotly.express as px
+
+fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+                        color_discrete_sequence=["fuchsia"], zoom=3, height=300)
+fig.update_layout(mapbox_style="open-street-map")
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+#### 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 `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.
+
+
+```python
 import pandas as pd
 us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
 
 import plotly.express as px
 
 fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
                         color_discrete_sequence=["fuchsia"], zoom=3, height=300)
-fig.update_layout(mapbox_style="dark", mapbox_accesstoken=token)
+fig.update_layout(
+    mapbox_style="white-bg",
+    mapbox_layers=[
+        {
+            "below": 'traces',
+            "sourcetype": "raster",
+            "sourceattribution": "United States Geological Survey",
+            "source": [
+                "https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
+            ]
+        }
+      ])
 fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-#### Using a mapbox image layer to display a datashader raster image
+#### Dark tiles from Mapbox service: free token needed
 
-See the example in the [plotly and datashader tutorial](/python/datashader).
+Here is a map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
 
+```python
+token = open(".mapbox_token").read() # you will need your own token
 
-#### Setting Map Bounds
+import pandas as pd
+us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
+
+import plotly.express as px
+
+fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
+                        color_discrete_sequence=["fuchsia"], zoom=3, height=300)
+fig.update_layout(mapbox_style="dark", mapbox_accesstoken=token)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+## Setting Map Bounds
 
 *New in 5.11*
 
@@ -205,7 +318,7 @@ us_cities = pd.read_csv(
     "https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv"
 )
 
-fig = px.scatter_mapbox(
+fig = px.scatter_map(
     us_cities,
     lat="lat",
     lon="lon",
@@ -215,12 +328,12 @@ fig = px.scatter_mapbox(
     zoom=3,
     height=300,
 )
-fig.update_layout(mapbox_style="open-street-map")
+fig.update_layout(map_style="open-street-map")
 fig.update_layout(margin={"r": 0, "t": 0, "l": 0, "b": 0})
-fig.update_layout(mapbox_bounds={"west": -180, "east": -50, "south": 20, "north": 90})
+fig.update_layout(map_bounds={"west": -180, "east": -50, "south": 20, "north": 90})
 fig.show()
 ```
 
 #### Reference
 
-See https://plotly.com/python/reference/layout/mapbox/ for more information and options!
+See https://plotly.com/python/reference/layout/map/ for more information and options on Maplibre-based tile maps and https://plotly.com/python/reference/layout/mapbox/ for Mapbox-based tile maps.
