Color text based on background color when using _background_gradient()

pandas/io/formats/style.py

@@ -863,7 +863,7 @@ def highlight_null(self, null_color='red'):
         return self
 
     def background_gradient(self, cmap='PuBu', low=0, high=0, axis=0,
-                            subset=None):
+                            subset=None, text_color_threshold=0.408):
         """
         Color the background in a gradient according to
         the data in each column (optionally row).
@@ -879,26 +879,34 @@ def background_gradient(self, cmap='PuBu', low=0, high=0, axis=0,
             1 or 'columns' for columnwise, 0 or 'index' for rowwise
         subset: IndexSlice
             a valid slice for ``data`` to limit the style application to
+        text_color_threshold: float or int
+            luminance threshold for determining text color. Facilitates text
+            visibility across varying background colors. From 0 to 1.
+            0 = all text is dark colored, 1 = all text is light colored.
+
+            .. versionadded:: 0.24.0
 
         Returns
         -------
         self : Styler
 
         Notes
         -----
-        Tune ``low`` and ``high`` to keep the text legible by
-        not using the entire range of the color map. These extend
-        the range of the data by ``low * (x.max() - x.min())``
-        and ``high * (x.max() - x.min())`` before normalizing.
+        Set ``text_color_threshold`` or tune ``low`` and ``high`` to keep the
+        text legible by not using the entire range of the color map. The range
+        of the data is extended by ``low * (x.max() - x.min())`` and ``high *
+        (x.max() - x.min())`` before normalizing.
         """
         subset = _maybe_numeric_slice(self.data, subset)
         subset = _non_reducing_slice(subset)
         self.apply(self._background_gradient, cmap=cmap, subset=subset,
-                   axis=axis, low=low, high=high)
+                   axis=axis, low=low, high=high,
+                   text_color_threshold=text_color_threshold)
         return self
 
     @staticmethod
-    def _background_gradient(s, cmap='PuBu', low=0, high=0):
+    def _background_gradient(s, cmap='PuBu', low=0, high=0,
+                             text_color_threshold=0.408):
         """Color background in a range according to the data."""
         with _mpl(Styler.background_gradient) as (plt, colors):
             rng = s.max() - s.min()
@@ -909,8 +917,39 @@ def _background_gradient(s, cmap='PuBu', low=0, high=0):
             # https://github.com/matplotlib/matplotlib/issues/5427
             normed = norm(s.values)
             c = [colors.rgb2hex(x) for x in plt.cm.get_cmap(cmap)(normed)]
-            return ['background-color: {color}'.format(color=color)
-                    for color in c]
+            if (not isinstance(text_color_threshold, (float, int)) or
+                    not 0 <= text_color_threshold <= 1):
+                msg = "`text_color_threshold` must be a value from 0 to 1."
+                raise ValueError(msg)
+
+            def relative_luminance(color):
+                """
+                Calculate relative luminance of a color.
+
+                The calculation adheres to the W3C standards
+                (https://www.w3.org/WAI/GL/wiki/Relative_luminance)
+
+                Parameters
+                ----------
+                color : matplotlib color
+                    Hex code, rgb-tuple, or HTML color name.
+
+                Returns
+                -------
+                float
+                    The relative luminance as a value from 0 to 1
+                """
+                rgb = colors.colorConverter.to_rgba_array(color)[:, :3]
+                rgb = np.where(rgb <= .03928, rgb / 12.92,
+                               ((rgb + .055) / 1.055) ** 2.4)
+                lum = rgb.dot([.2126, .7152, .0722])
+                return lum.item()
+
+            text_colors = ['#f1f1f1' if relative_luminance(x) <
+                           text_color_threshold else '#000000' for x in c]
+
+            return ['background-color: {color};color: {tc}'.format(
+                    color=color, tc=tc) for color, tc in zip(c, text_colors)]
 
     def set_properties(self, subset=None, **kwargs):
         """

pandas/tests/io/formats/test_style.py

@@ -1028,10 +1028,25 @@ def test_background_gradient(self):
             assert all("#" in x[0] for x in result.values())
             assert result[(0, 0)] == result[(0, 1)]
             assert result[(1, 0)] == result[(1, 1)]
+            for res in result:
+                if result[res][0].split(' ')[1] in ['#fde725', '#ffffcc']:
+                    assert result[(res)][1].split(' ')[1] == '#000000'
+                elif result[res][0].split(' ')[1] in ['#800026', '#440154']:
+                    assert result[(res)][1].split(' ')[1] == '#f1f1f1'
 
         result = df.style.background_gradient(
             subset=pd.IndexSlice[1, 'A'])._compute().ctx
-        assert result[(1, 0)] == ['background-color: #fff7fb']
+
+        assert result[(1, 0)] == ['background-color: #fff7fb',
+                                  'color: #000000']
+
+    @td.skip_if_no_mpl
+    def test_text_color_threshold(self):
+        df = pd.DataFrame([[1, 2], [2, 4]], columns=['A', 'B'])
+        for text_color_threshold in [1.1, '1', -1, [2, 2]]:
+            with pytest.raises(ValueError):
+                df.style.background_gradient(
+                    text_color_threshold=text_color_threshold)
 
 
 def test_block_names():