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
@@ -43,7 +45,10 @@
 from pandas.api.types import is_list_like
 from pandas.core import generic
 import pandas.core.common as com
-from pandas.core.frame import DataFrame
+from pandas.core.frame import (
+    DataFrame,
+    Series,
+)
 from pandas.core.generic import NDFrame
 from pandas.core.indexes.api import Index
 
@@ -1703,6 +1708,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:
@@ -1750,6 +1756,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:
@@ -1797,6 +1804,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:
@@ -1810,6 +1818,155 @@ 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/hbetw_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/hbetw_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/hbetw_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/hbetw_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,
+            axis_: Optional[Axis] = None,
+        ) -> np.ndarray:
+            if np.iterable(left) and not isinstance(left, str):
+                left = _validate_apply_axis_arg(left, "left", None, axis_, data)
+
+            if np.iterable(right) and not isinstance(right, str):
+                right = _validate_apply_axis_arg(right, "right", None, axis_, data)
+
+            # 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,
+            axis_=axis,
+        )
+
     @classmethod
     def from_custom_template(cls, searchpath, name):
         """
@@ -2257,3 +2414,59 @@ def pred(part) -> bool:
     else:
         slice_ = [part if pred(part) else [part] for part in slice_]
     return tuple(slice_)
+
+
+def _validate_apply_axis_arg(
+    arg: Union[FrameOrSeries, Sequence],
+    arg_name: str,
+    dtype: Optional[Any],
+    axis: Optional[Axis],
+    data: FrameOrSeries,
+) -> np.ndarray:
+    """
+    For the apply-type methods, ``axis=None`` creates ``data`` as DataFrame, and for
+    ``axis=[1,0]`` it creates a Series. Where ``arg`` is expected as an element
+    of some operator with ``data`` we must make sure that the two are compatible shapes,
+    or raise.
+
+    Parameters
+    ----------
+    arg : sequence, Series or DataFrame
+        the user input arg
+    arg_name : string
+        name of the arg for use in error messages
+    dtype : numpy dtype, optional
+        forced numpy dtype if given
+    axis : {0,1, None}
+        axis over which apply-type method is used
+    data : Series or DataFrame
+        underling subset of Styler data on which operations are performed
+
+    Returns
+    -------
+    ndarray
+    """
+    dtype = {"dtype": dtype} if dtype else {}
+    # raise if input is wrong for axis:
+    if isinstance(arg, Series) and axis is None:
+        raise ValueError(
+            f"'{arg_name}' is a Series but underlying data for operations "
+            f"is a DataFrame since 'axis=None'"
+        )
+    elif isinstance(arg, DataFrame) and axis in [0, 1]:
+        raise ValueError(
+            f"'{arg_name}' is a DataFrame but underlying data for "
+            f"operations is a Series with 'axis={axis}'"
+        )
+    elif isinstance(arg, (Series, DataFrame)):  # align indx / cols to data
+        arg = arg.reindex_like(data, method=None).to_numpy(**dtype)
+    else:
+        arg = np.asarray(arg, **dtype)
+        assert isinstance(arg, np.ndarray)  # mypy requirement
+        if arg.shape != data.shape:  # check valid input
+            raise ValueError(
+                f"supplied '{arg_name}' is not correct shape for data over "
+                f"selected 'axis': got {arg.shape}, "
+                f"expected {data.shape}"
+            )
+    return arg

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({"A": [0, 1], "B": [1, 1]}), "axis": None},  # test axis
+            {"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