diff --git a/doc/apidoc/plotly.express.rst b/doc/apidoc/plotly.express.rst
index 5f687e54868..c2512ee82d5 100644
--- a/doc/apidoc/plotly.express.rst
+++ b/doc/apidoc/plotly.express.rst
@@ -18,12 +18,14 @@ plotly's high-level API for rapid figure generation. ::
scatter_3d
scatter_polar
scatter_ternary
+ scatter_map
scatter_mapbox
scatter_geo
line
line_3d
line_polar
line_ternary
+ line_map
line_mapbox
line_geo
area
@@ -45,9 +47,11 @@ plotly's high-level API for rapid figure generation. ::
parallel_coordinates
parallel_categories
choropleth
+ choropleth_map
choropleth_mapbox
density_contour
density_heatmap
+ density_map
density_mapbox
imshow
set_mapbox_access_token
diff --git a/doc/python/axes.md b/doc/python/axes.md
index 2ade3a47213..851fb142db8 100644
--- a/doc/python/axes.md
+++ b/doc/python/axes.md
@@ -41,7 +41,7 @@ Other kinds of subplots and axes are described in other tutorials:
- [Polar axes](/python/polar-chart/). The axis object is [`go.layout.Polar`](/python/reference/layout/polar/)
- [Ternary axes](/python/ternary-plots). The axis object is [`go.layout.Ternary`](/python/reference/layout/ternary/)
- [Geo axes](/python/map-configuration/). The axis object is [`go.layout.Geo`](/python/reference/layout/geo/)
-- [Mapbox axes](/python/mapbox-layers/). The axis object is [`go.layout.Mapbox`](/python/reference/layout/mapbox/)
+- [Map axes](/python/tile-map-layers/). The axis object is [`go.layout.Map`](/python/reference/layout/map/)
- [Color axes](/python/colorscales/). The axis object is [`go.layout.Coloraxis`](/python/reference/layout/coloraxis/).
**See also** the tutorials on [facet plots](/python/facet-plots/), [subplots](/python/subplots) and [multiple axes](/python/multiple-axes/).
diff --git a/doc/python/bubble-maps.md b/doc/python/bubble-maps.md
index 23e1d543824..3315e934d90 100644
--- a/doc/python/bubble-maps.md
+++ b/doc/python/bubble-maps.md
@@ -5,10 +5,10 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
- jupytext_version: 1.1.1
+ format_version: '1.3'
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,14 +20,14 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.6.7
+ version: 3.10.0
plotly:
description: How to make bubble maps in Python with Plotly.
display_as: maps
language: python
layout: base
name: Bubble Maps
- order: 4
+ order: 5
page_type: example_index
permalink: python/bubble-maps/
thumbnail: thumbnail/bubble-map.jpg
diff --git a/doc/python/choropleth-maps.md b/doc/python/choropleth-maps.md
index 8bd82fc225b..6cdf73d51e0 100644
--- a/doc/python/choropleth-maps.md
+++ b/doc/python/choropleth-maps.md
@@ -6,9 +6,9 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.3'
- jupytext_version: 1.14.1
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,20 +20,20 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.8.8
+ version: 3.10.0
plotly:
description: How to make choropleth maps in Python with Plotly.
display_as: maps
language: python
layout: base
name: Choropleth Maps
- order: 7
+ order: 8
page_type: u-guide
permalink: python/choropleth-maps/
thumbnail: thumbnail/choropleth.jpg
---
-A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **outline** choropleth maps, but you can also build [choropleth **tile maps** using our Mapbox trace types](/python/mapbox-county-choropleth).
+A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **outline** choropleth maps, but you can also build [choropleth **tile maps**](/python/tile-county-choropleth).
Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` function or the lower-level `go.Choropleth` graph object.
diff --git a/doc/python/county-choropleth.md b/doc/python/county-choropleth.md
index 1340b4a75ad..935f3f649e0 100644
--- a/doc/python/county-choropleth.md
+++ b/doc/python/county-choropleth.md
@@ -5,10 +5,10 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.2'
- jupytext_version: 1.3.1
+ format_version: '1.3'
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.6.8
+ version: 3.10.0
plotly:
description: How to create colormaped representations of USA counties by FIPS
values in Python.
@@ -28,7 +28,7 @@ jupyter:
language: python
layout: base
name: USA County Choropleth Maps
- order: 10
+ order: 11
page_type: u-guide
permalink: python/county-choropleth/
thumbnail: thumbnail/county-choropleth-usa-greybkgd.jpg
@@ -37,7 +37,7 @@ jupyter:
### Deprecation warning
-This page describes a [legacy "figure factory" method](/python/figure-factories/) for creating map-like figures using [self-filled scatter traces](/python/shapes). **This is no longer the recommended way to make county-level choropleth maps**, instead we recommend using a [GeoJSON-based approach to making outline choropleth maps](/python/choropleth-maps/) or the alternative [Mapbox tile-based choropleth maps](/python/mapbox-county-choropleth).
+This page describes a [legacy "figure factory" method](/python/figure-factories/) for creating map-like figures using [self-filled scatter traces](/python/shapes). **This is no longer the recommended way to make county-level choropleth maps**, instead we recommend using a [GeoJSON-based approach to making outline choropleth maps](/python/choropleth-maps/) or the alternative [tile-based choropleth maps](/python/tile-county-choropleth).
#### Required Packages
@@ -274,7 +274,7 @@ fig.layout.template = None
fig.show()
```
-Also see Mapbox county choropleths made in Python: [https://plotly.com/python/mapbox-county-choropleth/](https://plotly.com/python/mapbox-county-choropleth/)
+Also see tile county choropleths made in Python: [https://plotly.com/python/tile-county-choropleth/](https://plotly.com/python/tile-county-choropleth/)
### Reference
diff --git a/doc/python/datashader.md b/doc/python/datashader.md
index 1c8d08852f7..ba1ec46e4fe 100644
--- a/doc/python/datashader.md
+++ b/doc/python/datashader.md
@@ -5,10 +5,10 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.2'
- jupytext_version: 1.3.0
+ format_version: '1.3'
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.3
+ version: 3.10.0
plotly:
description: How to use datashader to rasterize large datasets, and visualize
the generated raster data with plotly.
@@ -36,10 +36,10 @@ jupyter:
[datashader](https://datashader.org/) creates rasterized representations of large datasets for easier visualization, with a pipeline approach consisting of several steps: projecting the data on a regular grid, creating a color representation of the grid, etc.
-### Passing datashader rasters as a mapbox image layer
+### Passing datashader rasters as a tile map image layer
We visualize here the spatial distribution of taxi rides in New York City. A higher density
-is observed on major avenues. For more details about mapbox charts, see [the mapbox layers tutorial](/python/mapbox-layers). No mapbox token is needed here.
+is observed on major avenues. For more details about tile-based maps, see [the tile map layers tutorial](/python/tile-map-layers).
```python
import pandas as pd
@@ -51,7 +51,7 @@ cvs = ds.Canvas(plot_width=1000, plot_height=1000)
agg = cvs.points(dff, x='Lon', y='Lat')
# agg is an xarray object, see http://xarray.pydata.org/en/stable/ for more details
coords_lat, coords_lon = agg.coords['Lat'].values, agg.coords['Lon'].values
-# Corners of the image, which need to be passed to mapbox
+# Corners of the image
coordinates = [[coords_lon[0], coords_lat[0]],
[coords_lon[-1], coords_lat[0]],
[coords_lon[-1], coords_lat[-1]],
@@ -62,16 +62,12 @@ import datashader.transfer_functions as tf
img = tf.shade(agg, cmap=fire)[::-1].to_pil()
import plotly.express as px
-# Trick to create rapidly a figure with mapbox axes
-fig = px.scatter_mapbox(dff[:1], lat='Lat', lon='Lon', zoom=12)
-# Add the datashader image as a mapbox layer image
-fig.update_layout(mapbox_style="carto-darkmatter",
- mapbox_layers = [
- {
- "sourcetype": "image",
- "source": img,
- "coordinates": coordinates
- }]
+# Trick to create rapidly a figure with map axes
+fig = px.scatter_map(dff[:1], lat='Lat', lon='Lon', zoom=12)
+# Add the datashader image as a tile map layer image
+fig.update_layout(
+ map_style="carto-darkmatter",
+ map_layers=[{"sourcetype": "image", "source": img, "coordinates": coordinates}],
)
fig.show()
```
@@ -113,7 +109,3 @@ fig.update_traces(hoverongaps=False)
fig.update_layout(coloraxis_colorbar=dict(title='Count', tickprefix='1.e'))
fig.show()
```
-
-```python
-
-```
\ No newline at end of file
diff --git a/doc/python/figure-structure.md b/doc/python/figure-structure.md
index 7a078a05c94..f55abad91b5 100644
--- a/doc/python/figure-structure.md
+++ b/doc/python/figure-structure.md
@@ -97,7 +97,7 @@ The second of the three top-level attributes of a figure is `layout`, whose valu
* Subplots of various types on which can be drawn multiple traces and which are positioned in paper coordinates:
* `xaxis`, `yaxis`, `xaxis2`, `yaxis3` etc: X and Y cartesian axes, the intersections of which are cartesian subplots
* `scene`, `scene2`, `scene3` etc: 3d scene subplots
- * `ternary`, `ternary2`, `ternary3`, `polar`, `polar2`, `polar3`, `geo`, `geo2`, `geo3`, `mapbox`, `mapbox2`, `mabox3`, `smith`, `smith2` etc: ternary, polar, geo, mapbox or smith subplots
+ * `ternary`, `ternary2`, `ternary3`, `polar`, `polar2`, `polar3`, `geo`, `geo2`, `geo3`, `map`, `map2`, `map3`, `smith`, `smith2` etc: ternary, polar, geo, map or smith subplots
* Non-data marks which can be positioned in paper coordinates, or in data coordinates linked to 2d cartesian subplots:
* `annotations`: [textual annotations with or without arrows](/python/text-and-annotations/)
* `shapes`: [lines, rectangles, ellipses or open or closed paths](/python/shapes/)
@@ -181,18 +181,18 @@ The following trace types are compatible with smith subplots via the `smith` att
### Map Trace Types and Subplots
-Figures can include two different types of map subplots: [geo subplots for outline maps](/python/map-configuration/) and [mapbox subplots for tile maps](/python/mapbox-layers/). The following trace types support attributes named `geo` or `mapbox`, whose values must refer to corresponding objects in the layout i.e. `geo="geo2"` etc. Note that attributes such as `layout.geo2` and `layout.mapbox` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot.
+Figures can include two different types of map subplots: [geo subplots for outline maps](/python/map-configuration/) and [tile-based maps](/python/tile-map-layers/). The following trace types support attributes named `geo` or `map`, whose values must refer to corresponding objects in the layout i.e. `geo="geo2"` etc. Note that attributes such as `layout.geo2` and `layout.map` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot.
The following trace types are compatible with geo subplots via the `geo` attribute:
* [`scattergeo`](/python/scatter-plots-on-maps/), which can be used to draw [individual markers](/python/scatter-plots-on-maps/), [line and curves](/python/lines-on-maps/) and filled areas on outline maps
* [`choropleth`](/python/choropleth-maps/): [colored polygons](/python/choropleth-maps/) on outline maps
-The following trace types are compatible with mapbox subplots via the `mapbox` attribute:
+The following trace types are compatible with tile map subplots via the `map` attribute:
-* [`scattermapbox`](/python/scattermapbox/), which can be used to draw [individual markers](/python/scattermapbox/), [lines and curves](/python/lines-on-mapbox/) and [filled areas](/python/filled-area-on-mapbox/) on tile maps
-* [`choroplethmapbox`](/python/mapbox-county-choropleth/): colored polygons on tile maps
-* [`densitymapbox`](/python/mapbox-density-heatmaps/): density heatmaps on tile maps
+* [`scattermap`](/python/tile-scatter-maps/), which can be used to draw [individual markers](/python/tile-scatter-maps/), [lines and curves](/python/lines-on-tile-maps/) and [filled areas](/python/filled-area-tile-maps/) on tile maps
+* [`choroplethmap`](/python/tile-county-choropleth/): colored polygons on tile maps
+* [`densitymap`](/python/tile-density-heatmaps/): density heatmaps on tile maps
### Traces Which Are Their Own Subplots
diff --git a/doc/python/filled-area-on-mapbox.md b/doc/python/filled-area-on-mapbox.md
index 2cd389642ae..be08fd35ade 100644
--- a/doc/python/filled-area-on-mapbox.md
+++ b/doc/python/filled-area-on-mapbox.md
@@ -5,10 +5,10 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
- jupytext_version: 1.1.1
+ format_version: '1.3'
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,68 +20,63 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.6.8
+ version: 3.10.0
plotly:
- description: How to make an area on Map in Python with Plotly.
+ description: How to make an area on tile-based maps in Python with Plotly.
display_as: maps
language: python
layout: base
name: Filled Area on Maps
- order: 3
+ order: 4
page_type: example_index
- permalink: python/filled-area-on-mapbox/
+ permalink: python/filled-area-tile-maps/
+ redirect_from: python/filled-area-on-mapbox/
thumbnail: thumbnail/area.jpg
---
-
-
-### Mapbox Access Token and Base Map Configuration
-
-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](/python/mapbox-layers/) documentation for more information.
+There are three different ways to show a filled area on a tile-based map:
-There are three different ways to show a filled area in a Mapbox map:
+- Using a [Scattermap](https://plotly.com/python/reference/scattermap/) trace and setting the `fill` attribute to 'toself'
+- Using a map layout (i.e. by minimally using an empty [Scattermap](https://plotly.com/python/reference/scattermap/) trace) and adding a GeoJSON layer
+- Using the [Choroplethmap](https://plotly.com/python/tile-county-choropleth/) trace type
-1. Use a [Scattermapbox](https://plotly.com/python/reference/scattermapbox/) trace and set `fill` attribute to 'toself'
-2. Use a Mapbox layout (i.e. by minimally using an empty [Scattermapbox](https://plotly.com/python/reference/scattermapbox/) trace) and add a GeoJSON layer
-3. Use the [Choroplethmapbox](https://plotly.com/python/mapbox-county-choropleth/) trace type
-
+## Filled `Scattermap` Trace
-### Filled `Scattermapbox` Trace
-
-The following example uses `Scattermapbox` and sets `fill = 'toself'`
+The following example uses `Scattermap` and sets `fill = 'toself'`
```python
import plotly.graph_objects as go
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
fill = "toself",
lon = [-74, -70, -70, -74], lat = [47, 47, 45, 45],
marker = { 'size': 10, 'color': "orange" }))
fig.update_layout(
- mapbox = {
+ map = {
'style': "open-street-map",
'center': {'lon': -73, 'lat': 46 },
'zoom': 5},
showlegend = False)
fig.show()
+
```
-### Multiple Filled Areas with a `Scattermapbox` trace
+### Multiple Filled Areas with a `Scattermap` trace
-The following example shows how to use `None` in your data to draw multiple filled areas. Such gaps in trace data are unconnected by default, but this can be controlled via the [connectgaps](https://plotly.com/python/reference/scattermapbox/#scattermapbox-connectgaps) attribute.
+The following example shows how to use `None` in your data to draw multiple filled areas. Such gaps in trace data are unconnected by default, but this can be controlled via the [connectgaps](https://plotly.com/python/reference/scattermap/#scattermap-connectgaps) attribute.
```python
import plotly.graph_objects as go
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
mode = "lines", fill = "toself",
lon = [-10, -10, 8, 8, -10, None, 30, 30, 50, 50, 30, None, 100, 100, 80, 80, 100],
lat = [30, 6, 6, 30, 30, None, 20, 30, 30, 20, 20, None, 40, 50, 50, 40, 40]))
fig.update_layout(
- mapbox = {'style': "open-street-map", 'center': {'lon': 30, 'lat': 30}, 'zoom': 2},
+ map = {'style': "open-street-map", 'center': {'lon': 30, 'lat': 30}, 'zoom': 2},
showlegend = False,
margin = {'l':0, 'r':0, 'b':0, 't':0})
@@ -95,13 +90,13 @@ In this map we add a GeoJSON layer.
```python
import plotly.graph_objects as go
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
mode = "markers",
lon = [-73.605], lat = [45.51],
marker = {'size': 20, 'color': ["cyan"]}))
fig.update_layout(
- mapbox = {
+ map = {
'style': "open-street-map",
'center': { 'lon': -73.6, 'lat': 45.5},
'zoom': 12, 'layers': [{
@@ -139,6 +134,36 @@ fig.update_layout(
fig.show()
```
+
+### Mapbox Maps
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
+
+The earlier examples using `go.Scattermap` use [Maplibre](https://maplibre.org/maplibre-gl-js/docs/) for rendering. This trace was introduced in Plotly.py 5.24 and is now the recommended way to draw filled areas on tile-based maps. There is also a trace that uses [Mapbox](https://docs.mapbox.com), called `go.Scattermapbox`.
+
+To use the `Scattermapbox` trace type, in some cases you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+
+Here's one of the earlier examples rewritten to use `Scattermapbox`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattermapbox(
+ fill = "toself",
+ lon = [-74, -70, -70, -74], lat = [47, 47, 45, 45],
+ marker = { 'size': 10, 'color': "orange" }))
+
+fig.update_layout(
+ mapbox = {
+ 'style': "open-street-map",
+ 'center': {'lon': -73, 'lat': 46 },
+ 'zoom': 5},
+ showlegend = False)
+
+fig.show()
+```
+
+
#### Reference
-See https://plotly.com/python/reference/scattermapbox/ for more information about mapbox and their attribute options.
\ No newline at end of file
+See https://plotly.com/python/reference/scattermap/ for available attribute options, or for `go.Scattermapbox`, see https://plotly.com/python/reference/scattermapbox/.
diff --git a/doc/python/heatmaps.md b/doc/python/heatmaps.md
index 07edd31e9c7..d9079ea2845 100644
--- a/doc/python/heatmaps.md
+++ b/doc/python/heatmaps.md
@@ -34,7 +34,7 @@ jupyter:
thumbnail: thumbnail/heatmap.jpg
---
-The term "heatmap" usually refers to a cartesian plot with data visualized as colored rectangular tiles, which is the subject of this page. It is also sometimes used to refer to [actual maps with density data displayed as color intensity](/python/mapbox-density-heatmaps/).
+The term "heatmap" usually refers to a Cartesian plot with data visualized as colored rectangular tiles, which is the subject of this page. It is also sometimes used to refer to [actual maps with density data displayed as color intensity](/python/tile-density-heatmaps/).
Plotly supports two different types of colored-tile heatmaps:
diff --git a/doc/python/hexbin-mapbox.md b/doc/python/hexbin-mapbox.md
index 74739e856eb..ed30f329774 100644
--- a/doc/python/hexbin-mapbox.md
+++ b/doc/python/hexbin-mapbox.md
@@ -27,7 +27,7 @@ jupyter:
language: python
layout: base
name: Hexbin Mapbox
- order: 13
+ order: 14
page_type: u-guide
permalink: python/hexbin-mapbox/
thumbnail: thumbnail/hexbin_mapbox.jpg
diff --git a/doc/python/hover-text-and-formatting.md b/doc/python/hover-text-and-formatting.md
index 50befc860f0..3dc4249e158 100644
--- a/doc/python/hover-text-and-formatting.md
+++ b/doc/python/hover-text-and-formatting.md
@@ -285,7 +285,7 @@ fig.show()
### Specifying the formatting and labeling of custom fields in a Plotly Express figure using a hovertemplate
-This example adds custom fields to a Plotly Express figure using the custom_data parameter and then adds a hover template that applies d3 formats to each element of the customdata[n] array and uses HTML to customize the fonts and spacing.
+This example adds custom fields to a Plotly Express figure using the `custom_data` parameter and then adds a hover template that applies d3 formats to each element of the `customdata[n]` array and uses HTML to customize the fonts and spacing.
```python
# %%
@@ -301,20 +301,20 @@ df = df.sort_values(['continent', 'country'])
df.rename(columns={"gdpPercap":'GDP per capita', "lifeExp":'Life Expectancy (years)'}, inplace=True)
-fig=px.scatter(df,
+fig=px.scatter(df,
x='GDP per capita',
- y='Life Expectancy (years)',
- color='continent',
- size=np.sqrt(df['pop']),
+ y='Life Expectancy (years)',
+ color='continent',
+ size=np.sqrt(df['pop']),
# Specifying data to make available to the hovertemplate
# The px custom_data parameter has an underscore, while the analogous graph objects customdata parameter has no underscore.
# The px custom_data parameter is a list of column names in the data frame, while the graph objects customdata parameter expects a data frame or a numpy array.
- custom_data=['country', 'continent', 'pop'],
+ custom_data=['country', 'continent', 'pop'],
)
# Plotly express does not have a hovertemplate parameter in the graph creation function, so we apply the template with update_traces
fig.update_traces(
- hovertemplate =
+ hovertemplate =
"%{customdata[0]}
" +
"%{customdata[1]}
" +
"GDP per Capita: %{x:$,.0f}
" +
@@ -371,7 +371,7 @@ fig.show()
### Advanced Hover Template
-This produces the same graphic as in "Specifying the formatting and labeling of custom fields in a Plotly Express figure using a hovertemplate" above, but does so with the `customdata` and `text` parameters of `graph_objects`. It shows how to specify columns from a dataframe to include in the customdata array using the df[["col_i", "col_j"]] subsetting notation. It then references those variables using e.g. %{customdata[0]} in the hovertemplate. It includes comments about major differences between the parameters used by `graph_objects` and `plotly.express`.
+This produces the same graphic as in "Specifying the formatting and labeling of custom fields in a Plotly Express figure using a hovertemplate" above, but does so with the `customdata` and `text` parameters of `graph_objects`. It shows how to specify columns from a dataframe to include in the `customdata` array using the `df[["col_i", "col_j"]]` subsetting notation. It then references those variables using e.g. `%{customdata[0]}` in the hovertemplate. It includes comments about major differences between the parameters used by `graph_objects` and `plotly.express`.
```python
import plotly.graph_objects as go
@@ -404,12 +404,12 @@ for continent_name, df in continent_data.items():
name=continent_name,
# The next three parameters specify the hover text
- # Text supports just one customized field per trace
- # and is implemented here with text=df['continent'],
- # Custom data supports multiple fields through numeric indices in the hovertemplate
- # In we weren't using the text parameter in our example,
+ # Text supports just one customized field per trace
+ # and is implemented here with text=df['continent'],
+ # Custom data supports multiple fields through numeric indices in the hovertemplate
+ # In we weren't using the text parameter in our example,
# we could instead add continent as a third customdata field.
- customdata=df[['country','pop']],
+ customdata=df[['country','pop']],
hovertemplate=
"%{customdata[0]}
" +
"%{text}
" +
@@ -462,14 +462,12 @@ fig.update_layout(title_text='Hover to see the value of z1, z2 and z3 together')
fig.show()
```
-### Setting the Hover Template in Mapbox Maps
+### Setting the Hover Template in Tile Maps
```python
import plotly.graph_objects as go
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
name = "",
mode = "markers+text+lines",
lon = [-75, -80, -50],
@@ -481,8 +479,7 @@ fig = go.Figure(go.Scattermapbox(
"latitude: %{lat}
" ))
fig.update_layout(
- mapbox = {
- 'accesstoken': token,
+ map = {
'style': "outdoors", 'zoom': 1},
showlegend = False)
diff --git a/doc/python/line-charts.md b/doc/python/line-charts.md
index 0c9fe2522a1..4434aa8046c 100644
--- a/doc/python/line-charts.md
+++ b/doc/python/line-charts.md
@@ -77,7 +77,7 @@ IFrame(snippet_url + 'line-charts', width='100%', height=1200)
### Data Order in Line Charts
-Plotly line charts are implemented as [connected scatterplots](https://www.data-to-viz.com/graph/connectedscatter.html) (see below), meaning that the points are plotted and connected with lines **in the order they are provided, with no automatic reordering**.
+Plotly line charts are implemented as [connected scatterplots](https://www.data-to-viz.com/graph/connectedscatter.html) (see below), meaning that the points are plotted and connected with lines **in the order they are provided, with no automatic reordering**.
This makes it possible to make charts like the one below, but also means that it may be required to explicitly sort data before passing it to Plotly to avoid lines moving "backwards" across the chart.
@@ -89,17 +89,17 @@ df = pd.DataFrame(dict(
x = [1, 3, 2, 4],
y = [1, 2, 3, 4]
))
-fig = px.line(df, x="x", y="y", title="Unsorted Input")
+fig = px.line(df, x="x", y="y", title="Unsorted Input")
fig.show()
df = df.sort_values(by="x")
-fig = px.line(df, x="x", y="y", title="Sorted Input")
+fig = px.line(df, x="x", y="y", title="Sorted Input")
fig.show()
```
### Connected Scatterplots
-In a connected scatterplot, two continuous variables are plotted against each other, with a line connecting them in some meaningful order, usually a time variable. In the plot below, we show the "trajectory" of a pair of countries through a space defined by GDP per Capita and Life Expectancy. Botswana's life expectancy
+In a connected scatterplot, two continuous variables are plotted against each other, with a line connecting them in some meaningful order, usually a time variable. In the plot below, we show the "trajectory" of a pair of countries through a space defined by GDP per Capita and Life Expectancy.
```python
import plotly.express as px
@@ -263,7 +263,7 @@ fig.show()
#### Connect Data Gaps
-[connectgaps](https://plotly.com/python/reference/scatter/#scatter-connectgaps) determines if missing values in the provided data are shown as a gap in the graph or not. In [this tutorial](https://plotly.com/python/filled-area-on-mapbox/#multiple-filled-areas-with-a-scattermapbox-trace), we showed how to take benefit of this feature and illustrate multiple areas in mapbox.
+[connectgaps](https://plotly.com/python/reference/scatter/#scatter-connectgaps) determines if missing values in the provided data are shown as a gap in the graph or not. In [this tutorial](https://plotly.com/python/filled-area-tile-maps/#multiple-filled-areas-with-a-scattermap-trace), we showed how to take benefit of this feature and illustrate multiple areas on a tile map.
```python
import plotly.graph_objects as go
diff --git a/doc/python/lines-on-mapbox.md b/doc/python/lines-on-mapbox.md
index 20bf2fc2726..f524d7b56db 100644
--- a/doc/python/lines-on-mapbox.md
+++ b/doc/python/lines-on-mapbox.md
@@ -5,10 +5,10 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.2'
- jupytext_version: 1.4.2
+ format_version: '1.3'
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,26 +20,23 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.7
+ version: 3.10.0
plotly:
- description: How to draw a line on Map in Python with Plotly.
+ description: How to draw a line on tile-based maps in Python with Plotly.
display_as: maps
language: python
layout: base
- name: Lines on Mapbox
- order: 2
+ name: Lines on Maps
+ order: 3
page_type: example_index
- permalink: python/lines-on-mapbox/
+ permalink: python/lines-on-tile-maps/
+ redirect_from: python/lines-on-mapbox/
thumbnail: thumbnail/line_mapbox.jpg
---
-### Mapbox Access Token and Base Map Configuration
+### Lines on maps using Plotly Express
-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](/python/mapbox-layers/) documentation for more information.
-
-To draw a line on your map, you either can use [`px.line_mapbox()`](https://plotly.com/python-api-reference/generated/plotly.express.line_mapbox.html) in Plotly Express, or [`Scattermapbox`](https://plotly.com/python/reference/scattermapbox/) traces. Below we show you how to draw a line on Mapbox using Plotly Express.
-
-### Lines on Mapbox maps using Plotly Express
+To draw a line on a map, you either can use `px.line_map` in Plotly Express, or `go.Scattermap` in Plotly Graph Objects. Here's an example of drawing a line on a tile-based map using Plotly Express.
```python
import pandas as pd
@@ -49,17 +46,17 @@ us_cities = us_cities.query("State in ['New York', 'Ohio']")
import plotly.express as px
-fig = px.line_mapbox(us_cities, lat="lat", lon="lon", color="State", zoom=3, height=300)
+fig = px.line_map(us_cities, lat="lat", lon="lon", color="State", zoom=3, height=300)
-fig.update_layout(mapbox_style="open-street-map", mapbox_zoom=4, mapbox_center_lat = 41,
+fig.update_layout(map_style="open-street-map", map_zoom=4, map_center_lat = 41,
margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
-### Lines on Mapbox maps from GeoPandas
+### Lines on maps from GeoPandas
-Given a GeoPandas geo-data frame with `linestring` or `multilinestring` features, one can extra point data and use `px.line_mapbox()`.
+Given a GeoPandas geo-data frame with `linestring` or `multilinestring` features, one can extra point data and use `px.line_map`.
```python
import plotly.express as px
@@ -94,15 +91,53 @@ for feature, name in zip(geo_df.geometry, geo_df.name):
lons = np.append(lons, None)
names = np.append(names, None)
-fig = px.line_mapbox(lat=lats, lon=lons, hover_name=names,
- mapbox_style="open-street-map", zoom=1)
+fig = px.line_map(lat=lats, lon=lons, hover_name=names,
+ map_style="open-street-map", zoom=1)
+fig.show()
+```
+
+### Lines on maps using `Scattermap` traces
+
+This example uses `go.Scattermap` and sets
+the [mode](https://plotly.com/python/reference/scattermapbox/#scattermap-mode) attribute to a combination of markers and line.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattermap(
+ mode = "markers+lines",
+ lon = [10, 20, 30],
+ lat = [10, 20,30],
+ marker = {'size': 10}))
+
+fig.add_trace(go.Scattermap(
+ mode = "markers+lines",
+ lon = [-50, -60,40],
+ lat = [30, 10, -20],
+ marker = {'size': 10}))
+
+fig.update_layout(
+ margin ={'l':0,'t':0,'b':0,'r':0},
+ map = {
+ 'center': {'lon': 10, 'lat': 10},
+ 'style': "open-street-map",
+ 'center': {'lon': -20, 'lat': -20},
+ 'zoom': 1})
+
fig.show()
```
-### Lines on Mapbox maps using `Scattermapbox` traces
+### Mapbox Maps
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
+
+The earlier examples using `px.line_map` and `go.Scattermap` use [Maplibre](https://maplibre.org/maplibre-gl-js/docs/) for rendering. These traces were introduced in Plotly.py 5.24 and are now the recommended way to draw lines on tile-based maps. There are also traces that use [Mapbox](https://docs.mapbox.com): `px.line_mapbox` and `go.Scattermapbox`
-This example uses `go.Scattermapbox` and sets
-the [mode](https://plotly.com/python/reference/scattermapbox/#scattermapbox-mode) attribute to a combination of markers and line.
+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](/python/mapbox-layers/) documentation for more information.
+
+To draw a line on your map, you either can use [`px.line_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.line_mapbox.html) in Plotly Express, or [`Scattermapbox`](https://plotly.com/python/reference/scattermapbox/) traces. Below we show you how to draw a line on Mapbox using Plotly Express.
+
+Here's an example of using `Scattermapbox`.
```python
import plotly.graph_objects as go
@@ -132,5 +167,8 @@ fig.show()
#### Reference
-See [function reference for `px.(line_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.line_mapbox) or
-https://plotly.com/python/reference/scattermapbox/ for more information about mapbox and their attribute options.
+See [function reference for `px.line_map`](https://plotly.com/python-api-reference/generated/plotly.express.line_map) or
+https://plotly.com/python/reference/scattermap/ for more information about the attributes available.
+
+For Mapbox-based tile maps, see [function reference for `px.line_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.line_mapbox) or
+https://plotly.com/python/reference/scattermapbox/.
diff --git a/doc/python/lines-on-maps.md b/doc/python/lines-on-maps.md
index 0d8c3bb1bb3..000ec1d0258 100644
--- a/doc/python/lines-on-maps.md
+++ b/doc/python/lines-on-maps.md
@@ -27,7 +27,7 @@ jupyter:
language: python
layout: base
name: Lines on Maps
- order: 6
+ order: 7
page_type: u-guide
permalink: python/lines-on-maps/
thumbnail: thumbnail/flight-paths.jpg
diff --git a/doc/python/map-configuration.md b/doc/python/map-configuration.md
index 6e9f54e4d7e..6c296d34a83 100644
--- a/doc/python/map-configuration.md
+++ b/doc/python/map-configuration.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.3'
- jupytext_version: 1.14.7
+ jupytext_version: 1.16.3
kernelspec:
display_name: Python 3 (ipykernel)
language: python
@@ -20,27 +20,32 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.10.4
+ version: 3.10.0
plotly:
- description: How to configure and style base maps for Choropleths and Bubble Maps.
+ description: How to configure and style base maps for outline-based Geo Maps.
display_as: maps
language: python
layout: base
- name: Map Configuration and Styling
- order: 12
+ name: Map Configuration and Styling on Geo Maps
+ order: 13
page_type: u-guide
permalink: python/map-configuration/
thumbnail: thumbnail/county-level-choropleth.jpg
---
-### 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 Geo outline-based maps, and the [Mapbox Layers documentation](/python/mapbox-layers/) describes how to configure Mapbox tile-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` object in your figure contains configuration information for the map itself.
+
+- **Outline-based maps**
+
+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.
+
+> This page documents **Geo outline-based maps**, and the [Tile Map Layers documentation](/python/tile-map-layers/) describes how to configure tile-based maps.
**Note:** Plotly Express cannot create empty figures, so the examples below mostly create an "empty" map using `fig = go.Figure(go.Scattergeo())`. That said, every configuration option here is equally applicable to non-empty maps created with the Plotly Express `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions.
diff --git a/doc/python/mapbox-county-choropleth.md b/doc/python/mapbox-county-choropleth.md
index bd439c5e3d2..75b89acb302 100644
--- a/doc/python/mapbox-county-choropleth.md
+++ b/doc/python/mapbox-county-choropleth.md
@@ -6,9 +6,9 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.3'
- jupytext_version: 1.14.1
+ jupytext_version: 1.16.3
kernelspec:
- display_name: Python 3
+ display_name: Python 3 (ipykernel)
language: python
name: python3
language_info:
@@ -20,36 +20,32 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.8.8
+ version: 3.10.0
plotly:
- description: How to make a Mapbox Choropleth Map of US Counties in Python with
- Plotly.
+ description: How to make a choropleth map of US counties in Python with Plotly.
display_as: maps
language: python
layout: base
- name: Mapbox Choropleth Maps
- order: 1
+ name: Tile Choropleth Maps
+ order: 2
page_type: example_index
- permalink: python/mapbox-county-choropleth/
+ permalink: python/tile-county-choropleth/
+ redirect_from: python/mapbox-county-choropleth/
thumbnail: thumbnail/mapbox-choropleth.png
---
-A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **tile-map** choropleth maps, but you can also build [**outline** choropleth maps using our non-Mapbox trace types](/python/choropleth-maps).
+A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **tile-map** choropleth maps, but you can also build [**outline** choropleth maps](/python/choropleth-maps).
-Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth_mapbox` function or the lower-level `go.Choroplethmapbox` graph object.
-
-#### Mapbox Access Tokens and Base Map Configuration
-
-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](/python/mapbox-layers/) documentation for more information.
+Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth_map` function or the lower-level `go.Choroplethmap` graph object.
### Introduction: main parameters for choropleth tile maps
-Making choropleth Mapbox maps requires two main types of input:
+Making choropleth maps requires two main types of input:
1. GeoJSON-formatted geometry information where each feature has either an `id` field or some identifying value in `properties`.
2. A list of values indexed by feature identifier.
-The GeoJSON data is passed to the `geojson` argument, and the data is passed into the `color` argument of `px.choropleth_mapbox` (`z` if using `graph_objects`), in the same order as the IDs are passed into the `location` argument.
+The GeoJSON data is passed to the `geojson` argument, and the data is passed into the `color` argument of `px.choropleth_map` (`z` if using `graph_objects`), in the same order as the IDs are passed into the `location` argument.
**Note** the `geojson` attribute can also be the URL to a GeoJSON file, which can speed up map rendering in certain cases.
@@ -77,11 +73,11 @@ df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-
df.head()
```
-### Choropleth map using plotly.express and carto base map (no token needed)
+### Choropleth map using plotly.express and carto base map
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
-With `px.choropleth_mapbox`, each row of the DataFrame is represented as a region of the choropleth.
+With `px.choropleth_map`, each row of the DataFrame is represented as a region of the choropleth.
```python
from urllib.request import urlopen
@@ -95,10 +91,10 @@ df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-
import plotly.express as px
-fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
+fig = px.choropleth_map(df, geojson=counties, locations='fips', color='unemp',
color_continuous_scale="Viridis",
range_color=(0, 12),
- mapbox_style="carto-positron",
+ map_style="carto-positron",
zoom=3, center = {"lat": 37.0902, "lon": -95.7129},
opacity=0.5,
labels={'unemp':'unemployment rate'}
@@ -148,10 +144,10 @@ import plotly.express as px
df = px.data.election()
geojson = px.data.election_geojson()
-fig = px.choropleth_mapbox(df, geojson=geojson, color="Bergeron",
+fig = px.choropleth_map(df, geojson=geojson, color="Bergeron",
locations="district", featureidkey="properties.district",
center={"lat": 45.5517, "lon": -73.7073},
- mapbox_style="carto-positron", zoom=9)
+ map_style="carto-positron", zoom=9)
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
@@ -166,17 +162,17 @@ import plotly.express as px
df = px.data.election()
geojson = px.data.election_geojson()
-fig = px.choropleth_mapbox(df, geojson=geojson, color="winner",
+fig = px.choropleth_map(df, geojson=geojson, color="winner",
locations="district", featureidkey="properties.district",
center={"lat": 45.5517, "lon": -73.7073},
- mapbox_style="carto-positron", zoom=9)
+ map_style="carto-positron", zoom=9)
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
### Using GeoPandas Data Frames
-`px.choropleth_mapbox` accepts the `geometry` of a [GeoPandas](https://geopandas.org/) data frame as the input to `geojson` if the `geometry` contains polygons.
+`px.choropleth_map` accepts the `geometry` of a [GeoPandas](https://geopandas.org/) data frame as the input to `geojson` if the `geometry` contains polygons.
```python
import plotly.express as px
@@ -187,19 +183,19 @@ geo_df = gpd.GeoDataFrame.from_features(
px.data.election_geojson()["features"]
).merge(df, on="district").set_index("district")
-fig = px.choropleth_mapbox(geo_df,
+fig = px.choropleth_map(geo_df,
geojson=geo_df.geometry,
locations=geo_df.index,
color="Joly",
center={"lat": 45.5517, "lon": -73.7073},
- mapbox_style="open-street-map",
+ map_style="open-street-map",
zoom=8.5)
fig.show()
```
-### Choropleth map using plotly.graph_objects and carto base map (no token needed)
+### Choropleth map using plotly.graph_objects and carto base map
-If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Choroplethmapbox` class from `plotly.graph_objects`](/python/graph-objects/).
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Choroplethmap` class from `plotly.graph_objects`](/python/graph-objects/).
```python
from urllib.request import urlopen
@@ -213,21 +209,28 @@ df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-
import plotly.graph_objects as go
-fig = go.Figure(go.Choroplethmapbox(geojson=counties, locations=df.fips, z=df.unemp,
+fig = go.Figure(go.Choroplethmap(geojson=counties, locations=df.fips, z=df.unemp,
colorscale="Viridis", zmin=0, zmax=12,
marker_opacity=0.5, marker_line_width=0))
-fig.update_layout(mapbox_style="carto-positron",
- mapbox_zoom=3, mapbox_center = {"lat": 37.0902, "lon": -95.7129})
+fig.update_layout(map_style="carto-positron",
+ map_zoom=3, map_center = {"lat": 37.0902, "lon": -95.7129})
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
-#### Mapbox Light base map: free token needed
+### Mapbox Maps
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
+
+The earlier examples using `px.choropleth_map` and `go.Choroplethmap` use [Maplibre](https://maplibre.org/maplibre-gl-js/docs/) for rendering. These traces were introduced in Plotly.py 5.24 and are now the recommended way to create tile-based choropleth maps. There are also choropleth traces that use [Mapbox](https://docs.mapbox.com): `px.choropleth_mapbox` and `go.Choroplethmapbox`
+
+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](/python/mapbox-layers/) documentation for more information.
+
+Here's an exmaple of using the Mapbox Light base map, which requires a free token.
```python
token = open(".mapbox_token").read() # you will need your own token
-
from urllib.request import urlopen
import json
with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
@@ -249,5 +252,6 @@ fig.show()
#### Reference
-See [function reference for `px.(choropleth_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_mapbox) or https://plotly.com/python/reference/choroplethmapbox/ for more information about mapbox and their attribute options.
+See [function reference for `px.choropleth_map`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_map) or https://plotly.com/python/reference/choroplethmap/ for more information about the attributes available.
+For Mapbox-based tile maps, see [function reference for `px.choropleth_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_mapbox) or https://plotly.com/python/reference/choroplethmapbox/.
diff --git a/doc/python/mapbox-density-heatmaps.md b/doc/python/mapbox-density-heatmaps.md
index 85786542536..ea35fa3aa8c 100644
--- a/doc/python/mapbox-density-heatmaps.md
+++ b/doc/python/mapbox-density-heatmaps.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,100 +20,102 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.10.11
+ version: 3.10.0
plotly:
- description: How to make a Mapbox Density Heatmap in Python with Plotly.
+ description: How to make a density heatmap in Python with Plotly.
display_as: maps
language: python
layout: base
- name: Mapbox Density Heatmap
- order: 5
+ name: Density Heatmap
+ order: 6
page_type: u-guide
- permalink: python/mapbox-density-heatmaps/
+ permalink: python/density-heatmaps/
+ redirect_from: python/mapbox-density-heatmaps/
thumbnail: thumbnail/mapbox-density.png
---
-#### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly, you may need a [Mapbox account and token](https://www.mapbox.com/studio) or a [Stadia Maps account and token](https://www.stadiamaps.com), depending on base map (`mapbox_style`) you use. On this page, we show how to use the "open-street-map" base map, which doesn't require a token, and a "stamen" base map, which requires a Stadia Maps token. See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more examples.
-
-### OpenStreetMap base map (no token needed): density mapbox with `plotly.express`
+### Density map with `plotly.express`
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
-With `px.density_mapbox`, each row of the DataFrame is represented as a point smoothed with a given radius of influence.
+With `px.density_map`, each row of the DataFrame is represented as a point smoothed with a given radius of influence.
```python
import pandas as pd
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
import plotly.express as px
-fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
+fig = px.density_map(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
center=dict(lat=0, lon=180), zoom=0,
- mapbox_style="open-street-map")
+ map_style="open-street-map")
fig.show()
```
-
-### Stamen Terrain base map (Stadia Maps token needed): density mapbox with `plotly.express`
+### Density map with `plotly.graph_objects`
-Some base maps require a token. To use "stamen" base maps, you'll need a [Stadia Maps](https://www.stadiamaps.com) token, which you can provide to the `mapbox_accesstoken` parameter on `fig.update_layout`. Here, we have the token saved in a file called `.mapbox_token`, load it in to the variable `token`, and then pass it to `mapbox_accesstoken`.
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Densitymap` class from `plotly.graph_objects`](/python/graph-objects/).
```python
-import plotly.express as px
import pandas as pd
+quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
-token = open(".mapbox_token").read() # you will need your own token
-
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
-
-fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
- center=dict(lat=0, lon=180), zoom=0,
- mapbox_style="stamen-terrain")
-fig.update_layout(mapbox_accesstoken=token)
+import plotly.graph_objects as go
+fig = go.Figure(go.Densitymap(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
+ radius=10))
+fig.update_layout(map_style="open-street-map", map_center_lon=180)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
-
+
+### Mapbox Maps
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
-### OpenStreetMap base map (no token needed): density mapbox with `plotly.graph_objects`
+The earlier examples using `px.density_mapbox` and `go.Densitymap` use [Maplibre](https://maplibre.org/maplibre-gl-js/docs/) for rendering. These traces were introduced in Plotly.py 5.24. These trace types are now the recommended way to make tile-based density heatmaps. There are also traces that use [Mapbox](https://docs.mapbox.com): `density_mapbox` and `go.Densitymapbox`.
-If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Densitymapbox` class from `plotly.graph_objects`](/python/graph-objects/).
+To use these trace types, in some cases you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+
+Here's one of the earlier examples rewritten to use `px.density_mapbox`.
```python
import pandas as pd
-quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
-import plotly.graph_objects as go
-fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
- radius=10))
-fig.update_layout(mapbox_style="open-street-map", mapbox_center_lon=180)
-fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+import plotly.express as px
+fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
+ center=dict(lat=0, lon=180), zoom=0,
+ mapbox_style="open-street-map")
fig.show()
```
+
+
-### Stamen Terrain base map (Stadia Maps token needed): density mapbox with `plotly.graph_objects`
+#### Stamen Terrain base map with Mapbox (Stadia Maps token needed): density heatmap with `plotly.express`
Some base maps require a token. To use "stamen" base maps, you'll need a [Stadia Maps](https://www.stadiamaps.com) token, which you can provide to the `mapbox_accesstoken` parameter on `fig.update_layout`. Here, we have the token saved in a file called `.mapbox_token`, load it in to the variable `token`, and then pass it to `mapbox_accesstoken`.
-
```python
-import plotly.graph_objects as go
+import plotly.express as px
import pandas as pd
token = open(".mapbox_token").read() # you will need your own token
-quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
-fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
- radius=10))
-fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180, mapbox_accesstoken=token)
-fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
+ center=dict(lat=0, lon=180), zoom=0,
+ map_style="stamen-terrain")
+fig.update_layout(mapbox_accesstoken=token)
fig.show()
```
+
+
#### Reference
-See [function reference for `px.(density_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.density_mapbox) or https://plotly.com/python/reference/densitymapbox/ for more information about mapbox and their attribute options.
+See [function reference for `px.(density_map)`](https://plotly.com/python-api-reference/generated/plotly.express.density_mapbox) or https://plotly.com/python/reference/densitymap/ for available attribute options.
+
+For Mapbox-based maps, see [function reference for `px.(density_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.density_mapbox) or https://plotly.com/python/reference/densitymapbox/.
diff --git a/doc/python/mapbox-layers.md b/doc/python/mapbox-layers.md
index e7b672637d3..936b67c925e 100644
--- 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
- order: 8
+ name: Tile Map Layers
+ order: 9
page_type: u-guide
- permalink: python/mapbox-layers/
+ permalink: /python/tile-map-layers/
+ redirect_from: /python/mapbox-layers/
thumbnail: thumbnail/mapbox-layers.png
---
-### 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.
```python
@@ -85,24 +105,22 @@ 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
@@ -110,11 +128,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",
@@ -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,14 +184,80 @@ 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()
+```
+
+
+#### Stamen Watercolor using a Custom Style URL
+
+Here's an example of using a custom style URL that points to the [Stadia Maps](https://docs.stadiamaps.com/map-styles/stamen-watercolor) service to use the `stamen_watercolor` base map.
```python
-token = open(".mapbox_token").read() # you will need your own token
+import pandas as pd
+quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
+
+import plotly.graph_objects as go
+fig = go.Figure(go.Densitymap(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
+ radius=10))
+fig.update_layout(map_style="https://tiles.stadiamaps.com/styles/stamen_watercolor.json?api_key=YOUR-API-KEY", map_center_lon=180)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+
+
+### Mapbox
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
+
+#### 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:
+
+
+```python
import pandas as pd
us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
@@ -181,17 +265,66 @@ 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="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="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
+
+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
+
+import pandas as pd
+us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
-See the example in the [plotly and datashader tutorial](/python/datashader).
+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
+## Setting Map Bounds
*New in 5.11*
@@ -205,7 +338,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 +348,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.
diff --git a/doc/python/migrate-to-maplibre.md b/doc/python/migrate-to-maplibre.md
new file mode 100644
index 00000000000..d7576fef50f
--- /dev/null
+++ b/doc/python/migrate-to-maplibre.md
@@ -0,0 +1,75 @@
+---
+jupyter:
+ jupytext:
+ notebook_metadata_filter: all
+ text_representation:
+ extension: .md
+ format_name: markdown
+ format_version: '1.3'
+ jupytext_version: 1.16.1
+ kernelspec:
+ display_name: Python 3 (ipykernel)
+ language: python
+ name: python3
+ language_info:
+ codemirror_mode:
+ name: ipython
+ version: 3
+ file_extension: .py
+ mimetype: text/x-python
+ name: python
+ nbconvert_exporter: python
+ pygments_lexer: ipython3
+ version: 3.10.11
+ plotly:
+ description: Migrating from Mapbox traces to MapLibre traces.
+ display_as: maps
+ language: python
+ layout: base
+ name: MapLibre Migration
+ order: 1
+ page_type: u-guide
+ permalink: python/mapbox-to-maplibre/
+ thumbnail: thumbnail/mapbox-layers.png
+---
+
+## Migrating from Mapbox traces to MapLibre traces
+
+With the release of Plotly.py v5.24.0, we are introducing a new set of trace types for maps with tile underlays, including from Plotly Express:
+- `px.scatter_map`
+- `px.line_map`
+- `px.choropleth_map`
+- `px.density_map`
+
+as well as Plotly Graph Objects:
+- `go.Choroplethmap`
+- `go.Scattermap`
+- `go.Densitymap`
+
+These traces replace the existing Mapbox traces, `px.scatter_mapbox`, `px.line_mapbox`, etc., but use [MapLibre](https://maplibre.org) as the map renderer rather than Mapbox.
+
+When switching to the new traces, keep an eye out for improved rendering performance, WebGL2 support, and over time, improved features in the Plotly map traces inherited from the MapLibre renderer, including projection support, globe views, terrain support, and support for modern mapping standards.
+
+You can learn more about the motivations for this change in our [announcement post](https://plotly.com/blog/plotly-is-switching-to-maplibre/).
+
+As a result of removing Mapbox as the rendering engine, we're also removing the Mapbox branding from these trace names. This means that migrating from Mapbox traces to MapLibre traces will require some code changes in your projects.
+
+1. Change trace names from `*mapbox` to `*map`. For any existing trace name ending in `*mapbox`, ensure you've removed the "`box`" suffix.
+2. If in use, update `layout.mapbox` argument in your layout configuration to `layout.map`. The nested properties are identical in the new map traces, so no other changes should be required.
+3. If in use, update `mapbox_style` to `map_style`.
+4. Verify your `map_style` settings. With `mapbox` traces, we bundle `basic`, `streets`, `outdoors`, `light`, `dark`, `satellite`, and `satellite-streets` styles, using Mapbox styling. These style names are still available, but they now reference slightly different styles provided by other tools.
+
+Note that Mapbox API keys are no longer required for Plotly-provided styles, but using external styles in your Plotly maps remains supported with the existing API.
+
+### Style changes
+Built-in styles in map traces are free styles from [Carto](https://carto.com) and [ESRI](https://www.esri.com/en-us/home). Several names are re-used from the previous Mapbox styles.
+
+ 
+ 
+
+
+Compare to the previous Mapbox styles:
+
+ 
+ 
+
\ No newline at end of file
diff --git a/doc/python/plotly-express.md b/doc/python/plotly-express.md
index 4e4c30e8f31..0aebc72dccf 100644
--- a/doc/python/plotly-express.md
+++ b/doc/python/plotly-express.md
@@ -60,7 +60,7 @@ Plotly Express currently includes the following functions:
* **Matrix or Image Input**: [`imshow`](/python/imshow/)
* **3-Dimensional**: [`scatter_3d`](/python/3d-scatter-plots/), [`line_3d`](/python/3d-line-plots/)
* **Multidimensional**: [`scatter_matrix`](/python/splom/), [`parallel_coordinates`](/python/parallel-coordinates-plot/), [`parallel_categories`](/python/parallel-categories-diagram/)
-* **Tile Maps**: [`scatter_mapbox`](/python/scattermapbox/), [`line_mapbox`](/python/lines-on-mapbox/), [`choropleth_mapbox`](/python/mapbox-county-choropleth/), [`density_mapbox`](/python/mapbox-density-heatmaps/)
+* **Tile Maps**: [`scatter_map`](/python/tile-scatter-maps/), [`line_map`](/python/lines-on-tile-maps/), [`choropleth_map`](/python/tile-county-choropleth/), [`density_map`](/python/tile-density-heatmaps/)
* **Outline Maps**: [`scatter_geo`](/python/scatter-plots-on-maps/), [`line_geo`](/python/lines-on-maps/), [`choropleth`](/python/choropleth-maps/)
* **Polar Charts**: [`scatter_polar`](/python/polar-chart/), [`line_polar`](/python/polar-chart/), [`bar_polar`](/python/wind-rose-charts/)
* **Ternary Charts**: [`scatter_ternary`](/python/ternary-plots/), [`line_ternary`](/python/ternary-plots/)
@@ -393,18 +393,18 @@ fig.show()
#### Tile Maps
-**Read more about [tile maps](/python/mapbox-layers/) and [point on tile maps](/python/scattermapbox/).**
+**Read more about [tile maps](/python/tile-map-layers/) and [point on tile maps](/python/tile-scatter-maps/).**
```python
import plotly.express as px
df = px.data.carshare()
-fig = px.scatter_mapbox(df, lat="centroid_lat", lon="centroid_lon", color="peak_hour", size="car_hours",
+fig = px.scatter_map(df, lat="centroid_lat", lon="centroid_lon", color="peak_hour", size="car_hours",
color_continuous_scale=px.colors.cyclical.IceFire, size_max=15, zoom=10,
- mapbox_style="carto-positron")
+ map_style="carto-positron")
fig.show()
```
-**Read more about [tile map GeoJSON choropleths](/python/mapbox-county-choropleth/).**
+**Read more about [tile map GeoJSON choropleths](/python/tile-county-choropleth/).**
```python
import plotly.express as px
@@ -412,10 +412,10 @@ import plotly.express as px
df = px.data.election()
geojson = px.data.election_geojson()
-fig = px.choropleth_mapbox(df, geojson=geojson, color="Bergeron",
+fig = px.choropleth_map(df, geojson=geojson, color="Bergeron",
locations="district", featureidkey="properties.district",
center={"lat": 45.5517, "lon": -73.7073},
- mapbox_style="carto-positron", zoom=9)
+ map_style="carto-positron", zoom=9)
fig.show()
```
diff --git a/doc/python/scatter-plots-on-maps.md b/doc/python/scatter-plots-on-maps.md
index 53b582fa128..9c4ad70bea8 100644
--- a/doc/python/scatter-plots-on-maps.md
+++ b/doc/python/scatter-plots-on-maps.md
@@ -28,7 +28,7 @@ jupyter:
language: python
layout: base
name: Scatter Plots on Maps
- order: 11
+ order: 12
page_type: u-guide
permalink: python/scatter-plots-on-maps/
thumbnail: thumbnail/scatter-plot-on-maps.jpg
diff --git a/doc/python/scattermapbox.md b/doc/python/scattermapbox.md
index 1bd58271686..4e209b898cd 100644
--- a/doc/python/scattermapbox.md
+++ b/doc/python/scattermapbox.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.3'
- jupytext_version: 1.16.2
+ jupytext_version: 1.16.3
kernelspec:
display_name: Python 3 (ipykernel)
language: python
@@ -22,39 +22,35 @@ jupyter:
pygments_lexer: ipython3
version: 3.10.0
plotly:
- description: How to make scatter plots on Mapbox maps in Python.
+ description: How to make scatter plots on tile maps in Python.
display_as: maps
language: python
layout: base
name: Scatter Plots on Mapbox
- order: 9
+ order: 10
page_type: u-guide
- permalink: python/scattermapbox/
+ permalink: python/tile-scatter-maps/
+ redirect_from: python/scattermapbox/
thumbnail: thumbnail/scatter-mapbox.jpg
---
-#### Mapbox Access Token and Base Map Configuration
-
-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](/python/mapbox-layers/) documentation for more information.
-
### Basic example with Plotly Express
-Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_mapbox` for a scatter plot on a tile map.
+Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_map` for a scatter plot on a tile map.
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
```python
import plotly.express as px
-px.set_mapbox_access_token(open(".mapbox_token").read())
df = px.data.carshare()
-fig = px.scatter_mapbox(df, lat="centroid_lat", lon="centroid_lon", color="peak_hour", size="car_hours",
+fig = px.scatter_map(df, lat="centroid_lat", lon="centroid_lon", color="peak_hour", size="car_hours",
color_continuous_scale=px.colors.cyclical.IceFire, size_max=15, zoom=10)
fig.show()
```
### Basic Example with GeoPandas
-`px.scatter_mapbox` can work well with [GeoPandas](https://geopandas.org/) dataframes whose `geometry` is of type `Point`.
+`px.scatter_map` can work well with [GeoPandas](https://geopandas.org/) dataframes whose `geometry` is of type `Point`.
```python
import plotly.express as px
@@ -62,8 +58,7 @@ import geopandas as gpd
geo_df = gpd.read_file(gpd.datasets.get_path('naturalearth_cities'))
-px.set_mapbox_access_token(open(".mapbox_token").read())
-fig = px.scatter_mapbox(geo_df,
+fig = px.scatter_map(geo_df,
lat=geo_df.geometry.y,
lon=geo_df.geometry.x,
hover_name="name",
@@ -76,13 +71,11 @@ fig.show()
```python
import plotly.graph_objects as go
-mapbox_access_token = open(".mapbox_token").read()
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
lat=['45.5017'],
lon=['-73.5673'],
mode='markers',
- marker=go.scattermapbox.Marker(
+ marker=go.scattermap.Marker(
size=14
),
text=['Montreal'],
@@ -90,10 +83,9 @@ fig = go.Figure(go.Scattermapbox(
fig.update_layout(
hovermode='closest',
- mapbox=dict(
- accesstoken=mapbox_access_token,
+ map=dict(
bearing=0,
- center=go.layout.mapbox.Center(
+ center=go.layout.map.Center(
lat=45,
lon=-73
),
@@ -110,9 +102,7 @@ fig.show()
```python
import plotly.graph_objects as go
-mapbox_access_token = open(".mapbox_token").read()
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
lat=['38.91427','38.91538','38.91458',
'38.92239','38.93222','38.90842',
'38.91931','38.93260','38.91368',
@@ -124,7 +114,7 @@ fig = go.Figure(go.Scattermapbox(
'-76.99656','-77.042438','-77.02821',
'-77.01239'],
mode='markers',
- marker=go.scattermapbox.Marker(
+ marker=go.scattermap.Marker(
size=9
),
text=["The coffee bar","Bistro Bohem","Black Cat",
@@ -137,8 +127,7 @@ fig = go.Figure(go.Scattermapbox(
fig.update_layout(
autosize=True,
hovermode='closest',
- mapbox=dict(
- accesstoken=mapbox_access_token,
+ map=dict(
bearing=0,
center=dict(
lat=38.92,
@@ -158,8 +147,6 @@ fig.show()
import plotly.graph_objects as go
import pandas as pd
-mapbox_access_token = open(".mapbox_token").read()
-
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/Nuclear%20Waste%20Sites%20on%20American%20Campuses.csv')
site_lat = df.lat
site_lon = df.lon
@@ -167,11 +154,11 @@ locations_name = df.text
fig = go.Figure()
-fig.add_trace(go.Scattermapbox(
+fig.add_trace(go.Scattermap(
lat=site_lat,
lon=site_lon,
mode='markers',
- marker=go.scattermapbox.Marker(
+ marker=go.scattermap.Marker(
size=17,
color='rgb(255, 0, 0)',
opacity=0.7
@@ -180,11 +167,11 @@ fig.add_trace(go.Scattermapbox(
hoverinfo='text'
))
-fig.add_trace(go.Scattermapbox(
+fig.add_trace(go.Scattermap(
lat=site_lat,
lon=site_lon,
mode='markers',
- marker=go.scattermapbox.Marker(
+ marker=go.scattermap.Marker(
size=8,
color='rgb(242, 177, 172)',
opacity=0.7
@@ -197,8 +184,7 @@ fig.update_layout(
autosize=True,
hovermode='closest',
showlegend=False,
- mapbox=dict(
- accesstoken=mapbox_access_token,
+ map=dict(
bearing=0,
center=dict(
lat=38,
@@ -215,7 +201,7 @@ fig.show()
### Set Marker Symbols
-You can define a symbol on your map by setting [symbol](https://plotly.com/python/reference/scattermapbox/#scattermapbox-marker-symbol) attribute. This attribute only works on Mapbox-provided `style`s:
+You can define the symbol on your map by setting [`symbol`](https://plotly.com/python/reference/scattermap/#scattermap-marker-symbol) attribute.
- basic
- streets
@@ -228,17 +214,14 @@ You can define a symbol on your map by setting [symbol](https://plotly.com/pytho
```python
import plotly.graph_objects as go
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
mode = "markers+text+lines",
lon = [-75, -80, -50], lat = [45, 20, -20],
marker = {'size': 20, 'symbol': ["bus", "harbor", "airport"]},
text = ["Bus", "Harbor", "airport"],textposition = "bottom right"))
fig.update_layout(
- mapbox = {
- 'accesstoken': token,
+ map = {
'style': "outdoors", 'zoom': 0.7},
showlegend = False)
@@ -255,11 +238,10 @@ Display clusters of data points by setting `cluster`. Here, we enable clusters w
import plotly.express as px
import pandas as pd
-px.set_mapbox_access_token(open(".mapbox_token").read())
df = pd.read_csv(
"https://raw.githubusercontent.com/plotly/datasets/master/2011_february_us_airport_traffic.csv"
)
-fig = px.scatter_mapbox(df, lat="lat", lon="long", size="cnt", zoom=3)
+fig = px.scatter_map(df, lat="lat", lon="long", size="cnt", zoom=3)
fig.update_traces(cluster=dict(enabled=True))
fig.show()
@@ -267,14 +249,12 @@ fig.show()
#### Font Customization
-You can customize the font on `go.Scattermapbox` traces with `textfont`. For example, you can set the font `family`.
+You can customize the font on `go.Scattermap` traces with `textfont`. For example, you can set the font `family`.
```python
import plotly.graph_objects as go
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
mode = "markers+text+lines",
lon = [-75, -80, -50], lat = [45, 20, -20],
marker = {'size': 20, 'symbol': ["bus", "harbor", "airport"]},
@@ -283,15 +263,14 @@ fig = go.Figure(go.Scattermapbox(
))
fig.update_layout(
- mapbox = {
- 'accesstoken': token,
+ map = {
'style': "outdoors", 'zoom': 0.7},
showlegend = False,)
fig.show()
```
-`go.Scattermapbox` supports the following values for `textfont.family`:
+`go.Scattermap` supports the following values for `textfont.family`:
'Metropolis Black Italic', 'Metropolis Black', 'Metropolis Bold Italic', 'Metropolis Bold', 'Metropolis Extra Bold Italic', 'Metropolis Extra Bold', 'Metropolis Extra Light Italic', 'Metropolis Extra Light', 'Metropolis Light Italic', 'Metropolis Light', 'Metropolis Medium Italic', 'Metropolis Medium', 'Metropolis Regular Italic', 'Metropolis Regular', 'Metropolis Semi Bold Italic', 'Metropolis Semi Bold', 'Metropolis Thin Italic', 'Metropolis Thin', 'Open Sans Bold Italic', 'Open Sans Bold', 'Open Sans Extrabold Italic', 'Open Sans Extrabold', 'Open Sans Italic', 'Open Sans Light Italic', 'Open Sans Light', 'Open Sans Regular', 'Open Sans Semibold Italic', 'Open Sans Semibold', 'Klokantech Noto Sans Bold', 'Klokantech Noto Sans CJK Bold', 'Klokantech Noto Sans CJK Regular', 'Klokantech Noto Sans Italic', and 'Klokantech Noto Sans Regular'.
@@ -300,14 +279,12 @@ fig.show()
*New in 5.23*
-You can specify a numeric font weight on `go.Scattermapbox` with `textfont.weight`.
+You can specify a numeric font weight on `go.Scattermap` with `textfont.weight`.
```python
import plotly.graph_objects as go
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
mode = "markers+text+lines",
lon = [-75, -80, -50], lat = [45, 20, -20],
marker = dict(size=20, symbol=["bus", "harbor", "airport"]),
@@ -316,14 +293,68 @@ fig = go.Figure(go.Scattermapbox(
))
fig.update_layout(
- mapbox = dict(
- accesstoken=token,
+ map = dict(
style="outdoors", zoom=0.7),
showlegend = False,)
fig.show()
```
+## Mapbox Maps
+
+> Mapbox traces are deprecated and may be removed in a future version of Plotly.py.
+The earlier examples using `px.scatter_map` and `go.Scattermap` use [Maplibre](https://maplibre.org/maplibre-gl-js/docs/) for rendering. These traces were introduced in Plotly.py 5.24 and are now the recommended way to create scatter plots on tile-based maps. There are also traces that use [Mapbox](https://docs.mapbox.com): `px.scatter_mapbox` and `go.Scattermapbox`
+
+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](/python/mapbox-layers/) documentation for more information.
+
+Here's the first example rewritten to use `px.scatter_mapbox`.
+
+```python
+import plotly.express as px
+px.set_mapbox_access_token(open(".mapbox_token").read())
+df = px.data.carshare()
+fig = px.scatter_mapbox(df, lat="centroid_lat", lon="centroid_lon", color="peak_hour", size="car_hours",
+ color_continuous_scale=px.colors.cyclical.IceFire, size_max=15, zoom=10)
+fig.show()
+
+```
+
+And here's an example using Graph Objects:
+
+```python
+import plotly.graph_objects as go
+
+mapbox_access_token = open(".mapbox_token").read()
+
+fig = go.Figure(go.Scattermapbox(
+ lat=['45.5017'],
+ lon=['-73.5673'],
+ mode='markers',
+ marker=go.scattermapbox.Marker(
+ size=14
+ ),
+ text=['Montreal'],
+ ))
+
+fig.update_layout(
+ hovermode='closest',
+ mapbox=dict(
+ accesstoken=mapbox_access_token,
+ bearing=0,
+ center=go.layout.mapbox.Center(
+ lat=45,
+ lon=-73
+ ),
+ pitch=0,
+ zoom=5
+ )
+)
+
+fig.show()
+```
+
#### Reference
-See [function reference for `px.(scatter_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermapbox/ for more information and options!
+See [function reference for `px.scatter_map`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermap/ for more information about the attributes available.
+
+For Mapbox-based tile maps, see [function reference for `px.scatter_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermapbox/.
diff --git a/doc/unconverted/python/tesla-supercharging-stations.md b/doc/unconverted/python/tesla-supercharging-stations.md
index 28db02a40fd..0d669bc255d 100644
--- a/doc/unconverted/python/tesla-supercharging-stations.md
+++ b/doc/unconverted/python/tesla-supercharging-stations.md
@@ -18,7 +18,7 @@ jupyter:
language: python
layout: base
name: Tesla Supercharging Stations
- order: 10
+ order: 11
page_type: u-guide
permalink: python/tesla-supercharging-stations/
thumbnail: thumbnail/tesla-stations.jpg
diff --git a/packages/python/plotly/plotly/_subplots.py b/packages/python/plotly/plotly/_subplots.py
index 51898363975..a1bb4219c94 100644
--- a/packages/python/plotly/plotly/_subplots.py
+++ b/packages/python/plotly/plotly/_subplots.py
@@ -8,7 +8,7 @@
# little differently.
import collections
-_single_subplot_types = {"scene", "geo", "polar", "ternary", "mapbox"}
+_single_subplot_types = {"scene", "geo", "polar", "ternary", "map", "mapbox"}
_subplot_types = set.union(_single_subplot_types, {"xy", "domain"})
# For most subplot types, a trace is associated with a particular subplot
@@ -20,7 +20,7 @@
# the trace property is just named `subplot`. For example setting
# the `scatterpolar.subplot` property to `polar3` associates the scatterpolar
# trace with the third polar subplot in the figure
-_subplot_prop_named_subplot = {"polar", "ternary", "mapbox"}
+_subplot_prop_named_subplot = {"polar", "ternary", "map", "mapbox"}
# Named tuple to hold an xaxis/yaxis pair that represent a single subplot
@@ -150,7 +150,8 @@ def make_subplots(
- 'scene': 3D Cartesian subplot for scatter3d, cone, etc.
- 'polar': Polar subplot for scatterpolar, barpolar, etc.
- 'ternary': Ternary subplot for scatterternary
- - 'mapbox': Mapbox subplot for scattermapbox
+ - 'map': Map subplot for scattermap, choroplethmap and densitymap
+ - 'mapbox': Mapbox subplot for scattermapbox, choroplethmapbox and densitymapbox
- 'domain': Subplot type for traces that are individually
positioned. pie, parcoords, parcats, etc.
- trace type: A trace type which will be used to determine
diff --git a/packages/python/plotly/plotly/express/__init__.py b/packages/python/plotly/plotly/express/__init__.py
index 4dd37f64fc3..935d6745788 100644
--- a/packages/python/plotly/plotly/express/__init__.py
+++ b/packages/python/plotly/plotly/express/__init__.py
@@ -17,12 +17,14 @@
scatter_3d,
scatter_polar,
scatter_ternary,
+ scatter_map,
scatter_mapbox,
scatter_geo,
line,
line_3d,
line_polar,
line_ternary,
+ line_map,
line_mapbox,
line_geo,
area,
@@ -46,7 +48,9 @@
icicle,
funnel,
funnel_area,
+ choropleth_map,
choropleth_mapbox,
+ density_map,
density_mapbox,
)
@@ -67,16 +71,19 @@
"scatter_3d",
"scatter_polar",
"scatter_ternary",
+ "scatter_map",
"scatter_mapbox",
"scatter_geo",
"scatter_matrix",
"density_contour",
"density_heatmap",
+ "density_map",
"density_mapbox",
"line",
"line_3d",
"line_polar",
"line_ternary",
+ "line_map",
"line_mapbox",
"line_geo",
"parallel_coordinates",
@@ -91,6 +98,7 @@
"histogram",
"ecdf",
"choropleth",
+ "choropleth_map",
"choropleth_mapbox",
"pie",
"sunburst",
diff --git a/packages/python/plotly/plotly/express/_chart_types.py b/packages/python/plotly/plotly/express/_chart_types.py
index 74cdf84fa49..b444c0f25d7 100644
--- a/packages/python/plotly/plotly/express/_chart_types.py
+++ b/packages/python/plotly/plotly/express/_chart_types.py
@@ -1211,6 +1211,153 @@ def line_geo(
line_geo.__doc__ = make_docstring(line_geo)
+def scatter_map(
+ data_frame=None,
+ lat=None,
+ lon=None,
+ color=None,
+ text=None,
+ hover_name=None,
+ hover_data=None,
+ custom_data=None,
+ size=None,
+ animation_frame=None,
+ animation_group=None,
+ category_orders=None,
+ labels=None,
+ color_discrete_sequence=None,
+ color_discrete_map=None,
+ color_continuous_scale=None,
+ range_color=None,
+ color_continuous_midpoint=None,
+ opacity=None,
+ size_max=None,
+ zoom=8,
+ center=None,
+ map_style=None,
+ title=None,
+ template=None,
+ width=None,
+ height=None,
+) -> go.Figure:
+ """
+ In a scatter map, each row of `data_frame` is represented by a
+ symbol mark on the map.
+ """
+ return make_figure(args=locals(), constructor=go.Scattermap)
+
+
+scatter_map.__doc__ = make_docstring(scatter_map)
+
+
+def choropleth_map(
+ data_frame=None,
+ geojson=None,
+ featureidkey=None,
+ locations=None,
+ color=None,
+ hover_name=None,
+ hover_data=None,
+ custom_data=None,
+ animation_frame=None,
+ animation_group=None,
+ category_orders=None,
+ labels=None,
+ color_discrete_sequence=None,
+ color_discrete_map=None,
+ color_continuous_scale=None,
+ range_color=None,
+ color_continuous_midpoint=None,
+ opacity=None,
+ zoom=8,
+ center=None,
+ map_style=None,
+ title=None,
+ template=None,
+ width=None,
+ height=None,
+) -> go.Figure:
+ """
+ In a choropleth map, each row of `data_frame` is represented by a
+ colored region on the map.
+ """
+ return make_figure(args=locals(), constructor=go.Choroplethmap)
+
+
+choropleth_map.__doc__ = make_docstring(choropleth_map)
+
+
+def density_map(
+ data_frame=None,
+ lat=None,
+ lon=None,
+ z=None,
+ hover_name=None,
+ hover_data=None,
+ custom_data=None,
+ animation_frame=None,
+ animation_group=None,
+ category_orders=None,
+ labels=None,
+ color_continuous_scale=None,
+ range_color=None,
+ color_continuous_midpoint=None,
+ opacity=None,
+ zoom=8,
+ center=None,
+ map_style=None,
+ radius=None,
+ title=None,
+ template=None,
+ width=None,
+ height=None,
+) -> go.Figure:
+ """
+ In a density map, each row of `data_frame` contributes to the intensity of
+ the color of the region around the corresponding point on the map
+ """
+ return make_figure(
+ args=locals(), constructor=go.Densitymap, trace_patch=dict(radius=radius)
+ )
+
+
+density_map.__doc__ = make_docstring(density_map)
+
+
+def line_map(
+ data_frame=None,
+ lat=None,
+ lon=None,
+ color=None,
+ text=None,
+ hover_name=None,
+ hover_data=None,
+ custom_data=None,
+ line_group=None,
+ animation_frame=None,
+ animation_group=None,
+ category_orders=None,
+ labels=None,
+ color_discrete_sequence=None,
+ color_discrete_map=None,
+ zoom=8,
+ center=None,
+ map_style=None,
+ title=None,
+ template=None,
+ width=None,
+ height=None,
+) -> go.Figure:
+ """
+ In a line map, each row of `data_frame` is represented as
+ vertex of a polyline mark on the map.
+ """
+ return make_figure(args=locals(), constructor=go.Scattermap)
+
+
+line_map.__doc__ = make_docstring(line_map)
+
+
def scatter_mapbox(
data_frame=None,
lat=None,
diff --git a/packages/python/plotly/plotly/express/_core.py b/packages/python/plotly/plotly/express/_core.py
index 36c57055331..9a79810506d 100644
--- a/packages/python/plotly/plotly/express/_core.py
+++ b/packages/python/plotly/plotly/express/_core.py
@@ -426,7 +426,11 @@ def make_trace_kwargs(args, trace_spec, trace_data, mapping_labels, sizeref):
# as a list of row lists, which is what we want
trace_patch["customdata"] = trace_data[customdata_cols]
elif attr_name == "color":
- if trace_spec.constructor in [go.Choropleth, go.Choroplethmapbox]:
+ if trace_spec.constructor in [
+ go.Choropleth,
+ go.Choroplethmap,
+ go.Choroplethmapbox,
+ ]:
trace_patch["z"] = trace_data[attr_value]
trace_patch["coloraxis"] = "coloraxis1"
mapping_labels[attr_label] = "%{z}"
@@ -532,6 +536,9 @@ def configure_axes(args, constructor, fig, orders):
go.Scatterpolar: configure_polar_axes,
go.Scatterpolargl: configure_polar_axes,
go.Barpolar: configure_polar_axes,
+ go.Scattermap: configure_map,
+ go.Choroplethmap: configure_map,
+ go.Densitymap: configure_map,
go.Scattermapbox: configure_mapbox,
go.Choroplethmapbox: configure_mapbox,
go.Densitymapbox: configure_mapbox,
@@ -739,6 +746,20 @@ def configure_mapbox(args, fig, orders):
)
+def configure_map(args, fig, orders):
+ center = args["center"]
+ if not center and "lat" in args and "lon" in args:
+ center = dict(
+ lat=args["data_frame"][args["lat"]].mean(),
+ lon=args["data_frame"][args["lon"]].mean(),
+ )
+ fig.update_maps(
+ center=center,
+ zoom=args["zoom"],
+ style=args["map_style"],
+ )
+
+
def configure_geo(args, fig, orders):
fig.update_geos(
center=args["center"],
@@ -1911,7 +1932,7 @@ def infer_config(args, constructor, trace_patch, layout_patch):
else:
trace_patch["texttemplate"] = "%{" + letter + ":" + args["text_auto"] + "}"
- if constructor in [go.Histogram2d, go.Densitymapbox]:
+ if constructor in [go.Histogram2d, go.Densitymap, go.Densitymapbox]:
show_colorbar = True
trace_patch["coloraxis"] = "coloraxis1"
@@ -1919,7 +1940,13 @@ def infer_config(args, constructor, trace_patch, layout_patch):
if args["opacity"] is None:
if "barmode" in args and args["barmode"] == "overlay":
trace_patch["marker"] = dict(opacity=0.5)
- elif constructor in [go.Densitymapbox, go.Pie, go.Funnel, go.Funnelarea]:
+ elif constructor in [
+ go.Densitymap,
+ go.Densitymapbox,
+ go.Pie,
+ go.Funnel,
+ go.Funnelarea,
+ ]:
trace_patch["opacity"] = args["opacity"]
else:
trace_patch["marker"] = dict(opacity=args["opacity"])
@@ -1937,7 +1964,7 @@ def infer_config(args, constructor, trace_patch, layout_patch):
modes.add("lines")
trace_patch["mode"] = "+".join(sorted(modes))
elif constructor != go.Splom and (
- "symbol" in args or constructor == go.Scattermapbox
+ "symbol" in args or constructor in [go.Scattermap, go.Scattermapbox]
):
trace_patch["mode"] = "markers" + ("+text" if args["text"] else "")
@@ -2154,7 +2181,9 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
go.Parcats,
go.Parcoords,
go.Choropleth,
+ go.Choroplethmap,
go.Choroplethmapbox,
+ go.Densitymap,
go.Densitymapbox,
go.Histogram2d,
go.Sunburst,
@@ -2198,7 +2227,8 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
):
trace.update(marker=dict(color=m.val_map[val]))
elif (
- trace_spec.constructor in [go.Choropleth, go.Choroplethmapbox]
+ trace_spec.constructor
+ in [go.Choropleth, go.Choroplethmap, go.Choroplethmapbox]
and m.variable == "color"
):
trace.update(
@@ -2281,7 +2311,11 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
)
if show_colorbar:
- colorvar = "z" if constructor in [go.Histogram2d, go.Densitymapbox] else "color"
+ colorvar = (
+ "z"
+ if constructor in [go.Histogram2d, go.Densitymap, go.Densitymapbox]
+ else "color"
+ )
range_color = args["range_color"] or [None, None]
colorscale_validator = ColorscaleValidator("colorscale", "make_figure")
diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py
index ebab116b42e..75f09b6fab1 100644
--- a/packages/python/plotly/plotly/express/_doc.py
+++ b/packages/python/plotly/plotly/express/_doc.py
@@ -531,6 +531,11 @@
"Dict keys are `'lat'` and `'lon'`",
"Sets the center point of the map.",
],
+ map_style=[
+ "str (default `'basic'`)",
+ "Identifier of base map style.",
+ "Allowed values are `'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'`.",
+ ],
mapbox_style=[
"str (default `'basic'`, needs Mapbox API token)",
"Identifier of base map style, some of which require a Mapbox or Stadia Maps API token to be set using `plotly.express.set_mapbox_access_token()`.",
diff --git a/packages/python/plotly/plotly/subplots.py b/packages/python/plotly/plotly/subplots.py
index 018325df904..0ee6a654776 100644
--- a/packages/python/plotly/plotly/subplots.py
+++ b/packages/python/plotly/plotly/subplots.py
@@ -114,6 +114,7 @@ def make_subplots(
- 'scene': 3D Cartesian subplot for scatter3d, cone, etc.
- 'polar': Polar subplot for scatterpolar, barpolar, etc.
- 'ternary': Ternary subplot for scatterternary
+ - 'map': Map subplot for scattermap
- 'mapbox': Mapbox subplot for scattermapbox
- 'domain': Subplot type for traces that are individually
positioned. pie, parcoords, parcats, etc.
diff --git a/packages/python/plotly/templategen/utils/__init__.py b/packages/python/plotly/templategen/utils/__init__.py
index 38ac75e0608..812e5652925 100644
--- a/packages/python/plotly/templategen/utils/__init__.py
+++ b/packages/python/plotly/templategen/utils/__init__.py
@@ -20,6 +20,7 @@
("scattergl", "marker"),
("scatter3d", "line"),
("scatter3d", "marker"),
+ ("scattermap", "marker"),
("scattermapbox", "marker"),
("scatterternary", "marker"),
("scattercarpet", "marker"),