ENH: Styler builtins: highlight_between

doc/source/reference/style.rst

@@ -53,6 +53,7 @@ Builtin styles
    Styler.highlight_null
    Styler.highlight_max
    Styler.highlight_min
+   Styler.highlight_between
    Styler.background_gradient
    Styler.bar
 

doc/source/whatsnew/v1.3.0.rst

@@ -136,6 +136,7 @@ Other enhancements
 - :meth:`.Styler.apply` now more consistently accepts ndarray function returns, i.e. in all cases for ``axis`` is ``0, 1 or None`` (:issue:`39359`)
 - :meth:`.Styler.apply` and :meth:`.Styler.applymap` now raise errors if wrong format CSS is passed on render (:issue:`39660`)
 - Builtin highlighting methods in :class:`Styler` have a more consistent signature and css customisability (:issue:`40242`)
+- :meth:`.Styler.highlight_between` added to list of builtin styling methods (:issue:`39821`)
 - :meth:`Series.loc.__getitem__` and :meth:`Series.loc.__setitem__` with :class:`MultiIndex` now raising helpful error message when indexer has too many dimensions (:issue:`35349`)
 - :meth:`pandas.read_stata` and :class:`StataReader` support reading data from compressed files.
 - Add support for parsing ``ISO 8601``-like timestamps with negative signs to :meth:`pandas.Timedelta` (:issue:`37172`)

pandas/io/formats/style.py

@@ -7,6 +7,7 @@
 from contextlib import contextmanager
 import copy
 from functools import partial
+import operator
 from typing import (
     Any,
     Callable,
@@ -33,6 +34,7 @@
     FrameOrSeries,
     FrameOrSeriesUnion,
     IndexLabel,
+    Scalar,
 )
 from pandas.compat._optional import import_optional_dependency
 from pandas.util._decorators import doc
@@ -1701,6 +1703,7 @@ def highlight_null(
         --------
         Styler.highlight_max: Highlight the maximum with a style.
         Styler.highlight_min: Highlight the minimum with a style.
+        Styler.highlight_between: Highlight a defined range with a style.
         """
 
         def f(data: DataFrame, props: str) -> np.ndarray:
@@ -1748,6 +1751,7 @@ def highlight_max(
         --------
         Styler.highlight_null: Highlight missing values with a style.
         Styler.highlight_min: Highlight the minimum with a style.
+        Styler.highlight_between: Highlight a defined range with a style.
         """
 
         def f(data: FrameOrSeries, props: str) -> np.ndarray:
@@ -1795,6 +1799,7 @@ def highlight_min(
         --------
         Styler.highlight_null: Highlight missing values with a style.
         Styler.highlight_max: Highlight the maximum with a style.
+        Styler.highlight_between: Highlight a defined range with a style.
         """
 
         def f(data: FrameOrSeries, props: str) -> np.ndarray:
@@ -1808,6 +1813,163 @@ def f(data: FrameOrSeries, props: str) -> np.ndarray:
             f, axis=axis, subset=subset, props=props  # type: ignore[arg-type]
         )
 
+    def highlight_between(
+        self,
+        subset: Optional[IndexLabel] = None,
+        color: str = "yellow",
+        axis: Optional[Axis] = 0,
+        left: Optional[Union[Scalar, Sequence]] = None,
+        right: Optional[Union[Scalar, Sequence]] = None,
+        inclusive: Union[bool, str] = "both",
+        props: Optional[str] = None,
+    ) -> Styler:
+        """
+        Highlight a defined range with a style.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        subset : IndexSlice, default None
+            A valid slice for ``data`` to limit the style application to.
+        color : str, default 'yellow'
+            Background color to use for highlighting.
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            If ``left`` or ``right`` given as sequence, axis along which to apply those
+            boundaries. See examples.
+        left : scalar or datetime-like, or sequence or array-like, default None
+            Left bound for defining the range.
+        right : scalar or datetime-like, or sequence or array-like, default None
+            Right bound for defining the range.
+        inclusive : {'both', 'neither', 'left', 'right'}
+            Identify whether bounds are closed or open.
+        props : str, default None
+            CSS properties to use for highlighting. If ``props`` is given, ``color``
+            is not used.
+
+        Returns
+        -------
+        self : Styler
+
+        See Also
+        --------
+        Styler.highlight_null: Highlight missing values with a style.
+        Styler.highlight_max: Highlight the maximum with a style.
+        Styler.highlight_min: Highlight the minimum with a style.
+
+        Notes
+        -----
+        If ``left`` is ``None`` only the right bound is applied.
+        If ``right`` is ``None`` only the left bound is applied. If both are ``None``
+        all values are highlighted.
+
+        ``axis`` is only needed if ``left`` or ``right`` are provided as a sequence or
+        an array-like object for aligning the shapes. If ``left`` and ``right`` are
+        both scalars then all ``axis`` inputs will give the same result.
+
+        This function only works with compatible ``dtypes``. For example a datetime-like
+        region can only use equivalent datetime-like ``left`` and ``right`` arguments.
+        Use ``subset`` to control regions which have multiple ``dtypes``.
+
+        Examples
+        --------
+        Basic usage
+
+        >>> df = pd.DataFrame({
+        ...     'One': [1.2, 1.6, 1.5],
+        ...     'Two': [2.9, 2.1, 2.5],
+        ...     'Three': [3.1, 3.2, 3.8],
+        ... })
+        >>> df.style.highlight_between(left=2.1, right=2.9)
+
+        .. figure:: ../../_static/style/hr_basic.png
+
+        Using a range input sequnce along an ``axis``, in this case setting a ``left``
+        and ``right`` for each column individually
+
+        >>> df.style.highlight_between(left=[1.4, 2.4, 3.4], right=[1.6, 2.6, 3.6],
+        ...     axis=1, color="#fffd75")
+
+        .. figure:: ../../_static/style/hr_seq.png
+
+        Using ``axis=None`` and providing the ``left`` argument as an array that
+        matches the input DataFrame, with a constant ``right``
+
+        >>> df.style.highlight_between(left=[[2,2,3],[2,2,3],[3,3,3]], right=3.5,
+        ...     axis=None, color="#fffd75")
+
+        .. figure:: ../../_static/style/hr_axNone.png
+
+        Using ``props`` instead of default background coloring
+
+        >>> df.style.highlight_between(left=1.5, right=3.5,
+        ...     props='font-weight:bold;color:#e83e8c')
+
+        .. figure:: ../../_static/style/hr_props.png
+        """
+
+        def f(
+            data: FrameOrSeries,
+            props: str,
+            left: Optional[Union[Scalar, Sequence]] = None,
+            right: Optional[Union[Scalar, Sequence]] = None,
+            inclusive: Union[bool, str] = True,
+        ) -> np.ndarray:
+            def reshape(x, arg):
+                """if x is sequence check it fits axis, otherwise raise"""
+                if np.iterable(x) and not isinstance(x, str):
+                    try:
+                        return np.asarray(x).reshape(data.shape)
+                    except ValueError:
+                        raise ValueError(
+                            f"supplied '{arg}' is not correct shape for "
+                            "data over selected 'axis': got "
+                            f"{np.asarray(x).shape}, expected "
+                            f"{data.shape}"
+                        )
+                return x
+
+            left, right = reshape(left, "left"), reshape(right, "right")
+
+            # get ops with correct boundary attribution
+            if inclusive == "both":
+                ops = (operator.ge, operator.le)
+            elif inclusive == "neither":
+                ops = (operator.gt, operator.lt)
+            elif inclusive == "left":
+                ops = (operator.ge, operator.lt)
+            elif inclusive == "right":
+                ops = (operator.gt, operator.le)
+            else:
+                raise ValueError(
+                    f"'inclusive' values can be 'both', 'left', 'right', or 'neither' "
+                    f"got {inclusive}"
+                )
+
+            g_left = (
+                ops[0](data, left)
+                if left is not None
+                else np.full(data.shape, True, dtype=bool)
+            )
+            l_right = (
+                ops[1](data, right)
+                if right is not None
+                else np.full(data.shape, True, dtype=bool)
+            )
+            return np.where(g_left & l_right, props, "")
+
+        if props is None:
+            props = f"background-color: {color};"
+        return self.apply(
+            f,  # type: ignore[arg-type]
+            axis=axis,
+            subset=subset,
+            props=props,
+            left=left,
+            right=right,
+            inclusive=inclusive,
+        )
+
     @classmethod
     def from_custom_template(cls, searchpath, name):
         """

pandas/tests/io/formats/style/test_highlight.py

@@ -8,9 +8,8 @@
 
 class TestStylerHighlight:
     def setup_method(self, method):
-        np.random.seed(24)
-        self.s = DataFrame({"A": np.random.permutation(range(6))})
-        self.df = DataFrame({"A": [0, 1], "B": np.random.randn(2)})
+        self.s = DataFrame({"A": [4, 5, 1, 0, 3, 2]})
+        self.df = DataFrame({"A": [0, 1], "B": [-0.609, -1.228]})
 
     def test_highlight_null(self):
         df = DataFrame({"A": [0, np.nan]})
@@ -63,3 +62,65 @@ def test_highlight_minmax_ext(self, f, kwargs):
             df = self.df
         result = getattr(df.style, f)(**kwargs)._compute().ctx
         assert result == expected
+
+    @pytest.mark.parametrize(
+        "kwargs",
+        [
+            {"left": 0, "right": 1},  # test basic range
+            {"left": 0, "right": 1, "props": "background-color: yellow"},  # test props
+            {"left": -9, "right": 9, "subset": ["A"]},  # test subset effective
+            {"left": 0},  # test no right
+            {"right": 1, "subset": ["A"]},  # test no left
+            {"left": [0, 1], "axis": 0},  # test left as sequence
+            {"left": DataFrame([[0, 1], [1, 1]]), "axis": None},  # test axis with seq
+            {"left": 0, "right": [0, 1], "axis": 0},  # test sequence right
+        ],
+    )
+    def test_highlight_between(self, kwargs):
+        expected = {
+            (0, 0): [("background-color", "yellow")],
+            (1, 0): [("background-color", "yellow")],
+        }
+        result = self.df.style.highlight_between(**kwargs)._compute().ctx
+        assert result == expected
+
+    @pytest.mark.parametrize(
+        "arg, map, axis",
+        [
+            ("left", [1, 2, 3], 0),  # 0 axis has 2 elements not 3
+            ("left", [1, 2], 1),  # 1 axis has 3 elements not 2
+            ("left", np.array([[1, 2], [1, 2]]), None),  # df is (2,3) not (2,2)
+            ("right", [1, 2, 3], 0),  # same tests as above for 'right' not 'left'
+            ("right", [1, 2], 1),  # ..
+            ("right", np.array([[1, 2], [1, 2]]), None),  # ..
+        ],
+    )
+    def test_highlight_between_raises(self, arg, map, axis):
+        df = DataFrame([[1, 2, 3], [1, 2, 3]])
+        msg = f"supplied '{arg}' is not correct shape"
+        with pytest.raises(ValueError, match=msg):
+            df.style.highlight_between(**{arg: map, "axis": axis})._compute()
+
+    def test_highlight_between_raises2(self):
+        msg = "values can be 'both', 'left', 'right', or 'neither'"
+        with pytest.raises(ValueError, match=msg):
+            self.df.style.highlight_between(inclusive="badstring")._compute()
+
+        with pytest.raises(ValueError, match=msg):
+            self.df.style.highlight_between(inclusive=1)._compute()
+
+    def test_highlight_between_inclusive(self):
+        kwargs = {"left": 0, "right": 1, "subset": ["A"]}
+        result = self.df.style.highlight_between(**kwargs, inclusive="both")._compute()
+        assert result.ctx == {
+            (0, 0): [("background-color", "yellow")],
+            (1, 0): [("background-color", "yellow")],
+        }
+        result = self.df.style.highlight_between(
+            **kwargs, inclusive="neither"
+        )._compute()
+        assert result.ctx == {}
+        result = self.df.style.highlight_between(**kwargs, inclusive="left")._compute()
+        assert result.ctx == {(0, 0): [("background-color", "yellow")]}
+        result = self.df.style.highlight_between(**kwargs, inclusive="right")._compute()
+        assert result.ctx == {(1, 0): [("background-color", "yellow")]}

pandas/tests/io/formats/style/test_style.py

@@ -20,9 +20,8 @@
 
 class TestStyler:
     def setup_method(self, method):
-        np.random.seed(24)
-        self.s = DataFrame({"A": np.random.permutation(range(6))})
-        self.df = DataFrame({"A": [0, 1], "B": np.random.randn(2)})
+        self.s = DataFrame({"A": [4, 5, 1, 0, 3, 2]})
+        self.df = DataFrame({"A": [0, 1], "B": [-0.609, -1.228]})
         self.f = lambda x: x
         self.g = lambda x: x