ENH: Styler tooltips feature

doc/source/whatsnew/v1.2.0.rst

@@ -118,6 +118,7 @@ Other enhancements
 - :class:`Index` with object dtype supports division and multiplication (:issue:`34160`)
 - :meth:`DataFrame.explode` and :meth:`Series.explode` now support exploding of sets (:issue:`35614`)
 - ``Styler`` now allows direct CSS class name addition to individual data cells (:issue:`36159`)
+- ``Styler`` now has the ability to add tooltips to styled dataframes from strings (:issue:`35643`)
 - :meth:`Rolling.mean()` and :meth:`Rolling.sum()` use Kahan summation to calculate the mean to avoid numerical problems (:issue:`10319`, :issue:`11645`, :issue:`13254`, :issue:`32761`, :issue:`36031`)
 - :meth:`DatetimeIndex.searchsorted`, :meth:`TimedeltaIndex.searchsorted`, :meth:`PeriodIndex.searchsorted`, and :meth:`Series.searchsorted` with datetimelike dtypes will now try to cast string arguments (listlike and scalar) to the matching datetimelike type (:issue:`36346`)
 

pandas/io/formats/style.py

@@ -181,6 +181,8 @@ def __init__(
         self.cell_ids = cell_ids
         self.na_rep = na_rep
 
+        self.tooltips = _Tooltips()
+
         self.cell_context: Dict[str, Any] = {}
 
         # display_funcs maps (row, col) -> formatting function
@@ -204,6 +206,101 @@ def _repr_html_(self) -> str:
         """
         return self.render()
 
+    def set_tooltips(self, ttips: DataFrame) -> "Styler":
+        """
+        Add string based tooltips that will appear in the `Styler` HTML result. These
+        tooltips are applicable only to`<td>` elements.
+
+        Parameters
+        ----------
+        ttips : DataFrame
+            DataFrame containing strings that will be translated to tooltips, mapped
+            by identical column and index values that must exist on the underlying
+            `Styler` data. None, NaN values, and empty strings will be ignored and
+            not affect the rendered HTML.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        Tooltips are created by adding `<span class="pd-t"></span>` to each data cell
+        and then manipulating the table level CSS to attach pseudo hover and pseudo
+        after selectors to produce the required the results. For styling control
+        see `:meth:Styler.set_tooltips_class`.
+        Tooltips are not designed to be efficient, and can add large amounts of
+        additional HTML for larger tables, since they also require that `cell_ids`
+        is forced to `True`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        >>> ttips = pd.DataFrame(
+        ...    data=[["Min", ""], [np.nan, "Max"]], columns=df.columns, index=df.index
+        ... )
+        >>> s = df.style.set_tooltips(ttips).render()
+        """
+        if not self.cell_ids:
+            # tooltips not optimised for individual cell check.
+            raise NotImplementedError(
+                "Tooltips can only render with 'cell_ids' is True."
+            )
+        self.tooltips.tt_data = ttips
+        return self
+
+    def set_tooltips_class(
+        self,
+        name: Optional[str] = None,
+        properties: Optional[Sequence[Tuple[str, Union[str, int, float]]]] = None,
+    ) -> "Styler":
+        """
+        Manually configure the name and/or properties of the class for
+        creating tooltips on hover.
+
+        Parameters
+        ----------
+        name : str, default None
+            Name of the tooltip class used in CSS, should conform to HTML standards.
+        properties : list-like, default None
+            List of (attr, value) tuples; see example.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        If arguments are `None` will not make any changes to the underlying ``Tooltips``
+        existing values.
+
+        The default properties for the tooltip CSS class are:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+        The property ('visibility', 'hidden') is a key prerequisite to the hover
+        functionality, and should always be included in any manual properties
+        specification.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.random.randn(10, 4))
+        >>> df.style.set_tooltips_class(name='tt-add', properties=[
+        ...     ('visibility', 'hidden'),
+        ...     ('position', 'absolute'),
+        ...     ('z-index', 1)])
+        """
+        if properties:
+            self.tooltips.class_properties = properties
+        if name:
+            self.tooltips.class_name = name
+        return self
+
     @doc(NDFrame.to_excel, klass="Styler")
     def to_excel(
         self,
@@ -616,6 +713,7 @@ def render(self, **kwargs) -> str:
         self._compute()
         # TODO: namespace all the pandas keys
         d = self._translate()
+        d = self.tooltips._translate_tooltips(self.data, self.uuid, d)
         # filter out empty styles, every cell will have a class
         # but the list of props may just be [['', '']].
         # so we have the nested anys below
@@ -685,6 +783,7 @@ def clear(self) -> None:
         Returns None.
         """
         self.ctx.clear()
