ENH: Add bad, under, over kwargs to Colormap

This is part of the effort for making Colormaps immutable (matplotlib#29141).
Obviously, we can only get immutable in the future if the
bad, under, over colors can already be set upon creation.

Author: timhoffm

lib/matplotlib/colors.py

@@ -714,20 +714,26 @@ class Colormap:
     chain.
     """
 
-    def __init__(self, name, N=256):
+    def __init__(self, name, N=256, *, bad=None, under=None, over=None):
         """
         Parameters
         ----------
         name : str
             The name of the colormap.
         N : int
             The number of RGB quantization levels.
+        bad : :mpltype:`color`, default: transparent
+            The color for invalid values (NaN or masked).
+        under : :mpltype:`color`, default: color of the lowest value
+            The color for low out-of-range values.
+        over : :mpltype:`color`, default: color of the highest value
+            The color for high out-of-range values.
         """
         self.name = name
         self.N = int(N)  # ensure that N is always int
-        self._rgba_bad = (0.0, 0.0, 0.0, 0.0)  # If bad, don't paint anything.
-        self._rgba_under = None
-        self._rgba_over = None
+        self._rgba_bad = (0.0, 0.0, 0.0, 0.0) if bad is None else to_rgba(bad)
+        self._rgba_under = None if under is None else to_rgba(under)
+        self._rgba_over = None if over is None else to_rgba(over)
         self._i_under = self.N
         self._i_over = self.N + 1
         self._i_bad = self.N + 2
@@ -1034,9 +1040,10 @@ class LinearSegmentedColormap(Colormap):
     segments.
     """
 
-    def __init__(self, name, segmentdata, N=256, gamma=1.0):
+    def __init__(self, name, segmentdata, N=256, gamma=1.0, *,
+                 bad=None, under=None, over=None):
         """
-        Create colormap from linear mapping segments
+        Create colormap from linear mapping segments.
 
         segmentdata argument is a dictionary with a red, green and blue
         entries. Each entry should be a list of *x*, *y0*, *y1* tuples,
@@ -1070,7 +1077,7 @@ def __init__(self, name, segmentdata, N=256, gamma=1.0):
                           /
             row i+1: x  y0  y1
 
-        Hence y0 in the first row and y1 in the last row are never used.
+        Hence, y0 in the first row and y1 in the last row are never used.
 
         See Also
         --------
@@ -1080,7 +1087,7 @@ def __init__(self, name, segmentdata, N=256, gamma=1.0):
         """
         # True only if all colors in map are identical; needed for contouring.
         self.monochrome = False
-        super().__init__(name, N)
+        super().__init__(name, N, bad=bad, under=under, over=over)
         self._segmentdata = segmentdata
         self._gamma = gamma
 
@@ -1104,7 +1111,7 @@ def set_gamma(self, gamma):
         self._init()
 
     @staticmethod
-    def from_list(name, colors, N=256, gamma=1.0):
+    def from_list(name, colors, N=256, gamma=1.0, bad=None, under=None, over=None):
         """
         Create a `LinearSegmentedColormap` from a list of colors.
 
@@ -1121,6 +1128,13 @@ def from_list(name, colors, N=256, gamma=1.0):
         N : int
             The number of RGB quantization levels.
         gamma : float
+
+        bad : :mpltype:`color`, default: transparent
+            The color for invalid values (NaN or masked).
+        under : :mpltype:`color`, default: color of the lowest value
+            The color for low out-of-range values.
+        over : :mpltype:`color`, default: color of the highest value
+            The color for high out-of-range values.
         """
         if not np.iterable(colors):
             raise ValueError('colors must be iterable')
@@ -1140,7 +1154,8 @@ def from_list(name, colors, N=256, gamma=1.0):
             "alpha": np.column_stack([vals, a, a]),
         }
 
-        return LinearSegmentedColormap(name, cdict, N, gamma)
+        return LinearSegmentedColormap(name, cdict, N, gamma,
+                                       bad=bad, under=under, over=over)
 
     def resampled(self, lutsize):
         """Return a new colormap with *lutsize* entries."""
@@ -1215,6 +1230,18 @@ class ListedColormap(Colormap):
             N > len(colors)
 
         the list will be extended by repetition.
