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