+        self.tooltips = _Tooltips()
         self.cell_context = {}
         self._todo = []
 
@@ -1589,6 +1688,170 @@ def pipe(self, func: Callable, *args, **kwargs):
         return com.pipe(self, func, *args, **kwargs)
 
 
+class _Tooltips:
+    """
+    An extension to ``Styler`` that allows for and manipulates tooltips on hover
+    of table data-cells in the HTML result.
+
+    Parameters
+    ----------
+    css_name: str, default "pd-t"
+        Name of the CSS class that controls visualisation of tooltips.
+    css_props: list-like, default; see Notes
+        List of (attr, value) tuples defining properties of the CSS class.
+    tooltips: DataFrame, default empty
+        DataFrame of strings aligned with underlying ``Styler`` data for tooltip
+        display.
+
+    Notes
+    -----
+    The default properties for the tooltip CSS class are:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+    Hidden visibility is a key prerequisite to the hover functionality, and should
+    always be included in any manual properties specification.
+    """
+
+    def __init__(
+        self,
+        css_props: Sequence[Tuple[str, Union[str, int, float]]] = [
+            ("visibility", "hidden"),
+            ("position", "absolute"),
+            ("z-index", 1),
+            ("background-color", "black"),
+            ("color", "white"),
+            ("transform", "translate(-20px, -20px)"),
+        ],
+        css_name: str = "pd-t",
+        tooltips: DataFrame = DataFrame(),
+    ):
+        self.class_name = css_name
+        self.class_properties = css_props
+        self.tt_data = tooltips
+        self.table_styles: List[Dict[str, Union[str, List[Tuple[str, str]]]]] = []
+
+    @property
+    def _class_styles(self):
+        """
+        Combine the ``_Tooltips`` CSS class name and CSS properties to the format
+        required to extend the underlying ``Styler`` `table_styles` to allow
+        tooltips to render in HTML.
+
+        Returns
+        -------
+        styles : List
+        """
+        return [{"selector": f".{self.class_name}", "props": self.class_properties}]
+
+    def _translate_tooltips(self, styler_data, uuid, d):
+        """
+        Mutate the render dictionary to allow for tooltips:
+
+        - Add `<span>` HTML element to each data cells `display_value`. Ignores
+          headers.
+        - Add table level CSS styles to control pseudo classes.
+
+        Parameters
+        ----------
+        styler_data : DataFrame
+            Underlying ``Styler`` DataFrame used for reindexing.
+        uuid : str
+            The underlying ``Styler`` uuid for CSS id.
+        d : dict
+            The dictionary prior to final render
+        """
+        self.tt_data = (
+            self.tt_data.reindex_like(styler_data)
+            .dropna(how="all", axis=0)
+            .dropna(how="all", axis=1)
+        )
+        if self.tt_data.empty:
+            return d
+
+        name = self.class_name
+
+        def _pseudo_css(row: int, col: int, text: str):
+            """
+            For every table data-cell that has a valid tooltip (not None, NaN or
+            empty string) must create two pseudo CSS entries for the specific
+            <td> element id which are added to overall table styles:
+            an on hover visibility change and a content change
+            dependent upon the user's chosen display string.
+
+            For example:
+                [{"selector": "T__row1_col1:hover .pd-t",
+                 "props": [("visibility", "visible")]},
+                {"selector": "T__row1_col1 .pd-t::after",
+                 "props": [("content", "Some Valid Text String")]}]
+
+            Parameters
+            ----------
+            row : int
+                The row index of the specified tooltip string data
+            col : int
+                The col index of the specified tooltip string data
+            text : str
+                The textual content of the tooltip to be displayed in HTML.
+
+            Returns
+            -------
+            pseudo_css : List
+            """
+            return [
+                {
+                    "selector": "#T_"
+                    + uuid
+                    + "row"
+                    + str(row)
+                    + "_col"
+                    + str(col)
+                    + f":hover .{name}",
+                    "props": [("visibility", "visible")],
+                },
+                {
+                    "selector": "#T_"
+                    + uuid
+                    + "row"
+                    + str(row)
+                    + "_col"
+                    + str(col)
+                    + f" .{name}::after",
+                    "props": [("content", f'"{text}"')],
+                },
+            ]
+
+        mask = (self.tt_data.isna()) | (self.tt_data.eq(""))  # empty string = no ttip
+        self.table_styles = [
+            style
+            for sublist in [
+                _pseudo_css(i, j, str(self.tt_data.iloc[i, j]))
+                for i in range(len(self.tt_data.index))
+                for j in range(len(self.tt_data.columns))
+                if not mask.iloc[i, j]
+            ]
+            for style in sublist
+        ]
+
+        if self.table_styles:
+            for row in d["body"]:
+                for item in row:
+                    if item["type"] == "td":
+                        item["display_value"] = (
+                            str(item["display_value"])
+                            + f'<span class="{self.class_name}"></span>'
+                        )
+            d["table_styles"].extend(self._class_styles)
+            d["table_styles"].extend(self.table_styles)
+
+        return d
+
+
 def _is_visible(idx_row, idx_col, lengths) -> bool:
     """
     Index -> {(idx_row, idx_col): bool}).

pandas/tests/io/formats/test_style.py

@@ -1738,6 +1738,74 @@ def test_uuid_len_raises(self, len_):
         with pytest.raises(TypeError, match=msg):
             Styler(df, uuid_len=len_, cell_ids=False).render()
 
+    @pytest.mark.parametrize(
+        "ttips",
+        [
+            DataFrame(
+                data=[["Min", "Max"], [np.nan, ""]],
+                columns=["A", "B"],
+                index=["a", "b"],
+            ),
+            DataFrame(data=[["Max", "Min"]], columns=["B", "A"], index=["a"]),
+            DataFrame(
+                data=[["Min", "Max", None]], columns=["A", "B", "C"], index=["a"]
+            ),
+        ],
+    )
+    def test_tooltip_render(self, ttips):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 3], [1, 2]], columns=["A", "B"], index=["a", "b"])
+        s = Styler(df, uuid_len=0).set_tooltips(ttips).render()
+
+        # test tooltip table level class
+        assert "#T__ .pd-t {\n          visibility: hidden;\n" in s
+
+        # test 'Min' tooltip added
+        assert (
+            "#T__ #T__row0_col0:hover .pd-t {\n          visibility: visible;\n    }  "
+            + '  #T__ #T__row0_col0 .pd-t::after {\n          content: "Min";\n    }'
+            in s
+        )
+        assert (
+            '<td id="T__row0_col0" class="data row0 col0" >0<span class="pd-t">'
+            + "</span></td>"
+            in s
+        )
+
+        # test 'Max' tooltip added
+        assert (
+            "#T__ #T__row0_col1:hover .pd-t {\n          visibility: visible;\n    }  "
+            + '  #T__ #T__row0_col1 .pd-t::after {\n          content: "Max";\n    }'
+            in s
+        )
+        assert (
+            '<td id="T__row0_col1" class="data row0 col1" >3<span class="pd-t">'
+            + "</span></td>"
+            in s
+        )
+
+    def test_tooltip_ignored(self):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        s = Styler(df).set_tooltips_class("pd-t").render()  # no set_tooltips()
+        assert '<style  type="text/css" >\n</style>' in s
+        assert '<span class="pd-t"></span>' not in s
+
+    def test_tooltip_class(self):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        s = (
+            Styler(df, uuid_len=0)
+            .set_tooltips(DataFrame([["tooltip"]]))
+            .set_tooltips_class(name="other-class", properties=[("color", "green")])
+            .render()
+        )
+        assert "#T__ .other-class {\n          color: green;\n" in s
+        assert (
+            '#T__ #T__row0_col0 .other-class::after {\n          content: "tooltip";\n'
+            in s
+        )
+
 
 @td.skip_if_no_mpl
 class TestStylerMatplotlibDep: