Color text based on background gradient

Close pandas-dev#21258

Author: joelostblom

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=0.3):
         """
         Color the background in a gradient according to
         the data in each column (optionally row).
@@ -879,26 +879,30 @@ 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: float or int
+            luminance threshold for determining text color. Facilitates text
+            visibility across varying background colors. From 0 to 1.
+            0 = all text is colored black, 1 = all text is colored white.
 
         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`` 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=text_color)
         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=0.3):
         """Color background in a range according to the data."""
         with _mpl(Styler.background_gradient) as (plt, colors):
             rng = s.max() - s.min()
@@ -909,8 +913,33 @@ 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, (float, int)) or
+                    not 0 <= text_color <= 1):
+                msg = "`text_color` must be a value from 0 to 1."
+                raise ValueError(msg)
+
+            def relative_luminance(color):
+                """Calculate the relative luminance of a color according to W3C
+                standards, https://www.w3.org/WAI/GL/wiki/Relative_luminance
+                Parameters
+                ----------
+                color : matplotlib color. Hex code, rgb-tuple, or
+                HTML color name.
+                Returns
+                -------
+                luminance : float between 0 and 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 = ['#ffffff' if relative_luminance(x) < text_color
+                           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):
         """