Tentative norm docs.

anntzer · anntzer · commit 7b34dc1364e4 · 2022-07-03T19:58:13.000+02:00
diff --git a/doc/users/next_whats_new/strnorm.rst b/doc/users/next_whats_new/strnorm.rst
@@ -0,0 +1,6 @@
+Setting norms with strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Norms can now be set (e.g. on images) using the string name of the
+corresponding scale, e.g. ``imshow(array, norm="log")``.  Note that in that
+case, it is permissible to also pass *vmin* and *vmax*, as a new Norm instance
+will be created under the hood.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4369,21 +4369,10 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             See :mod:`matplotlib.markers` for more information about marker
             styles.
 
-        cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            A `.Colormap` instance or registered colormap name. *cmap* is only
-            used if *c* is an array of floats.
-
-        norm : `~matplotlib.colors.Normalize`, default: None
-            If *c* is an array of floats, *norm* is used to scale the color
-            data, *c*, in the range 0 to 1, in order to map into the colormap
-            *cmap*.
-            If *None*, use the default `.colors.Normalize`.
-
-        vmin, vmax : float, default: None
-            *vmin* and *vmax* are used in conjunction with the default norm to
-            map the color array *c* to the colormap *cmap*. If None, the
-            respective min and max of the color array is used.
-            It is an error to use *vmin*/*vmax* when *norm* is given.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters for *c*; only used
+            if *c* is an array of floats. See `~.Axes.imshow` for a detailed
+            description.
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4656,21 +4645,9 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
 
         Other Parameters
         ----------------
-        cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            The Colormap instance or registered colormap name used to map
-            the bin values to colors.
-
-        norm : `~matplotlib.colors.Normalize`, optional
-            The Normalize instance scales the bin values to the canonical
-            colormap range [0, 1] for mapping to colors. By default, the data
-            range is mapped to the colorbar range using linear scaling.
-
-        vmin, vmax : float, default: None
-            The colorbar range. If *None*, suitable min/max values are
-            automatically chosen by the `.Normalize` instance (defaults to
-            the respective min/max values of the bins in case of the default
-            linear scaling).
-            It is an error to use *vmin*/*vmax* when *norm* is given.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters. See `~.Axes.imshow`
+            for a detailed description.
 
         alpha : float between 0 and 1, optional
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5296,6 +5273,10 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
         replace_names=["y", "x1", "x2", "where"])
 
     #### plotting z(x, y): imshow, pcolor and relatives, contour
+
+    # Once this deprecation elapses, also move vmin, vmax right after norm, to
+    # match the signature of other methods returning ScalarMappables and keep
+    # the documentation for *norm*, *vmax* and *vmin* together.
     @_api.make_keyword_only("3.5", "aspect")
     @_preprocess_data()
     def imshow(self, X, cmap=None, norm=None, aspect=None,
@@ -5340,12 +5321,31 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             The Colormap instance or registered colormap name used to map
             scalar data to colors. This parameter is ignored for RGB(A) data.
 
-        norm : `~matplotlib.colors.Normalize`, optional
-            The `.Normalize` instance used to scale scalar data to the [0, 1]
+        norm : str or `~matplotlib.colors.Normalize`, optional
+            The normalization method used to scale scalar data to the [0, 1]
             range before mapping to colors using *cmap*. By default, a linear
             scaling mapping the lowest value to 0 and the highest to 1 is used.
             This parameter is ignored for RGB(A) data.
 
+            If given, this can be one of the following:
+
+            - An instance of `.Normalize` or one of its subclasses
+              (see :doc:`/tutorials/colors/colormapnorms`).
+            - A scale name, i.e. one of "linear", "log", "symlog", "logit",
+              etc. For a full list of available scales call
+              `matplotlib.scales.get_scale_names()`.
+              In that case, a suitable `.Normalize` subclass is dynamically
+              generated and instantiated.
+
+        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). When using RGB(A) data, parameters *vmin*/*vmax* are
+            ignored.
+
         aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
             The aspect ratio of the Axes.  This parameter is particularly
             relevant for images since it determines whether data pixels are
@@ -5404,13 +5404,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             If *alpha* is an array, the alpha blending values are applied pixel
             by pixel, and *alpha* must have the same shape as *X*.
 
-        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 *norm* is given.
-            When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
-
         origin : {'upper', 'lower'}, default: :rc:`image.origin`
             Place the [0, 0] index of the array in the upper left or lower
             left corner of the Axes. The convention (the default) 'upper' is
@@ -5721,21 +5714,9 @@ 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 : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            A Colormap instance or registered colormap name. The colormap
-            maps the *C* values to colors.
-
-        norm : `~matplotlib.colors.Normalize`, optional
-            The Normalize instance scales the data values to the canonical
-            colormap range [0, 1] for mapping to colors. By default, the data
-            range is mapped to the colorbar range using linear scaling.
-
-        vmin, vmax : float, default: None
-            The colorbar range. If *None*, suitable min/max values are
-            automatically chosen by the `.Normalize` instance (defaults to
-            the respective min/max values of *C* in case of the default linear
-            scaling).
-            It is an error to use *vmin*/*vmax* when *norm* is given.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters for *C*. See
+            `~.Axes.imshow` for a detailed description.
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -5947,21 +5928,9 @@ 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 : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            A Colormap instance or registered colormap name. The colormap
-            maps the *C* values to colors.
-
-        norm : `~matplotlib.colors.Normalize`, optional
-            The Normalize instance scales the data values to the canonical
-            colormap range [0, 1] for mapping to colors. By default, the data
-            range is mapped to the colorbar range using linear scaling.
-
-        vmin, vmax : float, default: None
-            The colorbar range. If *None*, suitable min/max values are
-            automatically chosen by the `.Normalize` instance (defaults to
-            the respective min/max values of *C* in case of the default linear
-            scaling).
-            It is an error to use *vmin*/*vmax* when *norm* is given.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters for *C*. See
+            `~.Axes.imshow` for a detailed description.
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -6195,21 +6164,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
             These arguments can only be passed positionally.
 
-        cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            A Colormap instance or registered colormap name. The colormap
-            maps the *C* values to colors.
-
-        norm : `~matplotlib.colors.Normalize`, optional
-            The Normalize instance scales the data values to the canonical
-            colormap range [0, 1] for mapping to colors. By default, the data
-            range is mapped to the colorbar range using linear scaling.
-
-        vmin, vmax : float, default: None
-            The colorbar range. If *None*, suitable min/max values are
-            automatically chosen by the `.Normalize` instance (defaults to
-            the respective min/max values of *C* in case of the default linear
-            scaling).
-            It is an error to use *vmin*/*vmax* when *norm* is given.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters for *C*. See
+            `~.Axes.imshow` for a detailed description.
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6964,16 +6921,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
 
         Other Parameters
         ----------------