+
+        .. deprecated:: 3.11
+
+            This parameter will be removed. Please ensure instead that
+            the list of passed colors is the required length.
+
+    bad : :mpltype:`color`, default: transparent
+        The color for invalid values (NaN or masked).
+    under : :mpltype:`color`, default: color of the lowest value
+        The color for low out-of-range values.
+    over : :mpltype:`color`, default: color of the highest value
+        The color for high out-of-range values.
     """
 
     @_api.delete_parameter(
@@ -1223,7 +1250,8 @@ class ListedColormap(Colormap):
                 "and will be removed in %(removal)s. Please ensure the list "
                 "of passed colors is the required length instead."
     )
-    def __init__(self, colors, name='from_list', N=None):
+    def __init__(self, colors, name='from_list', N=None, *,
+                 bad=None, under=None, over=None):
         if N is None:
             self.colors = colors
             N = len(colors)
@@ -1240,7 +1268,7 @@ def __init__(self, colors, name='from_list', N=None):
                     pass
                 else:
                     self.colors = [gray] * N
-        super().__init__(name, N)
+        super().__init__(name, N, bad=bad, under=under, over=over)
 
     def _init(self):
         self._lut = np.zeros((self.N + 3, 4), float)

lib/matplotlib/colors.pyi

@@ -120,19 +120,24 @@ class LinearSegmentedColormap(Colormap):
         ],
         N: int = ...,
         gamma: float = ...,
+        bad: ColorType | None = ...,
+        under: ColorType | None = ...,
+        over: ColorType | None = ...,
     ) -> None: ...
     def set_gamma(self, gamma: float) -> None: ...
     @staticmethod
     def from_list(
-        name: str, colors: ArrayLike | Sequence[tuple[float, ColorType]], N: int = ..., gamma: float = ...
+        name: str, colors: ArrayLike | Sequence[tuple[float, ColorType]], N: int = ..., gamma: float = ...,
+        bad: ColorType | None = ..., under: ColorType | None = ..., over: ColorType | None = ...,
     ) -> LinearSegmentedColormap: ...
     def resampled(self, lutsize: int) -> LinearSegmentedColormap: ...
     def reversed(self, name: str | None = ...) -> LinearSegmentedColormap: ...
 
 class ListedColormap(Colormap):
     colors: ArrayLike | ColorType
     def __init__(
-        self, colors: ArrayLike | ColorType, name: str = ..., N: int | None = ...
+        self, colors: ArrayLike | ColorType, name: str = ..., N: int | None = ...,
+        bad: ColorType | None = ..., under: ColorType | None = ..., over: ColorType | None = ...
     ) -> None: ...
     @property
     def monochrome(self) -> bool: ...

lib/matplotlib/tests/test_colors.py

@@ -221,6 +221,33 @@ def test_colormap_return_types():
     assert cmap(x2d).shape == x2d.shape + (4,)
 
 
+def test_ListedColormap_bad_under_over():
+    cmap = mcolors.ListedColormap(["r", "g", "b"], bad="c", under="m", over="y")
+    assert mcolors.same_color(cmap.get_bad(), "c")
+    assert mcolors.same_color(cmap.get_under(), "m")
+    assert mcolors.same_color(cmap.get_over(), "y")
+
+
+def test_LinearSegmentedColormap_bad_under_over():
+    cdict = {
+        'red': [(0., 0., 0.), (0.5, 1., 1.), (1., 1., 1.)],
+        'green': [(0., 0., 0.), (0.25, 0., 0.), (0.75, 1., 1.), (1., 1., 1.)],
+        'blue': [(0., 0., 0.), (0.5, 0., 0.), (1., 1., 1.)],
+    }
+    cmap = mcolors.LinearSegmentedColormap("lsc", cdict, bad="c", under="m", over="y")
+    assert mcolors.same_color(cmap.get_bad(), "c")
+    assert mcolors.same_color(cmap.get_under(), "m")
+    assert mcolors.same_color(cmap.get_over(), "y")
+
+
+def test_LinearSegmentedColormap_from_list_bad_under_over():
+    cmap = mcolors.LinearSegmentedColormap.from_list(
+        "lsc", ["r", "g", "b"], bad="c", under="m", over="y")
+    assert mcolors.same_color(cmap.get_bad(), "c")
+    assert mcolors.same_color(cmap.get_under(), "m")
+    assert mcolors.same_color(cmap.get_over(), "y")
+
+
 def test_BoundaryNorm():
     """
     GitHub issue #1258: interpolation was failing with numpy