ENH: allow concat of Styler objects

doc/source/reference/style.rst

@@ -42,6 +42,7 @@ Style application
    Styler.format
    Styler.format_index
    Styler.hide
+   Styler.set_footer
    Styler.set_td_classes
    Styler.set_table_styles
    Styler.set_table_attributes

doc/source/whatsnew/v1.5.0.rst

@@ -21,6 +21,7 @@ Styler
 
   - New method :meth:`.Styler.to_string` for alternative customisable output methods (:issue:`44502`)
   - Added the ability to render ``border`` and ``border-{side}`` CSS properties in Excel (:issue:`42276`)
+  - Added a new method :meth:`.Styler.set_footer` which allows adding customised footer rows to explore and make calculations on the data, e.g. totals and counts etc. (:issue:`43875`)
 
 .. _whatsnew_150.enhancements.enhancement2:
 

pandas/io/formats/style.py

@@ -1435,6 +1435,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 +1978,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 for use with ``set_footer``.
+
         Returns
         -------
         styles : dict
@@ -1995,9 +1999,10 @@ def export(self) -> dict[str, Any]:
         The following items are exported since they are not generally data dependent:
 
           - Styling functions added by the ``apply`` and ``applymap``
-          - Whether axes and names are hidden from the display, if unambiguous.
+          - Whether axes and names are hidden from the display, if unambiguous
           - Table attributes
           - Table styles
+          - Descriptors, i.e. from ``set_footer``
 
         The following attributes are considered data dependent and therefore not
         exported:
@@ -2027,6 +2032,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 +2041,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 for use with ``set_footer``.
+
         Parameters
         ----------
         styles : dict(str, Any)
@@ -2052,6 +2061,7 @@ 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_footer``.
 
         Returns
         -------
@@ -2094,6 +2104,12 @@ 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") and styles["descriptors"]["methods"]:
+            self.set_footer(
+                func=styles["descriptors"]["methods"],
+                alias=styles["descriptors"]["names"],
+                errors=styles["descriptors"]["errors"],
+            )
         return self
 
     def set_uuid(self, uuid: str) -> Styler:
@@ -2352,7 +2368,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 +2442,80 @@ def set_table_styles(
             self.table_styles = table_styles
         return self
 
+    def set_footer(
+        self,
+        func: Sequence[str | Callable] | None = None,
+        alias: Sequence[str] | None = None,
+        errors: str = "ignore",
+    ) -> Styler:
+        """
+        Add footer-level calculations to the output which describes the data.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        func : list-like of str or 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.
+        alias : list-like of str, optional
+            Aliases to use for the function names. Must have length equal to ``func``.
+        errors : {"ignore", "warn", "raise"}
+            If errors, will be ignored or warned returning ``NA``, or raise.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        These metrics are calculated at render time and can therefore be exported
+        and used on other general Styler objects.
+
+        Footers are applied to Styler output formats including ``to_html``,
+        ``to_latex`` and ``to_string``, but not, currently, ``to_excel``.
+
+        Examples
+        --------
+        A common use case is adding totals rows for descriptive tables, with ``func``.
+
+        >>> df = DataFrame([[4, 6], [1, 9], [3, 4], [5, 5], [9,6]],
+        ...                columns=["Mike", "Jim"],
+        ...                index=["Mon", "Tue", "Wed", "Thurs", "Fri"])
+        >>> styler = df.style.set_footer(["sum"])  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/footer_simple.png
+
+        User defined functions and an ``alias`` can also be used, which is useful for
+        displaying metrics such as dtypes, missing value counts, or unique value
+        counts etc.
+
+        >>> def reject_h0(s):
+        ...     count = (s > 0.8).sum()
+        ...     return "Reject" if count > 3 else "Accept"
+        >>> df = DataFrame({
+        ...          "Machine 1": np.random.rand(10),
+        ...          "Machine 2": np.random.rand(10),
+        ...          "Machine 3": np.random.rand(10),
+        ... })
+        >>> df.style.highlight_between(left=0.8, props="color: red;")
+        ...         .set_footer(func=[reject_h0],
+        ...                     alias=["Hypothesis Test:"])  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/footer_hypothesis.png
+        """
+        if func is not None:
+            if alias is not None and len(alias) != len(func):
+                raise ValueError("``alias`` must have same length as ``func``")
+
+        self.descriptors = {
+            "methods": func,
+            "names": alias,
+            "errors": errors,
+        }
+        return self
+
     def set_na_rep(self, na_rep: str) -> StylerRenderer:
         """
         Set the missing data representation on a ``Styler``.