docstrings for multivariate plotting in imshow, pcolor and pcolormesh

trygvrad · trygvrad · commit 48eb32ba2413 · 2025-02-24T21:26:23.000+01:00
diff --git a/doc/api/colors_api.rst b/doc/api/colors_api.rst
@@ -53,6 +53,7 @@ Multivariate Colormaps
    BivarColormap
    SegmentedBivarColormap
    BivarColormapFromImage
+   MultivarColormap
 
 Other classes
 -------------
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5753,7 +5753,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
         """
         Display data as an image, i.e., on a 2D regular raster.
 
-        The input may either be actual RGB(A) data, or 2D scalar data, which
+        The input may either be actual RGB(A) data, or 2D data, which
         will be rendered as a pseudocolor image. For displaying a grayscale
         image, set up the colormapping using the parameters
         ``cmap='gray', vmin=0, vmax=255``.
@@ -5774,24 +5774,25 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
             - (M, N): an image with scalar data. The values are mapped to
               colors using normalization and a colormap. See parameters *norm*,
               *cmap*, *vmin*, *vmax*.
+            - (K, M, N): multiple images with scalar data. Must be used
+              with a multivariate or bivariate colormap. See *cmap*.
             - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
             - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
               i.e. including transparency.
 
-            The first two dimensions (M, N) define the rows and columns of
-            the image.
+            Here M and N define the rows and columns of the image.
 
             Out-of-range RGB(A) values are clipped.
 
-        %(cmap_doc)s
+        %(multi_cmap_doc)s
 
             This parameter is ignored if *X* is RGB(A).
 
-        %(norm_doc)s
+        %(multi_norm_doc)s
 
             This parameter is ignored if *X* is RGB(A).
 
-        %(vmin_vmax_doc)s
+        %(multi_vmin_vmax_doc)s
 
             This parameter is ignored if *X* is RGB(A).
 
@@ -6130,9 +6131,10 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
 
         Parameters
         ----------
-        C : 2D array-like
+        C : 2D array-like or list of 2D array-like objects
             The color-mapped values.  Color-mapping is controlled by *cmap*,
-            *norm*, *vmin*, and *vmax*.
+            *norm*, *vmin*, and *vmax*.  Multiple arrays are only supported
+            when a bivariate or mulivariate colormap is used, see *cmap*.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -6179,11 +6181,11 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
             See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
             for more description.
 
-        %(cmap_doc)s
+        %(multi_cmap_doc)s
 
-        %(norm_doc)s
+        %(multi_norm_doc)s
 
-        %(vmin_vmax_doc)s
+        %(multi_vmin_vmax_doc)s
 
         %(colorizer_doc)s
 
@@ -6370,12 +6372,13 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             - (M, N) or M*N: a mesh with scalar data. The values are mapped to
               colors using normalization and a colormap. See parameters *norm*,
               *cmap*, *vmin*, *vmax*.
+            - (K, M, N): multiple images with scalar data. Must be used with
+              a multivariate or bivariate colormap. See *cmap*.
             - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
             - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
               i.e. including transparency.
 
-            The first two dimensions (M, N) define the rows and columns of
-            the mesh data.
+            Here M and N define the rows and columns of the image.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -6406,11 +6409,11 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             expanded as needed into the appropriate 2D arrays, making a
             rectangular grid.
 
-        %(cmap_doc)s
+        %(multi_cmap_doc)s
 
-        %(norm_doc)s
+        %(multi_norm_doc)s
 
-        %(vmin_vmax_doc)s
+        %(multi_vmin_vmax_doc)s
 
         %(colorizer_doc)s
 
diff --git a/lib/matplotlib/colorizer.py b/lib/matplotlib/colorizer.py
@@ -607,6 +607,15 @@ def _get_colorizer(cmap, norm, colorizer):
 cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
     The Colormap instance or registered colormap name used to map scalar data
     to colors.""",
