doc, more tests

Author: emmanuelle

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

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.1
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.3
   plotly:
     description: How to use hover text and formatting in Python with Plotly.
     display_as: file_settings
@@ -102,7 +102,7 @@ fig.show()
 
 ### Customizing Hover text with Plotly Express
 
-Plotly Express functions automatically add all the data being plotted (x, y, color etc) to the hover label. Many Plotly Express functions also support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip. The `hover_name` property controls which column is displayed in bold as the tooltip title.
+Plotly Express functions automatically add all the data being plotted (x, y, color etc) to the hover label. Many Plotly Express functions also support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip, or a dictionary for advanced formatting (see the next section). The `hover_name` property controls which column is displayed in bold as the tooltip title.
 
 Here is an example that creates a scatter plot using Plotly Express with custom hover data and a custom hover name.
 
@@ -117,6 +117,35 @@ fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True,
 fig.show()
 ```
 
+### Disabling or customizing hover of columns in plotly express
+
+`hover_data` can also be a dictionary. Its keys are existing columns of the `dataframe` argument, or new labels. For an existing column, the values can be
+* `False` to remove the column from the hover data (for example, if one wishes to remove the column of the `x` argument)
+* `True` to add a different column, with default formatting
+* a formatting string starting with `:` for numbers [d3-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#d3_forma), and `|` for dates in [d3-time-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md#format), for example `:.3f`, `|%a`.
+
+For passing new data, the value is a tuple, which first element is one of the possible values described above for existing columns, and the second element correspond to the hover values, for example `(True, [1, 2, 3])` or `(':.1f', [1.54, 2.345])`.
+
+These different cases are illustrated in the following example.
+
+```python
+import plotly.express as px
+import numpy as np
+df = px.data.iris()
+fig = px.scatter(df, x='petal_length', y='sepal_length', facet_col='species', color='species',
+                 hover_data={'species':False, # remove species from hover data
+                             'sepal_length':':.2f', # customize hover for column of y attribute
+                             'petal_width':True, # add other column, default formatting
+                             'sepal_width':':.2f', # add other column, customized formatting
+                             # data not in dataframe, default formatting
+                             'suppl_1': (True, np.random.random(len(df))),
+                             # data not in dataframe, customized formatting
+                             'suppl_2': (':.3f', np.random.random(len(df)))
+                            })
+fig.update_layout(height=300)
+fig.show()
+```
+
 ### Customizing hover text with a hovertemplate
 
 To customize the tooltip on your graph you can use [hovertemplate](https://plotly.com/python/reference/#pie-hovertemplate), which is a template string used for rendering the information that appear on hoverbox.

packages/python/plotly/plotly/express/_core.py

@@ -985,7 +985,7 @@ def build_dataframe(args, attrables, array_attrables):
                 bypass_warnings = (
                     hover_data_is_dict
                     and argument in args["hover_data"]
-                    and args["hover_data"][argument][1]
+                    and args["hover_data"][argument][1] is not None
                 )
                 if not df_provided and not bypass_warnings:
                     raise ValueError(
@@ -1022,7 +1022,7 @@ def build_dataframe(args, attrables, array_attrables):
                 if (
                     field_name == "hover_data"
                     and hover_data_is_dict
-                    and args["hover_data"][col_name][1]
+                    and args["hover_data"][col_name][1] is not None
                 ):
                     df_output[col_name] = args["hover_data"][col_name][1]
                 else:

packages/python/plotly/plotly/express/_doc.py

@@ -185,7 +185,9 @@
         "or array_like objects",
         "or a dict with column names as keys, with values True (for default formatting)",
         "False (in order to remove this column from hover information),",
-        "or a formatting string, for example ':.3f' or '|%a'."
+        "or a formatting string, for example ':.3f' or '|%a'",
+        "or tuples with a bool or formatting string as first element,",
+        "and list-like data to appear in hover as second element",
         "Values from these columns appear as extra data in the hover tooltip.",
     ],
     custom_data=[

packages/python/plotly/plotly/tests/test_core/test_px/test_px_hover.py

@@ -20,7 +20,9 @@ def test_skip_hover():
 
 def test_composite_hover():
     df = px.data.tips()
-    hover_dict = OrderedDict({"day": False, "sex": True, "total_bill": ":.1f"})
+    hover_dict = OrderedDict(
+        {"day": False, "time": False, "sex": True, "total_bill": ":.1f"}
+    )
     fig = px.scatter(
         df,
         x="tip",
@@ -29,12 +31,11 @@ def test_composite_hover():
         facet_row="time",
         hover_data=hover_dict,
     )
-    assert (
-        fig.data[0].hovertemplate
-        == "time=Dinner<br>tip=%{x}<br>total_bill=%{customdata[2]:.1f}<br>sex=%{customdata[1]}<extra></extra>"
-        or fig.data[0].hovertemplate
-        == "time=Dinner<br>tip=%{x}<br>total_bill=%{customdata[1]:.1f}<br>sex=%{customdata[0]}<extra></extra>"
-    )
+    for el in ["tip", "total_bill", "sex"]:
+        assert el in fig.data[0].hovertemplate
+    for el in ["day", "time"]:
+        assert el not in fig.data[0].hovertemplate
+    assert ":.1f" in fig.data[0].hovertemplate
 
 
 def test_tuple_hover_data():
@@ -45,12 +46,38 @@ def test_tuple_hover_data():
         fig.data[0].hovertemplate
         == "x=%{x}<br>y=%{y}<br>comment=%{customdata[0]}<extra></extra>"
     )
-    fig = px.scatter(
-        x=[1, 2, 3],
-        y=[3, 4, 5],
-        hover_data={"comment": (":.1f", [1.234, 45.3455, 5666.234])},
-    )
-    assert (
-        fig.data[0].hovertemplate
-        == "x=%{x}<br>y=%{y}<br>comment=%{customdata[0]:.1f}<extra></extra>"
-    )
+    hover_dicts = [
+        {"comment": (":.1f", [1.234, 45.3455, 5666.234])},
+        {"comment": (":.1f", np.array([1.234, 45.3455, 5666.234]))},
+        {"comment": (":.1f", pd.Series([1.234, 45.3455, 5666.234]))},
+    ]
+    for hover_dict in hover_dicts:
+        fig = px.scatter(x=[1, 2, 3], y=[3, 4, 5], hover_data=hover_dict,)
+        assert (
+            fig.data[0].hovertemplate
+            == "x=%{x}<br>y=%{y}<br>comment=%{customdata[0]:.1f}<extra></extra>"
+        )
+
+
+def test_fail_wrong_column():
+    with pytest.raises(ValueError):
+        fig = px.scatter(
+            {"a": [1, 2], "b": [3, 4], "c": [2, 1]},
+            x="a",
+            y="b",
+            hover_data={"d": True},
+        )
+    with pytest.raises(ValueError):
+        fig = px.scatter(
+            {"a": [1, 2], "b": [3, 4], "c": [2, 1]},
+            x="a",
+            y="b",
+            hover_data={"d": ":.1f"},
+        )
+    with pytest.raises(ValueError):
+        fig = px.scatter(
+            {"a": [1, 2], "b": [3, 4], "c": [2, 1]},
+            x="a",
+            y="b",
+            hover_data={"d": (True, [3, 4, 5])},
+        )