diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index a96196a698f43..3a83d50884017 100644 --- a/pandas/io/formats/style.py +++ b/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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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 diff --git a/pandas/io/formats/style_render.py b/pandas/io/formats/style_render.py index 6f7d298c7dec0..1d45e30e64d7c 100644 --- a/pandas/io/formats/style_render.py +++ b/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[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` 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.