+    multi_cmap_doc="""\
+cmap : str, `~matplotlib.colors.Colormap`, `~matplotlib.colors.BivarColormap`\
+    or `~matplotlib.colors.MultivarColormap`, default: :rc:`image.cmap`
+    The Colormap instance or registered colormap name used to map
+    scalar/multivariate data to colors.
+
+    Multivariate data is only accepted if a multivariate colormap
+    (`~matplotlib.colors.BivarColormap` or `~matplotlib.colors.MultivarColormap`)
+    is used.""",
     norm_doc="""\
 norm : str or `~matplotlib.colors.Normalize`, optional
     The normalization method used to scale scalar data to the [0, 1] range
@@ -621,13 +630,41 @@ def _get_colorizer(cmap, norm, colorizer):
       list of available scales, call `matplotlib.scale.get_scale_names()`.
       In that case, a suitable `.Normalize` subclass is dynamically generated
       and instantiated.""",
+    multi_norm_doc="""\
+norm : str, `~matplotlib.colors.Normalize` or list, optional
+    The normalization method used to scale data to the [0, 1] range
+    before mapping to colors using *cmap*. By default, a linear scaling is
+    used, mapping the lowest value to 0 and the highest to 1.
+
+    If given, this can be one of the following:
+
+    - An instance of `.Normalize` or one of its subclasses
+      (see :ref:`colormapnorms`).
+    - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc.  For a
+      list of available scales, call `matplotlib.scale.get_scale_names()`.
+      In that case, a suitable `.Normalize` subclass is dynamically generated
+      and instantiated.
+    - A list of scale names or `.Normalize` objects matching the number of
+      variates in the colormap, for use with `~matplotlib.colors.BivarColormap`
+      or `~matplotlib.colors.MultivarColormap`, i.e. ``["linear", "log"]``.""",
     vmin_vmax_doc="""\
 vmin, vmax : float, optional
     When using scalar data and no explicit *norm*, *vmin* and *vmax* define
     the data range that the colormap covers. By default, the colormap covers
     the complete value range of the supplied data. It is an error to use
     *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
     name together with *vmin*/*vmax* is acceptable).""",
+    multi_vmin_vmax_doc="""\
+vmin, vmax : float or list, optional
+    When using scalar data and no explicit *norm*, *vmin* and *vmax* define
+    the data range that the colormap covers. By default, the colormap covers
+    the complete value range of the supplied data. It is an error to use
+    *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
+    name together with *vmin*/*vmax* is acceptable).
+
+    A list can be used to define independent limits for each variate when
+    using a `~matplotlib.colors.BivarColormap` or
+    `~matplotlib.colors.MultivarColormap`.""",
 )
 
 
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1420,10 +1420,10 @@ def __init__(self, colormaps, combination_mode, name='multivariate colormap'):
         combination_mode: str, 'sRGB_add' or 'sRGB_sub'
             Describe how colormaps are combined in sRGB space
 
-            - If 'sRGB_add' -> Mixing produces brighter colors
-              `sRGB = sum(colors)`
-            - If 'sRGB_sub' -> Mixing produces darker colors
-              `sRGB = 1 - sum(1 - colors)`
+            - If 'sRGB_add': Mixing produces brighter colors
+              ``sRGB = sum(colors)``
+            - If 'sRGB_sub': Mixing produces darker colors
+              ``sRGB = 1 - sum(1 - colors)``
         name : str, optional
             The name of the colormap family.
         """
@@ -1598,12 +1598,12 @@ def with_extremes(self, *, bad=None, under=None, over=None):
         bad: :mpltype:`color`, default: None
             If Matplotlib color, the bad value is set accordingly in the copy
 
-        under tuple of :mpltype:`color`, default: None
-            If tuple, the `under` value of each component is set with the values
+        under: tuple of :mpltype:`color`, default: None
+            If tuple, the ``under`` value of each component is set with the values
             from the tuple.
 
-        over tuple of :mpltype:`color`, default: None
-            If tuple, the `over` value of each component is set with the values
+        over: tuple of :mpltype:`color`, default: None
+            If tuple, the ``over`` value of each component is set with the values
             from the tuple.
 
         Returns
