From 0aeef484f9b1ffc74840cbe45b48fbced1fc9b39 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Wed, 19 May 2021 13:31:19 +0200 Subject: [PATCH 1/5] redocument styler subset --- pandas/io/formats/style.py | 85 ++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 30 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index a96196a698f43..1c1e54714014b 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -1,5 +1,14 @@ """ Module for applying conditional formatting to DataFrames and Series. + +.. |subset_doc| replace:: 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. + +.. |subset_doc_1d| replace:: A valid 1d input or single key along the appropriate + axis within `DataFrame.loc[]`, to limit ``data`` to + *before* applying the function. """ from __future__ import annotations @@ -614,9 +623,8 @@ 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 : key, array-like, IndexSlice + |subset_doc| **kwargs : dict Pass along to ``func``. @@ -642,10 +650,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 +693,8 @@ 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 : key, array-like, IndexSlice + |subset_doc| **kwargs : dict Pass along to ``func``. @@ -699,8 +716,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 +759,8 @@ 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 + |subset_doc| **kwargs : dict Pass along to ``cond``. @@ -1072,9 +1098,8 @@ 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 + |subset_doc_1d| Returns ------- @@ -1127,8 +1152,8 @@ 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 + |subset_doc| 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,8 @@ 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 + |subset_doc| **kwargs : dict A dictionary of property, value pairs to be set for each cell. @@ -1349,8 +1374,8 @@ def bar( Parameters ---------- - subset : IndexSlice, optional - A valid slice for `data` to limit the style application to. + subset : label, array-like, IndexSlice + |subset_doc|. 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 +1456,8 @@ 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 + |subset_doc| .. versionadded:: 1.1.0 @@ -1477,8 +1502,8 @@ def highlight_max( Parameters ---------- - subset : IndexSlice, default None - A valid slice for ``data`` to limit the style application to. + subset : label, array-like, IndexSlice + |subset_doc| color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 @@ -1526,8 +1551,8 @@ def highlight_min( Parameters ---------- - subset : IndexSlice, default None - A valid slice for ``data`` to limit the style application to. + subset : label, array-like, IndexSlice + |subset_doc| color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 @@ -1580,8 +1605,8 @@ def highlight_between( Parameters ---------- - subset : IndexSlice, default None - A valid slice for ``data`` to limit the style application to. + subset : label, array-like, IndexSlice + |subset_doc| color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 @@ -1688,8 +1713,8 @@ def highlight_quantile( Parameters ---------- - subset : IndexSlice, default None - A valid slice for ``data`` to limit the style application to. + subset : label, array-like, IndexSlice + |subset_doc| color : str, default 'yellow' Background color to use for highlighting axis : {0 or 'index', 1 or 'columns', None}, default 0 From add8759809aa771819f3070f2f862ec175a285f0 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Wed, 19 May 2021 13:37:07 +0200 Subject: [PATCH 2/5] optional --- pandas/io/formats/style.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 1c1e54714014b..205e1c9b2d16d 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -623,7 +623,7 @@ 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 : key, array-like, IndexSlice + subset : key, array-like, IndexSlice, optional |subset_doc| **kwargs : dict Pass along to ``func``. @@ -693,7 +693,7 @@ def applymap( ---------- func : function ``func`` should take a scalar and return a scalar. - subset : key, array-like, IndexSlice + subset : key, array-like, IndexSlice, optional |subset_doc| **kwargs : dict Pass along to ``func``. @@ -759,7 +759,7 @@ def where( Applied when ``cond`` returns true. other : str Applied when ``cond`` returns false. - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| **kwargs : dict Pass along to ``cond``. @@ -1152,7 +1152,7 @@ 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 : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| text_color_threshold : float or int Luminance threshold for determining text color in [0, 1]. Facilitates text @@ -1276,7 +1276,7 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler: Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| **kwargs : dict A dictionary of property, value pairs to be set for each cell. @@ -1374,7 +1374,7 @@ def bar( Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc|. axis : {0 or 'index', 1 or 'columns', None}, default 0 Apply to each column (``axis=0`` or ``'index'``), to each row @@ -1456,7 +1456,7 @@ def highlight_null( Parameters ---------- null_color : str, default 'red' - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| .. versionadded:: 1.1.0 @@ -1502,7 +1502,7 @@ def highlight_max( Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| color : str, default 'yellow' Background color to use for highlighting. @@ -1551,7 +1551,7 @@ def highlight_min( Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| color : str, default 'yellow' Background color to use for highlighting. @@ -1605,7 +1605,7 @@ def highlight_between( Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| color : str, default 'yellow' Background color to use for highlighting. @@ -1713,7 +1713,7 @@ def highlight_quantile( Parameters ---------- - subset : label, array-like, IndexSlice + subset : label, array-like, IndexSlice, optional |subset_doc| color : str, default 'yellow' Background color to use for highlighting From 18b3dbb06c8b58651cf4b161839f6a846bebbf77 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Wed, 19 May 2021 13:39:27 +0200 Subject: [PATCH 3/5] format method also --- pandas/io/formats/style_render.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pandas/io/formats/style_render.py b/pandas/io/formats/style_render.py index 6f7d298c7dec0..a55dd1d2f61de 100644 --- a/pandas/io/formats/style_render.py +++ b/pandas/io/formats/style_render.py @@ -417,9 +417,11 @@ 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. From 4f5d2718394a9b0f9548bf511ebc152ebee451c0 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Thu, 20 May 2021 09:12:30 +0200 Subject: [PATCH 4/5] no subs docstrings --- pandas/io/formats/style.py | 56 +++++++++++++++++++------------ pandas/io/formats/style_render.py | 7 ++-- 2 files changed, 38 insertions(+), 25 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 205e1c9b2d16d..c5aad6235f06f 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -1,14 +1,5 @@ """ Module for applying conditional formatting to DataFrames and Series. - -.. |subset_doc| replace:: 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. - -.. |subset_doc_1d| replace:: A valid 1d input or single key along the appropriate - axis within `DataFrame.loc[]`, to limit ``data`` to - *before* applying the function. """ from __future__ import annotations @@ -624,7 +615,9 @@ def apply( (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. subset : key, array-like, IndexSlice, optional - |subset_doc| + 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``. @@ -694,7 +687,9 @@ def applymap( func : function ``func`` should take a scalar and return a scalar. subset : key, array-like, IndexSlice, optional - |subset_doc| + 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``. @@ -760,7 +755,9 @@ def where( other : str Applied when ``cond`` returns false. subset : label, array-like, IndexSlice, optional - |subset_doc| + 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``. @@ -1099,7 +1096,8 @@ def hide_columns(self, subset: Subset) -> Styler: Parameters ---------- subset : label, array-like, IndexSlice - |subset_doc_1d| + A valid 1d input or single key along the appropriate axis within + `DataFrame.loc[]`, to limit ``data`` to *before* applying the function. Returns ------- @@ -1153,7 +1151,9 @@ def background_gradient( (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 @@ -1277,7 +1277,9 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler: Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc| + 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. @@ -1375,7 +1377,9 @@ def bar( Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc|. + 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 @@ -1457,7 +1461,9 @@ def highlight_null( ---------- null_color : str, default 'red' subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 @@ -1503,7 +1509,9 @@ def highlight_max( Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 @@ -1552,7 +1560,9 @@ def highlight_min( Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 @@ -1606,7 +1616,9 @@ def highlight_between( Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 @@ -1714,7 +1726,9 @@ def highlight_quantile( Parameters ---------- subset : label, array-like, IndexSlice, optional - |subset_doc| + 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 a55dd1d2f61de..1d45e30e64d7c 100644 --- a/pandas/io/formats/style_render.py +++ b/pandas/io/formats/style_render.py @@ -418,10 +418,9 @@ def format( formatter : str, callable, dict or None Object to define how values are displayed. See notes. 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. + 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. From ce5e79343a9d60de5da5823e95a78e286b7de54c Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Thu, 20 May 2021 09:15:21 +0200 Subject: [PATCH 5/5] no subs docstrings --- pandas/io/formats/style.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index c5aad6235f06f..3a83d50884017 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -614,7 +614,7 @@ 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 : key, array-like, IndexSlice, optional + 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. @@ -686,7 +686,7 @@ def applymap( ---------- func : function ``func`` should take a scalar and return a scalar. - subset : key, array-like, IndexSlice, optional + 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.