-        cmap : Colormap or str, optional
-            A `.colors.Colormap` instance.  If not set, use rc settings.
-
-        norm : Normalize, optional
-            A `.colors.Normalize` instance is used to
-            scale luminance data to ``[0, 1]``. If not set, defaults to
-            `.colors.Normalize()`.
-
-        vmin/vmax : None or scalar, optional
-            Arguments passed to the `~.colors.Normalize` instance.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters. See `~.Axes.imshow`
+            for a detailed description.
 
         alpha : ``0 <= scalar <= 1`` or ``None``, optional
             The alpha blending value.
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -131,13 +131,9 @@ def __init__(self,
         offset_transform : `~.Transform`, default: `.IdentityTransform`
             A single transform which will be applied to each *offsets* vector
             before it is used.
-        norm : `~.colors.Normalize`, optional
-            Forwarded to `.ScalarMappable`. The default of
-            ``None`` means that the first draw call will set ``vmin`` and
-            ``vmax`` using the minimum and maximum values of the data.
-        cmap : `~.colors.Colormap`, optional
-            Forwarded to `.ScalarMappable`. The default of
-            ``None`` will result in :rc:`image.cmap` being used.
+        cmap, norm
+            Data normalization and colormapping parameters. See
+            `.ScalarMappable` for a detailed description.
         hatch : str, optional
             Hatching pattern to use in filled paths, if any. Valid strings are
             ['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*']. See
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -1635,21 +1635,14 @@ def _initialize_x_y(self, z):
 alpha : float, default: 1
     The alpha blending value, between 0 (transparent) and 1 (opaque).
 
-cmap : str or `.Colormap`, default: :rc:`image.cmap`
-    A `.Colormap` instance or registered colormap name. The colormap
-    maps the level values to colors.
+cmap, norm, vmin, vmax
+    Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
+    for a detailed description.
 
-    If both *colors* and *cmap* are given, an error is raised.
+    *cmap* cannot be given together with *colors*.
 
-norm : `~matplotlib.colors.Normalize`, optional
-    If a colormap is used, the `.Normalize` instance scales the level
-    values to the canonical colormap range [0, 1] for mapping to
-    colors. If not given, the default linear scaling is used.
-
-vmin, vmax : float, optional
-    If not *None*, either or both of these values will be supplied to
-    the `.Normalize` instance, overriding the default color scaling
-    based on *levels*.
+    If *vmin* or *vmax* are not given, the default color scaling is based on
+    *levels*.
 
 origin : {*None*, 'upper', 'lower', 'image'}, default: None
     Determines the orientation and exact position of *Z* by specifying
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2747,16 +2747,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
         alpha : None or float
             The alpha blending value.
 
-        norm : `matplotlib.colors.Normalize`
-            A `.Normalize` instance to map the luminance to the
-            interval [0, 1].
-
-        cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            The colormap to use.
-
-        vmin, vmax : float
-            If *norm* is not given, these values set the data limits for the
-            colormap.
+        cmap, norm, vmin, vmax
+            Data normalization and colormapping parameters for *X*. See
+            `~.Axes.imshow` for a detailed description.
 
         origin : {'upper', 'lower'}, default: :rc:`image.origin`
             Indicates where the [0, 0] index of the array is in the upper left
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -865,7 +865,7 @@ class AxesImage(_ImageBase):
     cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
         The Colormap instance or registered colormap name used to map scalar
         data to colors.
-    norm : `~matplotlib.colors.Normalize`
+    norm : str or `~matplotlib.colors.Normalize`
         Maps luminance to 0-1.
     interpolation : str, default: :rc:`image.interpolation`
         Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
@@ -1216,7 +1216,7 @@ def __init__(self, ax,
         cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
             The Colormap instance or registered colormap name used to map
             scalar data to colors.
-        norm : `~matplotlib.colors.Normalize`
+        norm : str or `~matplotlib.colors.Normalize`
             Maps luminance to 0-1.
         **kwargs : `.Artist` properties
         """
diff --git a/lib/matplotlib/streamplot.py b/lib/matplotlib/streamplot.py
@@ -46,12 +46,10 @@ def streamplot(axes, x, y, u, v, density=1, linewidth=None, color=None,
         The streamline color. If given an array, its values are converted to
         colors using *cmap* and *norm*.  The array must have the same shape
         as *u* and *v*.
-    cmap : `~matplotlib.colors.Colormap`
-        Colormap used to plot streamlines and arrows. This is only used if
-        *color* is an array.
-    norm : `~matplotlib.colors.Normalize`
-        Normalize object used to scale luminance data to 0, 1. If ``None``,
-        stretch (min, max) to (0, 1). This is only used if *color* is an array.
+    cmap, norm
+        Data normalization and colormapping parameters for *color*; only used
+        if *color* is an array of floats. See `~.Axes.imshow` for a detailed
+        description.
     arrowsize : float
         Scaling factor for the arrow size.
     arrowstyle : str
diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -143,21 +143,14 @@ def _contour_args(self, args, kwargs):
 alpha : float, default: 1
     The alpha blending value, between 0 (transparent) and 1 (opaque).
 
-cmap : str or `.Colormap`, default: :rc:`image.cmap`
-    A `.Colormap` instance or registered colormap name. The colormap maps the
-    level values to colors.
+cmap, norm, vmin, vmax
+    Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
+    for a detailed description.
 
-    If both *colors* and *cmap* are given, an error is raised.
+    *cmap* cannot be given together with *colors*.
 
-norm : `~matplotlib.colors.Normalize`, optional
-    If a colormap is used, the `.Normalize` instance scales the level values to
-    the canonical colormap range [0, 1] for mapping to colors. If not given,
-    the default linear scaling is used.
-
-vmin, vmax : float, optional
-    If not *None*, either or both of these values will be supplied to
-    the `.Normalize` instance, overriding the default color scaling
-    based on *levels*.
+    If *vmin* or *vmax* are not given, the default color scaling is based on
+    *levels*.
 
 origin : {*None*, 'upper', 'lower', 'image'}, default: None
     Determines the orientation and exact position of *Z* by specifying the
