Merge pull request #4476 from plotly/update-plotly-js-2-28-0

Update plotly.js version to 2.29.0 + add Plotly.py docs examples

Author: LiamConnors

CHANGELOG.md

@@ -5,6 +5,16 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [UNRELEASED]
 
 ### Updated
+
+- Updated Plotly.js from version 2.27.0 to version 2.29.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2291----2024-02-12) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  - Add `layout.barcornerradius` and `trace.marker.cornerradius` properties to support rounding the corners of bar traces [[#6761](https://github.com/plotly/plotly.js/pull/6761)],
+   with thanks to [Displayr](https://www.displayr.com) for sponsoring development!
+  - Add `autotickangles` to cartesian and radial axes [[#6790](https://github.com/plotly/plotly.js/pull/6790)], with thanks to @my-tien for the contribution!
+  - Add `align` option to sankey nodes to control horizontal alignment [[#6800](https://github.com/plotly/plotly.js/pull/6800)],
+   with thanks to @adamreeve for the contribution!
+  - Add the possibility of loading "virtual-webgl" script for WebGL 1 to help display several WebGL contexts on a page [[#6784](https://github.com/plotly/plotly.js/pull/6784)], with thanks to @greggman for the contribution!
+  - Add options to use base64 encoding (`bdata`) and `shape` (for 2 dimensional arrays) to declare various typed arrays i.e. `dtype=(float64|float32|int32|int16|int8|uint32|uint16|uint8)` [[#5230](https://github.com/plotly/plotly.js/pull/5230)]
+  -  Adjust stamen styles to point to `stadiamaps.com`, the users may also need to provide their own API_KEY via `config.mapboxAccessToken` [[#6776](https://github.com/plotly/plotly.js/pull/6776), [#6778](https://github.com/plotly/plotly.js/pull/6778)]
 - Removed Python 3.6 and Python 3.7 support [[#4492](https://github.com/plotly/plotly.py/pull/4492)]
 
 ### Fixed

doc/python/axes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.15.1
+      jupytext_version: 1.16.1
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.4
+    version: 3.10.11
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -363,6 +363,23 @@ fig.update_xaxes(tickangle=45, tickfont=dict(family='Rockwell', color='crimson',
 fig.show()
 ```
 
+##### Auto Tick Angle Options
+
+*New in 5.19*
+
+If `tickangle` is not explicitly set, its default value is `auto`, meaning if the label needs to be rotated to avoid labels overlapping, it will rotate by either 30 or 90 degrees. Using `autotickangles`, you can also specify a list of angles for `tickangle` to use. If `tickangle` is `auto` and you provide a list of angles to `autotickangles`, the label angle will be set to the first value in the list that prevents overlap. 
+
+```python
+import plotly.express as px
+df = px.data.gapminder()
+df = df.loc[(df.continent=="Asia") & (df.year==1992)]
+fig = px.histogram(df, x=df.country, y=df.gdpPercap)
+
+fig.update_xaxes(autotickangles=[45, 60, 90])
+
+fig.show()
+```
+
 #### Enumerated Ticks with Tickvals and Ticktext
 
 The `tickvals` and `ticktext` axis properties can be used together to display custom tick label text at custom locations along an axis. They should be set to lists of the same length where the `tickvals` list contains positions along the axis, and `ticktext` contains the strings that should be displayed at the corresponding positions.

doc/python/bar-charts.md

@@ -6,9 +6,9 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.16.1
   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.8.8
+    version: 3.10.11
   plotly:
     description: How to make Bar Charts in Python with Plotly.
     display_as: basic
@@ -480,6 +480,64 @@ fig.add_trace(go.Bar(x=years, y=[300, 400, 700],
                 name='revenue'
                 ))
 
+fig.show()
+```
+
+### Rounded Bars
+
+*New in 5.19*
+
+You can round the corners on all bar traces in a figure by setting `barcornerradius` on the figure's layout. `barcornerradius` can be a number of pixels or a percentage of the bar width (using a string ending in %, for example "20%").
+
+In this example, we set all bars to have a radius of 15 pixels.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.medals_wide()
+
+fig = go.Figure(
+    data=[
+        go.Bar(x=df.nation, y=df.gold, name="Gold"),
+        go.Bar(x=df.nation, y=df.silver, name="Silver"),
+        go.Bar(x=df.nation, y=df.bronze, name="Bronze"),
+    ],
+    layout=dict(
+        barcornerradius=15,
+    ),
+)
+
+fig.show()
+```
+
+When you don't want all bar traces in a figure to have the same rounded corners, you can instead configure rounded corners on each trace using `marker.cornerradius`. In this example, which uses subplots, the first trace has a corner radius of 30 pixels, the second trace has a bar corner radius of 30% of the bar width, and the third trace has no rounded corners set.
+
+```python
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from plotly import data
+
+df = data.medals_wide()
+
+fig = make_subplots(rows=1, cols=3, shared_yaxes=True)
+
+fig.add_trace(
+    go.Bar(x=df.nation, y=df.gold, name="Gold", marker=dict(cornerradius=30)), 1, 1
+)
+fig.add_trace(
+    go.Bar(x=df.nation, y=df.silver, name="Silver", marker=dict(cornerradius="30%")),
+    1,
+    2,
+)
+
+fig.add_trace(
+    go.Bar(x=df.nation, y=df.bronze, name="Bronze"),
+    1,
+    3,
+)
+
+
 fig.show()
 ```
 

doc/python/mapbox-density-heatmaps.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.14.6
   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.11
   plotly:
     description: How to make a Mapbox Density Heatmap in Python with Plotly.
     display_as: maps
@@ -35,9 +35,10 @@ jupyter:
 
 #### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+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.
 
-### Stamen Terrain base map (no token needed): density mapbox with `plotly.express`
+
+### OpenStreetMap base map (no token needed): density mapbox 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/).
 
@@ -48,13 +49,35 @@ 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,
+                        center=dict(lat=0, lon=180), zoom=0,
+                        mapbox_style="open-street-map")
+fig.show()
+```
+
+<!-- #region -->
+### Stamen Terrain base map (Stadia Maps token needed): density mapbox 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.express as px
+import pandas as pd
+
+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)
 fig.show()
 ```
 
-### Stamen Terrain base map (no token needed): density mapbox with `plotly.graph_objects`
+<!-- #endregion -->
+
+### OpenStreetMap base map (no token needed): density mapbox with `plotly.graph_objects`
 
 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/).
 
@@ -65,10 +88,32 @@ quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/e
 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="stamen-terrain", mapbox_center_lon=180)
+fig.update_layout(mapbox_style="open-street-map", mapbox_center_lon=180)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+<!-- #region -->
+### Stamen Terrain base map (Stadia Maps token needed): density mapbox 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`.
+
+
+```python
+import plotly.graph_objects as go
+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')
+
+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.show()
 ```
+<!-- #endregion -->
 
 #### Reference
 

doc/python/mapbox-layers.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.6
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.0
+    version: 3.10.11
   plotly:
     description: How to make Mapbox maps in Python with various base layers, with
       or without needing a Mapbox Access token.
@@ -55,17 +55,21 @@ Mapbox tile maps are composed of various layers, of three different types:
 
 #### 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).
+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. 
 
-> If your `layout.mapbox.style` does not use data from the Mapbox service, you do _not_ need to register for a Mapbox account.
 
 #### 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"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yield maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens
+- `"open-street-map"`, `"carto-positron"`, or `"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/
 
@@ -88,7 +92,6 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### Using `layout.mapbox.layers` to Specify a Base Map
 
@@ -100,7 +103,6 @@ If you have access to your own private tile servers, or wish to use a tile serve
 
 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.
 
-<!-- #endregion -->
 
 ```python
 import pandas as pd
@@ -126,13 +128,11 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
 
 Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the `go.Scattermapbox` trace, as is the default:
 
-<!-- #endregion -->
 
 ```python
 import pandas as pd
@@ -165,13 +165,11 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### 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:
 
-<!-- #endregion -->
 
 ```python
 token = open(".mapbox_token").read() # you will need your own token