Skip to content

Commit e0de415

Browse files
anntzeranntzer
committed
Tentative norm docs.
1 parent 3c66118 commit e0de415

File tree

8 files changed

+69
-137
lines changed

8 files changed

+69
-137
lines changed

‎doc/users/next_whats_new/strnorm.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Setting norms with strings
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
Norms can now be set (e.g. on images) using the string name of the
4+
corresponding scale, e.g. ``imshow(array, norm="log")``. Note that in that
5+
case, it is permissible to also pass *vmin* and *vmax*, as a new Norm instance
6+
will be created under the hood.

‎lib/matplotlib/axes/_axes.py

+39-86
Original file line numberDiff line numberDiff line change
@@ -4296,21 +4296,10 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
42964296
See :mod:`matplotlib.markers` for more information about marker
42974297
styles.
42984298
4299-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4300-
A `.Colormap` instance or registered colormap name. *cmap* is only
4301-
used if *c* is an array of floats.
4302-
4303-
norm : `~matplotlib.colors.Normalize`, default: None
4304-
If *c* is an array of floats, *norm* is used to scale the color
4305-
data, *c*, in the range 0 to 1, in order to map into the colormap
4306-
*cmap*.
4307-
If *None*, use the default `.colors.Normalize`.
4308-
4309-
vmin, vmax : float, default: None
4310-
*vmin* and *vmax* are used in conjunction with the default norm to
4311-
map the color array *c* to the colormap *cmap*. If None, the
4312-
respective min and max of the color array is used.
4313-
It is an error to use *vmin*/*vmax* when *norm* is given.
4299+
cmap, norm, vmin, vmax
4300+
Data normalization and colormapping parameters for *c*; only used
4301+
if *c* is an array of floats. See `~.Axes.imshow` for a detailed
4302+
description.
43144303
43154304
alpha : float, default: None
43164305
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4583,14 +4572,9 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
45834572
45844573
Other Parameters
45854574
----------------
4586-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4587-
The Colormap instance or registered colormap name used to map
4588-
the bin values to colors.
4589-
4590-
norm : `~matplotlib.colors.Normalize`, optional
4591-
The Normalize instance scales the bin values to the canonical
4592-
colormap range [0, 1] for mapping to colors. By default, the data
4593-
range is mapped to the colorbar range using linear scaling.
4575+
cmap, norm, vmin, vmax
4576+
Data normalization and colormapping parameters. See `~.Axes.imshow`
4577+
for a detailed description.
45944578
45954579
vmin, vmax : float, default: None
45964580
The colorbar range. If *None*, suitable min/max values are
@@ -5283,6 +5267,10 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52835267
replace_names=["y", "x1", "x2", "where"])
52845268

52855269
#### plotting z(x, y): imshow, pcolor and relatives, contour
5270+
5271+
# Once this deprecation elapses, also move vmin, vmax right after norm, to
5272+
# match the signature of other methods returning ScalarMappables and keep
5273+
# the documentation for *norm*, *vmax* and *vmin* together.
52865274
@_api.make_keyword_only("3.5", "aspect")
52875275
@_preprocess_data()
52885276
def imshow(self, X, cmap=None, norm=None, aspect=None,
@@ -5327,12 +5315,27 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53275315
The Colormap instance or registered colormap name used to map
53285316
scalar data to colors. This parameter is ignored for RGB(A) data.
53295317
5330-
norm : `~matplotlib.colors.Normalize`, optional
5318+
norm : str or `~matplotlib.colors.Normalize`, optional
53315319
The `.Normalize` instance used to scale scalar data to the [0, 1]
53325320
range before mapping to colors using *cmap*. By default, a linear
53335321
scaling mapping the lowest value to 0 and the highest to 1 is used.
53345322
This parameter is ignored for RGB(A) data.
53355323
5324+
The normalization can also be given as a str, which should be a
5325+
scale name (as in `~.Axes.set_xscale`, i.e. one of "linear", "log",
5326+
"symlog", "logit", etc.). In that case, a normalization class is
5327+
dynamically generated from the corresponding scale, as if using
5328+
that scale for the image's colorbar.
5329+
5330+
vmin, vmax : float, optional
5331+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5332+
define the data range that the colormap covers. By default, the
5333+
colormap covers the complete value range of the supplied data. It
5334+
is an error to use *vmin*/*vmax* when a *norm* instance is given
5335+
(but using a `str` *norm* name together with *vmin*/*vmax* is
5336+
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5337+
ignored.
5338+
53365339
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53375340
The aspect ratio of the Axes. This parameter is particularly
53385341
relevant for images since it determines whether data pixels are
@@ -5391,13 +5394,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53915394
If *alpha* is an array, the alpha blending values are applied pixel
53925395
by pixel, and *alpha* must have the same shape as *X*.
53935396
5394-
vmin, vmax : float, optional
5395-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5396-
define the data range that the colormap covers. By default,
5397-
the colormap covers the complete value range of the supplied
5398-
data. It is an error to use *vmin*/*vmax* when *norm* is given.
5399-
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
5400-
54015397
origin : {'upper', 'lower'}, default: :rc:`image.origin`
54025398
Place the [0, 0] index of the array in the upper left or lower
54035399
left corner of the Axes. The convention (the default) 'upper' is
@@ -5704,21 +5700,9 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57045700
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57055701
for more description.
57065702
5707-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5708-
A Colormap instance or registered colormap name. The colormap
5709-
maps the *C* values to colors.
5710-
5711-
norm : `~matplotlib.colors.Normalize`, optional
5712-
The Normalize instance scales the data values to the canonical
5713-
colormap range [0, 1] for mapping to colors. By default, the data
5714-
range is mapped to the colorbar range using linear scaling.
5715-
5716-
vmin, vmax : float, default: None
5717-
The colorbar range. If *None*, suitable min/max values are
5718-
automatically chosen by the `.Normalize` instance (defaults to
5719-
the respective min/max values of *C* in case of the default linear
5720-
scaling).
5721-
It is an error to use *vmin*/*vmax* when *norm* is given.
5703+
cmap, norm, vmin, vmax
5704+
Data normalization and colormapping parameters for *C*. See
5705+
`~.Axes.imshow` for a detailed description.
57225706
57235707
edgecolors : {'none', None, 'face', color, color sequence}, optional
57245708
The color of the edges. Defaults to 'none'. Possible values:
@@ -5930,21 +5914,9 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59305914
expanded as needed into the appropriate 2D arrays, making a
59315915
rectangular grid.
59325916
5933-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5934-
A Colormap instance or registered colormap name. The colormap
5935-
maps the *C* values to colors.
5936-
5937-
norm : `~matplotlib.colors.Normalize`, optional
5938-
The Normalize instance scales the data values to the canonical
5939-
colormap range [0, 1] for mapping to colors. By default, the data
5940-
range is mapped to the colorbar range using linear scaling.
5941-
5942-
vmin, vmax : float, default: None
5943-
The colorbar range. If *None*, suitable min/max values are
5944-
automatically chosen by the `.Normalize` instance (defaults to
5945-
the respective min/max values of *C* in case of the default linear
5946-
scaling).
5947-
It is an error to use *vmin*/*vmax* when *norm* is given.
5917+
cmap, norm, vmin, vmax
5918+
Data normalization and colormapping parameters for *C*. See
5919+
`~.Axes.imshow` for a detailed description.
59485920
59495921
edgecolors : {'none', None, 'face', color, color sequence}, optional
59505922
The color of the edges. Defaults to 'none'. Possible values:
@@ -6178,21 +6150,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61786150
61796151
These arguments can only be passed positionally.
61806152
6181-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
6182-
A Colormap instance or registered colormap name. The colormap
6183-
maps the *C* values to colors.
6184-
6185-
norm : `~matplotlib.colors.Normalize`, optional
6186-
The Normalize instance scales the data values to the canonical
6187-
colormap range [0, 1] for mapping to colors. By default, the data
6188-
range is mapped to the colorbar range using linear scaling.
6189-
6190-
vmin, vmax : float, default: None
6191-
The colorbar range. If *None*, suitable min/max values are
6192-
automatically chosen by the `.Normalize` instance (defaults to
6193-
the respective min/max values of *C* in case of the default linear
6194-
scaling).
6195-
It is an error to use *vmin*/*vmax* when *norm* is given.
6153+
cmap, norm, vmin, vmax
6154+
Data normalization and colormapping parameters for *C*. See
6155+
`~.Axes.imshow` for a detailed description.
61966156
61976157
alpha : float, default: None
61986158
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6946,16 +6906,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69466906
69476907
Other Parameters
69486908
----------------
6949-
cmap : Colormap or str, optional
6950-
A `.colors.Colormap` instance. If not set, use rc settings.
6951-
6952-
norm : Normalize, optional
6953-
A `.colors.Normalize` instance is used to
6954-
scale luminance data to ``[0, 1]``. If not set, defaults to
6955-
`.colors.Normalize()`.
6956-
6957-
vmin/vmax : None or scalar, optional
6958-
Arguments passed to the `~.colors.Normalize` instance.
6909+
cmap, norm, vmin, vmax
6910+
Data normalization and colormapping parameters. See `~.Axes.imshow`
6911+
for a detailed description.
69596912
69606913
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69616914
The alpha blending value.

‎lib/matplotlib/collections.py

+3-7
Original file line numberDiff line numberDiff line change
@@ -131,13 +131,9 @@ def __init__(self,
131131
offset_transform : `~.Transform`, default: `.IdentityTransform`
132132
A single transform which will be applied to each *offsets* vector
133133
before it is used.
134-
norm : `~.colors.Normalize`, optional
135-
Forwarded to `.ScalarMappable`. The default of
136-
``None`` means that the first draw call will set ``vmin`` and
137-
``vmax`` using the minimum and maximum values of the data.
138-
cmap : `~.colors.Colormap`, optional
139-
Forwarded to `.ScalarMappable`. The default of
140-
``None`` will result in :rc:`image.cmap` being used.
134+
cmap, norm
135+
Data normalization and colormapping parameters. See
136+
`.ScalarMappable` for a detailed description.
141137
hatch : str, optional
142138
Hatching pattern to use in filled paths, if any. Valid strings are
143139
['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*']. See

‎lib/matplotlib/contour.py

+6-13
Original file line numberDiff line numberDiff line change
@@ -1639,21 +1639,14 @@ def _initialize_x_y(self, z):
16391639
alpha : float, default: 1
16401640
The alpha blending value, between 0 (transparent) and 1 (opaque).
16411641
1642-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
1643-
A `.Colormap` instance or registered colormap name. The colormap
1644-
maps the level values to colors.
1642+
cmap, norm, vmin, vmax
1643+
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
1644+
for a detailed description.
16451645
1646-
If both *colors* and *cmap* are given, an error is raised.
1646+
*cmap* cannot be given together with *colors*.
16471647
1648-
norm : `~matplotlib.colors.Normalize`, optional
1649-
If a colormap is used, the `.Normalize` instance scales the level
1650-
values to the canonical colormap range [0, 1] for mapping to
1651-
colors. If not given, the default linear scaling is used.
1652-
1653-
vmin, vmax : float, optional
1654-
If not *None*, either or both of these values will be supplied to
1655-
the `.Normalize` instance, overriding the default color scaling
1656-
based on *levels*.
1648+
If *vmin* or *vmax* are not given, the default color scaling is based on
1649+
*levels*.
16571650
16581651
origin : {*None*, 'upper', 'lower', 'image'}, default: None
16591652
Determines the orientation and exact position of *Z* by specifying

‎lib/matplotlib/figure.py

+3-10
Original file line numberDiff line numberDiff line change
@@ -2635,16 +2635,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26352635
alpha : None or float
26362636
The alpha blending value.
26372637
2638-
norm : `matplotlib.colors.Normalize`
2639-
A `.Normalize` instance to map the luminance to the
2640-
interval [0, 1].
2641-
2642-
cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
2643-
The colormap to use.
2644-
2645-
vmin, vmax : float
2646-
If *norm* is not given, these values set the data limits for the
2647-
colormap.
2638+
cmap, norm, vmin, vmax
2639+
Data normalization and colormapping parameters for *X*. See
2640+
`~.Axes.imshow` for a detailed description.
26482641
26492642
origin : {'upper', 'lower'}, default: :rc:`image.origin`
26502643
Indicates where the [0, 0] index of the array is in the upper left

‎lib/matplotlib/image.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -844,7 +844,7 @@ class AxesImage(_ImageBase):
844844
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
845845
The Colormap instance or registered colormap name used to map scalar
846846
data to colors.
847-
norm : `~matplotlib.colors.Normalize`
847+
norm : str or `~matplotlib.colors.Normalize`
848848
Maps luminance to 0-1.
849849
interpolation : str, default: :rc:`image.interpolation`
850850
Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
@@ -1194,7 +1194,7 @@ def __init__(self, ax,
11941194
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
11951195
The Colormap instance or registered colormap name used to map
11961196
scalar data to colors.
1197-
norm : `~matplotlib.colors.Normalize`
1197+
norm : str or `~matplotlib.colors.Normalize`
11981198
Maps luminance to 0-1.
11991199
**kwargs : `.Artist` properties
12001200
"""

‎lib/matplotlib/streamplot.py

+4-6
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,10 @@ def streamplot(axes, x, y, u, v, density=1, linewidth=None, color=None,
4646
The streamline color. If given an array, its values are converted to
4747
colors using *cmap* and *norm*. The array must have the same shape
4848
as *u* and *v*.
49-
cmap : `~matplotlib.colors.Colormap`
50-
Colormap used to plot streamlines and arrows. This is only used if
51-
*color* is an array.
52-
norm : `~matplotlib.colors.Normalize`
53-
Normalize object used to scale luminance data to 0, 1. If ``None``,
54-
stretch (min, max) to (0, 1). This is only used if *color* is an array.
49+
cmap, norm
50+
Data normalization and colormapping parameters for *color*; only used
51+
if *color* is an array of floats. See `~.Axes.imshow` for a detailed
52+
description.
5553
arrowsize : float
5654
Scaling factor for the arrow size.
5755
arrowstyle : str

‎lib/matplotlib/tri/tricontour.py

+6-13
Original file line numberDiff line numberDiff line change
@@ -180,21 +180,14 @@ def _contour_args(self, args, kwargs):
180180
alpha : float, default: 1
181181
The alpha blending value, between 0 (transparent) and 1 (opaque).
182182
183-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
184-
A `.Colormap` instance or registered colormap name. The colormap maps the
185-
level values to colors.
183+
cmap, norm, vmin, vmax
184+
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
185+
for a detailed description.
186186
187-
If both *colors* and *cmap* are given, an error is raised.
187+
*cmap* cannot be given together with *colors*.
188188
189-
norm : `~matplotlib.colors.Normalize`, optional
190-
If a colormap is used, the `.Normalize` instance scales the level values to
191-
the canonical colormap range [0, 1] for mapping to colors. If not given,
192-
the default linear scaling is used.
193-
194-
vmin, vmax : float, optional
195-
If not *None*, either or both of these values will be supplied to
196-
the `.Normalize` instance, overriding the default color scaling
197-
based on *levels*.
189+
If *vmin* or *vmax* are not given, the default color scaling is based on
190+
*levels*.
198191
199192
origin : {*None*, 'upper', 'lower', 'image'}, default: None
200193
Determines the orientation and exact position of *Z* by specifying the

0 commit comments

Comments
 (0)