add hoversubplots examples

Author: LiamConnors

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,38 @@ 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`. In the following example, the three stacked scatter plots use the same `xaxis`:
+
+```python
+import plotly.graph_objects as go
+import pandas as pd
+from plotly import data
+
+df = data.stocks()
+
+date_range = pd.date_range(start="1/1/2020", end="1/10/2020")
+
+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`.

doc/python/splom.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.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.6.7
+    version: 3.10.11
   plotly:
     description: How to make scatterplot matrices or sploms natively in Python with
       Plotly.
@@ -77,7 +77,6 @@ fig.update_traces(diagonal_visible=False)
 fig.show()
 ```
 
-<!-- #region -->
 
 ### Scatter matrix (splom) with go.Splom
 
@@ -103,7 +102,7 @@ trace=go.Splom(dimensions=[dict(label='string-1',
 
 The label in each dimension is assigned to the axes titles of the corresponding matrix cell.
 
-<!-- #endregion -->
+
 
 #### Splom of the Iris data set
 
@@ -290,6 +289,55 @@ fig.update_layout(title=title,
 
 fig.show()
 ```
+#### Hover Effects
+
+*New in 5.21*
+
+Set `hoversubplots='axis'` with `hovermode` set to `x`, `x unified`, `y`, or `y unified` for hover effects to appear across a column or row.
+
+For more on hover effects see the [Hover Text and Formatting](/python/hover-text-and-formatting/) page.
+
+```python
+import plotly.graph_objects as go
+import pandas as pd
+
+df = pd.read_csv(
+    "https://raw.githubusercontent.com/plotly/datasets/master/iris-data.csv"
+)
+index_vals = df["class"].astype("category").cat.codes
+
+fig = go.Figure(
+    data=go.Splom(
+        dimensions=[
+            dict(label="sepal length", values=df["sepal length"]),
+            dict(label="sepal width", values=df["sepal width"]),
+            dict(label="petal length", values=df["petal length"]),
+            dict(label="petal width", values=df["petal width"]),
+        ],
+        showupperhalf=False,
+        text=df["class"],
+        marker=dict(
+            color=index_vals,
+            showscale=False,
+            line_color="white",
+            line_width=0.5,
+        ),
+    )
+)
+
+
+fig.update_layout(
+    title="Iris Data set",
+    hoversubplots="axis",
+    width=600,
+    height=600,
+    hovermode="x",
+)
+
+fig.show()
+
+```
+
 #### Reference
 
 See [function reference for `px.scatter_matrix()`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_matrix) or https://plotly.com/python/reference/splom/ for more information and chart attribute options!