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: