DOC: redocument the subset arg in styler for clarity of use (#41566)

Author: attack68

pandas/io/formats/style.py

@@ -614,9 +614,10 @@ def apply(
             Apply to each column (``axis=0`` or ``'index'``), to each row
             (``axis=1`` or ``'columns'``), or to the entire DataFrame at once
             with ``axis=None``.
-        subset : IndexSlice
-            A valid indexer to limit ``data`` to *before* applying the
-            function. Consider using a pandas.IndexSlice.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         **kwargs : dict
             Pass along to ``func``.
 
@@ -642,10 +643,20 @@ def apply(
         --------
         >>> def highlight_max(x, color):
         ...     return np.where(x == np.nanmax(x.to_numpy()), f"color: {color};", None)
-        >>> df = pd.DataFrame(np.random.randn(5, 2))
+        >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"])
         >>> df.style.apply(highlight_max, color='red')
         >>> df.style.apply(highlight_max, color='blue', axis=1)
         >>> df.style.apply(highlight_max, color='green', axis=None)
+
+        Using ``subset`` to restrict application to a single column or multiple columns
+
+        >>> df.style.apply(highlight_max, color='red', subset="A")
+        >>> df.style.apply(highlight_max, color='red', subset=["A", "B"])
+
+        Using a 2d input to ``subset`` to select rows in addition to columns
+
+        >>> df.style.apply(highlight_max, color='red', subset=([0,1,2], slice(None))
+        >>> df.style.apply(highlight_max, color='red', subset=(slice(0,5,2), "A")
         """
         self._todo.append(
             (lambda instance: getattr(instance, "_apply"), (func, axis, subset), kwargs)
@@ -675,9 +686,10 @@ def applymap(
         ----------
         func : function
             ``func`` should take a scalar and return a scalar.
-        subset : IndexSlice
-            A valid indexer to limit ``data`` to *before* applying the
-            function. Consider using a pandas.IndexSlice.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         **kwargs : dict
             Pass along to ``func``.
 
@@ -699,8 +711,18 @@ def applymap(
         --------
         >>> def color_negative(v, color):
         ...     return f"color: {color};" if v < 0 else None
-        >>> df = pd.DataFrame(np.random.randn(5, 2))
+        >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"])
         >>> df.style.applymap(color_negative, color='red')
+
+        Using ``subset`` to restrict application to a single column or multiple columns
+
+        >>> df.style.applymap(color_negative, color='red', subset="A")
+        >>> df.style.applymap(color_negative, color='red', subset=["A", "B"])
+
+        Using a 2d input to ``subset`` to select rows in addition to columns
+
+        >>> df.style.applymap(color_negative, color='red', subset=([0,1,2], slice(None))
+        >>> df.style.applymap(color_negative, color='red', subset=(slice(0,5,2), "A")
         """
         self._todo.append(
             (lambda instance: getattr(instance, "_applymap"), (func, subset), kwargs)
@@ -732,9 +754,10 @@ def where(
             Applied when ``cond`` returns true.
         other : str
             Applied when ``cond`` returns false.
-        subset : IndexSlice
-            A valid indexer to limit ``data`` to *before* applying the
-            function. Consider using a pandas.IndexSlice.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         **kwargs : dict
             Pass along to ``cond``.
 
@@ -1072,9 +1095,9 @@ def hide_columns(self, subset: Subset) -> Styler:
 
         Parameters
         ----------
-        subset : IndexSlice
-            An argument to ``DataFrame.loc`` that identifies which columns
-            are hidden.
+        subset : label, array-like, IndexSlice
+            A valid 1d input or single key along the appropriate axis within
+            `DataFrame.loc[]`, to limit ``data`` to *before* applying the function.
 
         Returns
         -------
@@ -1127,8 +1150,10 @@ def background_gradient(
             Apply to each column (``axis=0`` or ``'index'``), to each row
             (``axis=1`` or ``'columns'``), or to the entire DataFrame at once
             with ``axis=None``.
-        subset : IndexSlice
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         text_color_threshold : float or int
             Luminance threshold for determining text color in [0, 1]. Facilitates text
             visibility across varying background colors. All text is dark if 0, and
@@ -1251,8 +1276,10 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler:
 
         Parameters
         ----------
-        subset : IndexSlice
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         **kwargs : dict
             A dictionary of property, value pairs to be set for each cell.
 
@@ -1349,8 +1376,10 @@ def bar(
 
         Parameters
         ----------
-        subset : IndexSlice, optional
-            A valid slice for `data` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         axis : {0 or 'index', 1 or 'columns', None}, default 0
             Apply to each column (``axis=0`` or ``'index'``), to each row
             (``axis=1`` or ``'columns'``), or to the entire DataFrame at once
@@ -1431,8 +1460,10 @@ def highlight_null(
         Parameters
         ----------
         null_color : str, default 'red'
-        subset : label or list of labels, default None
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
 
             .. versionadded:: 1.1.0
 
@@ -1477,8 +1508,10 @@ def highlight_max(
 
         Parameters
         ----------
-        subset : IndexSlice, default None
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         color : str, default 'yellow'
             Background color to use for highlighting.
         axis : {0 or 'index', 1 or 'columns', None}, default 0
@@ -1526,8 +1559,10 @@ def highlight_min(
 
         Parameters
         ----------
-        subset : IndexSlice, default None
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         color : str, default 'yellow'
             Background color to use for highlighting.
         axis : {0 or 'index', 1 or 'columns', None}, default 0
@@ -1580,8 +1615,10 @@ def highlight_between(
 
         Parameters
         ----------
-        subset : IndexSlice, default None
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         color : str, default 'yellow'
             Background color to use for highlighting.
         axis : {0 or 'index', 1 or 'columns', None}, default 0
@@ -1688,8 +1725,10 @@ def highlight_quantile(
 
         Parameters
         ----------
-        subset : IndexSlice, default None
-            A valid slice for ``data`` to limit the style application to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         color : str, default 'yellow'
             Background color to use for highlighting
         axis : {0 or 'index', 1 or 'columns', None}, default 0

pandas/io/formats/style_render.py

@@ -417,9 +417,10 @@ def format(
         ----------
         formatter : str, callable, dict or None
             Object to define how values are displayed. See notes.
-        subset : IndexSlice
-            An argument to ``DataFrame.loc`` that restricts which elements
-            ``formatter`` is applied to.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, <subset>]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
         na_rep : str, optional
             Representation for missing values.
             If ``na_rep`` is None, no special formatting is applied.