Merge pull request #4557 from rl-utility-man/patch-5

Update hover-text-and-formatting.md

doc/python/hover-text-and-formatting.md

@@ -283,6 +283,58 @@ print("user_defined hovertemplate:", fig.data[0].hovertemplate)
 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. 
+
+```python
+# %%
+import plotly.graph_objects as go
+import plotly.express as px
+import pandas as pd
+import math
+import numpy as np
+
+data = px.data.gapminder()
+df = data[data['year']==2007]
+df = df.sort_values(['continent', 'country'])
+
+df.rename(columns={"gdpPercap":'GDP per capita', "lifeExp":'Life Expectancy (years)'}, inplace=True)
+
+fig=px.scatter(df, 
+               x='GDP per capita',
+               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'], 
+)
+
+# 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 = 
+                "<b>%{customdata[0]}</b><br>" +
+                "<b>%{customdata[1]}</b><br><br>" +
+                "GDP per Capita: %{x:$,.0f}<br>" +
+                "Life Expectation: %{y:.0f}<br>" +
+                "Population: %{customdata[2]:,.0f}" +
+                "<extra></extra>",
+    mode='markers',
+    marker={'sizemode':'area',
+            'sizeref':10},
+)
+
+fig.update_layout(
+        xaxis={
+            'type':'log'},
+        )
+
+fig.show()
+```
+
+
 ### Hover Templates with Mixtures of Period data
 
 *New in v5.0*
@@ -319,7 +371,7 @@ fig.show()
 
 ### Advanced Hover Template
 
-The following example shows how to format a 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`.  
 
 ```python
 import plotly.graph_objects as go
@@ -343,21 +395,31 @@ continent_data = {continent:df_2007.query("continent == '%s'" %continent)
 
 fig = go.Figure()
 
-for continent_name, continent in continent_data.items():
-    fig.add_trace(go.Scatter(
-        x=continent['gdpPercap'],
-        y=continent['lifeExp'],
-        name=continent_name,
-        text=continent['continent'],
-        hovertemplate=
-        "<b>%{text}</b><br><br>" +
-        "GDP per Capita: %{x:$,.0f}<br>" +
-        "Life Expectation: %{y:.0%}<br>" +
-        "Population: %{marker.size:,}" +
-        "<extra></extra>",
-        marker_size=continent['size'],
+for continent_name, df in continent_data.items():
+    fig.add_trace(
+        go.Scatter(
+            x=df['gdpPercap'],
+            y=df['lifeExp'],
+            marker_size=df['size'],
+            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, 
+            # we could instead add continent as a third customdata field.
+            customdata=df[['country','pop']],  
+            hovertemplate=
+                "<b>%{customdata[0]}</b><br>" +
+                "<b>%{text}</b><br><br>" +
+                "GDP per Capita: %{x:$,.0f}<br>" +
+                "Life Expectancy: %{y:.0f}<br>" +
+                "Population: %{customdata[1]:,.0f}" +
+                "<extra></extra>",
         ))
 
+
 fig.update_traces(
     mode='markers',
     marker={'sizemode':'area',