Merge pull request #4569 from plotly/docs-updates-5-21

Update plotly.js version to 2.31.0 + add docs

Author: LiamConnors

Diff for: .circleci/config.yml

@@ -447,7 +447,7 @@ jobs:
     resource_class: xlarge
     docker:
       # specify the version you desire here
-      # use `-browsers` prefix for selenium tests, for example, `3.6.1-browsers`
+      # use `-browsers` prefix for selenium tests, for example, `3.9-browsers`
       - image: cimg/python:3.9-browsers
 
     steps:

Diff for: CHANGELOG.md

@@ -2,6 +2,17 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+
+### Updated
+- Updated Plotly.js from version 2.30.0 to version 2.31.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2311----2024-04-15) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  - Add `zorder` attribute to various cartesian traces for controlling stacking order of SVG traces drawn into a subplot [[#6918](https://github.com/plotly/plotly.js/pull/6918), [#6953](https://github.com/plotly/plotly.js/pull/6953)],
+    This feature was anonymously sponsored: thank you to our sponsor!
+  - Add "between" option to shape layer for placing them above grid lines and below traces [[#6927](https://github.com/plotly/plotly.js/pull/6927)],
+    with thanks to @my-tien for the contribution!
+  - Add "raw" `sizemode` to cone trace [[#6938](https://github.com/plotly/plotly.js/pull/6938)]
+  - Add `layout.hoversubplots` to enable hover effects across multiple cartesian suplots sharing one axis [[#6947](https://github.com/plotly/plotly.js/pull/6947), [#6950](https://github.com/plotly/plotly.js/pull/6950)]
+
 ## [5.20.0] - 2024-03-13
 
 ### Updated

Diff for: doc/python/cone-plot.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.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.7.3
+    version: 3.10.11
   plotly:
     description: How to make 3D Cone plots in Python with Plotly.
     display_as: 3d_charts
@@ -126,5 +126,43 @@ fig.update_layout(scene=dict(aspectratio=dict(x=1, y=1, z=0.8),
 fig.show()
 ```
 
+### Sizemode
+
+Earlier examples use `sizemode="absolute"` when adjusting the cone size scaling with `sizeref`. `sizemode` also supports `raw`(new in 5.21) and `scaled`.
+
+```python
+import plotly.graph_objects as go
+import pandas as pd
+
+df = pd.read_csv(
+    "https://raw.githubusercontent.com/plotly/datasets/master/cone_plot_data.csv"
+)
+
+fig = go.Figure(
+    data=go.Cone(
+        x=df["x"],
+        y=df["y"],
+        z=df["z"],
+        u=df["u"],
+        v=df["v"],
+        w=df["w"],
+        sizemode="raw",
+        sizeref=0.1,
+        colorscale="Portland",
+        cmin=0,
+        cmax=80,
+        hoverinfo="u+v+w+text",
+        text="-> wind <-",
+    ),
+    layout=dict(
+        width=900, height=600, scene=dict(camera=dict(eye=dict(x=1.2, y=0, z=0.6)))
+    ),
+)
+
+
+fig.show()
+
+```
+
 #### Reference
-See https://plotly.com/python/reference/ for more information and chart attribute options!
+See https://plotly.com/python/reference/ for more information and chart attribute options!

Diff for: doc/python/graphing-multiple-chart-types.md

@@ -6,7 +6,7 @@ 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 (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 design figures with multiple chart types in python.
     display_as: file_settings
@@ -208,5 +208,41 @@ fig.add_trace(
 fig.show()
 ```
 
+#### Trace Zorder
+
+*New in 5.21*
+
+You can move a trace in front of or behind another trace by setting its `zorder`. All traces have a default `zorder` of `0`. In the following example, we set `zorder` on the bar trace to `1` to move it in front of the scatter trace.
+
+```python
+import plotly.graph_objects as go
+
+x = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+y_bar = [10, 15, 7, 10, 17, 15, 14, 20, 16, 19, 15, 17]
+y_area = [12, 13, 10, 14, 15, 13, 16, 18, 15, 17, 14, 16]
+
+area_trace = go.Scatter(
+    x=x,
+    y=y_area,
+    fill="tozeroy",
+    mode="lines+markers",
+    name="Area Trace with default `zorder` of 0",
+    line=dict(color="lightsteelblue"),
+)
+
+bar_trace = go.Bar(
+    x=x,
+    y=y_bar,
+    name="Bar Trace with `zorder` of 1",
+    zorder=1,
+    marker=dict(color="lightslategray"),
+)
+
+fig = go.Figure(data=[area_trace, bar_trace])
+
+fig.show()
+
+```
+
 #### Reference
 See https://plotly.com/python/reference/ for more information and attribute options!

Diff for: doc/python/hover-text-and-formatting.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 use hover text and formatting in Python with Plotly.
     display_as: file_settings
@@ -116,6 +116,37 @@ fig.update_layout(hovermode='x unified')
 fig.show()
 ```
 
+#### Hover on Subplots
+
+*New in 5.21*
+
+Use `hoversubplots` to define how hover effects expand to additional subplots. With `hoversubplots=axis`, hover effects are included on stacked subplots using the same axis when `hovermode` is set to `x`, `x unified`, `y`, or `y unified`.
+
+```python
+import plotly.graph_objects as go
+import pandas as pd
+from plotly import data
+
+df = data.stocks()
+
+layout = dict(
+    hoversubplots="axis",
+    title="Stock Price Changes",
+    hovermode="x",
+    grid=dict(rows=3, columns=1),
+)
+
+data = [
+    go.Scatter(x=df["date"], y=df["AAPL"], xaxis="x", yaxis="y", name="Apple"),
+    go.Scatter(x=df["date"], y=df["GOOG"], xaxis="x", yaxis="y2", name="Google"),
+    go.Scatter(x=df["date"], y=df["AMZN"], xaxis="x", yaxis="y3", name="Amazon"),
+]
+
+fig = go.Figure(data=data, layout=layout)
+
+fig.show()
+```
+
 ### Customizing Hover Label Appearance
 
 Hover label text and colors default to trace colors in hover modes other than `unified`, and can be globally set via the `layout.hoverlabel` attributes. Hover label appearance can also be controlled per trace in `<trace>.hoverlabel`.

Diff for: doc/python/line-and-scatter.md

@@ -6,7 +6,7 @@ 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 (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 scatter plots in Python with Plotly.
     display_as: basic
@@ -426,6 +426,48 @@ fig = go.Figure(data=go.Scatter(
 fig.show()
 ```
 
+#### Trace Zorder
+
+*New in 5.21*
+
+For many trace types, including `go.Scatter`, you can define the order traces are drawn in by setting a `zorder`. Traces with a higher `zorder` appear at the front, with traces with a lower `zorder` at the back. In this example, we give our trace for 'France' the highest `zorder`, meaning it is drawn in front of the other two traces:
+
+```python
+import plotly.graph_objects as go
+import plotly.data as data
+
+df = data.gapminder()
+
+df_europe = df[df['continent'] == 'Europe']
+
+trace1 = go.Scatter(x=df_europe[df_europe['country'] == 'France']['year'], 
+                    y=df_europe[df_europe['country'] == 'France']['lifeExp'], 
+                    mode='lines+markers', 
+                    zorder=3,
+                    name='France',
+                    marker=dict(size=15))
+
+trace2 = go.Scatter(x=df_europe[df_europe['country'] == 'Germany']['year'], 
+                    y=df_europe[df_europe['country'] == 'Germany']['lifeExp'], 
+                    mode='lines+markers',
+                    zorder=1,
+                    name='Germany',
+                    marker=dict(size=15))
+
+trace3 = go.Scatter(x=df_europe[df_europe['country'] == 'Spain']['year'], 
+                    y=df_europe[df_europe['country'] == 'Spain']['lifeExp'], 
+                    mode='lines+markers',
+                    zorder=2,
+                    name='Spain',
+                    marker=dict(size=15))
+
+layout = go.Layout(title='Life Expectancy in Europe Over Time')
+
+fig = go.Figure(data=[trace1, trace2, trace3], layout=layout)
+
+fig.show()
+```
+
 #### Large Data Sets
 
 Now in Plotly you can implement WebGL with `Scattergl()` in place of `Scatter()` <br>

Diff for: doc/python/shapes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.6
+      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.10
+    version: 3.10.11
   plotly:
     description: How to make SVG shapes in python. Examples of lines, circle, rectangle,
       and path.
@@ -1105,5 +1105,58 @@ fig.show(
 )
 ```
 
+#### Shape Layer
+
+By default, shapes are drawn above traces. You can also configure them to be drawn between traces and gridlines with `layer="between"` (new in 5.21), or below gridlines with `layer="below"`.
+
+```python
+import plotly.express as px
+
+df = px.data.stocks(indexed=True)
+
+fig = px.line(df)
+
+fig.add_shape(
+    type="rect",
+    x0="2018-03-01",
+    y0=0,
+    x1="2018-08-01",
+    y1=3,
+    line_width=0,
+    layer="above",
+    label=dict(text="Above", textposition="top center", font=dict(size=15)),
+    fillcolor="LightGreen",
+    opacity=0.80,
+)
+
+fig.add_shape(
+    type="rect",
+    x0="2018-10-01",
+    y0=0,
+    x1="2019-03-01",
+    y1=3,
+    line_width=0,
+    layer="between",
+    label=dict(text="Between", textposition="top center", font=dict(size=15)),
+    fillcolor="LightGreen",
+    opacity=0.80,
+)
+
+fig.add_shape(
+    type="rect",
+    x0="2019-05-01",
+    y0=0,
+    x1="2019-10-01",
+    y1=3,
+    line_width=0,
+    layer="below",
+    label=dict(text="Below", textposition="top center", font=dict(size=15)),
+    fillcolor="LightGreen",
+    opacity=0.80,
+)
+
+fig.show()
+```
+
 ### Reference
 See https://plotly.com/python/reference/layout/shapes/ for more information and chart attribute options!