ENH: Add custom descriptors (such as dtype, nunique, etc.) to Styler output

doc/source/reference/style.rst

@@ -45,6 +45,7 @@ Style application
    Styler.set_td_classes
    Styler.set_table_styles
    Styler.set_table_attributes
+   Styler.set_descriptors
    Styler.set_tooltips
    Styler.set_caption
    Styler.set_sticky

doc/source/user_guide/style.ipynb

@@ -216,6 +216,47 @@
     "weather_df.loc[\"2021-01-04\":\"2021-01-08\"].style.pipe(make_pretty)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Describing Data\n",
+    "\n",
+    "The data can also be explored with the ability to add header level calculations. The [.set_descriptors()][descriptors] method is used here. We begin with a large DataFrame and reconfigure the `pandas.options` to reduce the rendered size, whilst adding descriptors we wish to calculate on the data.\n",
+    "\n",
+    "[descriptors]: ../reference/api/pandas.io.formats.style.Styler.set_descriptors.rst"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pd.options.styler.render.max_rows = 5\n",
+    "df_described = pd.DataFrame({\"A\": np.random.randn(1000), \n",
+    "                   \"B\": np.random.randint(low=-10, high=10, size=1000, dtype=\"int64\")})\n",
+    "df_described.style.set_descriptors([\n",
+    "    \"mean\",\n",
+    "    (\"mean 2dp\", lambda s: f\"{s.mean():.2f}\"),\n",
+    "    (\"std\", pd.Series.std),\n",
+    "    \"nunique\",\n",
+    "    lambda s: s.dtype,\n",
+    "])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "# Hidden cell to reset pandas options \n",
+    "pd.options.styler.render.max_rows = None"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1661,6 +1702,7 @@
     "  + `col<n>`, where `n` is the numeric position of the cell.\n",
     "- Blank cells include `blank`\n",
     "- Trimmed cells include `col_trim` or `row_trim`\n",
+    "- Descriptor name cells include `descriptor_name`, descriptor value cells include `descriptor_value` and both also include `descriptor<j>`, where `j` is the numeric index of the list of descriptors.\n",
     "\n",
     "The structure of the `id` is `T_uuid_level<k>_row<m>_col<n>` where `level<k>` is used only on headings, and headings will only have either `row<m>` or `col<n>` whichever is needed. By default we've also prepended each row/column identifier with a UUID unique to each DataFrame so that the style from one doesn't collide with the styling from another within the same notebook or page. You can read more about the use of UUIDs in [Optimization](#Optimization).\n",
     "\n",
@@ -1675,7 +1717,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(pd.DataFrame([[1,2],[3,4]], index=['i1', 'i2'], columns=['c1', 'c2']).style.to_html())"
+    "print(pd.DataFrame([[1,2],[3,4]], index=['i1', 'i2'], columns=['c1', 'c2']).style.set_descriptors([\"mean\"]).to_html())"
    ]
   },
   {

doc/source/whatsnew/v1.5.0.rst

@@ -20,6 +20,7 @@ Styler
 ^^^^^^
 
   - New method :meth:`.Styler.to_string` for alternative customisable output methods (:issue:`44502`)
+  - Added a new method :meth:`.Styler.set_descriptors` which allows adding customised header rows to explore and make calculations on the data, e.g. totals and counts etc. (:issue:`43875`)
   - Various bug fixes, see below.
 
 .. _whatsnew_150.enhancements.enhancement2:

pandas/io/formats/style.py

@@ -54,6 +54,7 @@
 from pandas.io.formats.style_render import (
     CSSProperties,
     CSSStyles,
+    Descriptor,
     ExtFormatter,
     StylerRenderer,
     Subset,
@@ -1435,6 +1436,7 @@ def _copy(self, deepcopy: bool = False) -> Styler:
         ]
         deep = [  # nested lists or dicts
             "css",
+            "descriptors",
             "_display_funcs",
             "_display_funcs_index",
             "_display_funcs_columns",
@@ -1977,6 +1979,9 @@ def export(self) -> dict[str, Any]:
 
         Can be applied to a second Styler with ``Styler.use``.
 
+        .. versionchanged:: 1.5.0
+           Adds ``descriptors`` to the exported items.
+
         Returns
         -------
         styles : dict
@@ -1998,6 +2003,7 @@ def export(self) -> dict[str, Any]:
           - Whether axes and names are hidden from the display, if unambiguous.
           - Table attributes
           - Table styles
+          - Descriptors
 
         The following attributes are considered data dependent and therefore not
         exported:
@@ -2027,6 +2033,7 @@ def export(self) -> dict[str, Any]:
             "hide_index_names": self.hide_index_names,
             "hide_column_names": self.hide_column_names,
             "css": copy.copy(self.css),
+            "descriptors": copy.copy(self.descriptors),
         }
 
     def use(self, styles: dict[str, Any]) -> Styler:
@@ -2035,6 +2042,9 @@ def use(self, styles: dict[str, Any]) -> Styler:
 
         Possibly uses styles from ``Styler.export``.
 
+        .. versionchanged:: 1.5.0
+           Adds ``descriptors`` to the used items.
+
         Parameters
         ----------
         styles : dict(str, Any)
@@ -2052,6 +2062,8 @@ def use(self, styles: dict[str, Any]) -> Styler:
               - "hide_index_names": whether index names are hidden.
               - "hide_column_names": whether column header names are hidden.
               - "css": the css class names used.
+              - "descriptors": list of descriptors, typically added with
+                ``set_descriptors``.
 
         Returns
         -------
@@ -2094,6 +2106,8 @@ def use(self, styles: dict[str, Any]) -> Styler:
         self.hide_column_names = styles.get("hide_column_names", False)
         if styles.get("css"):
             self.css = styles.get("css")  # type: ignore[assignment]
+        if styles.get("descriptors"):
+            self.set_descriptors(styles.get("descriptors"))
         return self
 
     def set_uuid(self, uuid: str) -> Styler:
@@ -2352,7 +2366,10 @@ def set_table_styles(
                                "row_trim": "row_trim",
                                "level": "level",
                                "data": "data",
-                               "blank": "blank}
+                               "blank": "blank",
+                               "descriptor": "descriptor",
+                               "descriptor_name": "descriptor_name",
+                               "descriptor_value": "descriptor_value"}
 
         Examples
         --------
@@ -2423,6 +2440,50 @@ def set_table_styles(
             self.table_styles = table_styles
         return self
 
+    def set_descriptors(
+        self, descriptors: list[Descriptor | tuple[str, Descriptor]] | None = None
+    ) -> Styler:
+        """
+        Add header-level calculations to the output which describes the data.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        descriptors : list of str, callables or 2-tuples of str and callable
+            If a string is given must be a valid Series method, e.g. "mean" invokes
+            Series.mean().
+
+            If a callable is given must accept a Series and return a scalar.
+
+            If a 2-tuple, must be a string used as the name of the row and a
+            callable or string as above.
+
+        Returns
+        -------
+        self : Styler
+
+        Examples
+        --------
+
+        >>> df = DataFrame([[1, 2], [3, 4]], columns=["A", "B"])
+        >>> def udf_func(s):
+        ...     return s.mean()
+        >>> styler = df.style.set_descriptors([
+        ...     "mean",
+        ...     Series.mean,
+        ...     ("my-text", "mean"),
+        ...     ("my-text2", Series.mean),
+        ...     ("my-func", lambda s: s.sum()/2),
+        ...     lambda s: s.sum()/2,
+        ...     udf_func,
+        ... ])  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/des_mean.png
+        """
+        self.descriptors = descriptors if descriptors is not None else []
+        return self
+
     def set_na_rep(self, na_rep: str) -> StylerRenderer:
         """
         Set the missing data representation on a ``Styler``.