Skip to content

Commit ae7c8e8

Browse files
anntzeranntzer
committed
Tentative norm docs.
1 parent a44db64 commit ae7c8e8

8 files changed

Lines changed: 69 additions & 138 deletions

File tree

‎doc/users/next_whats_new/strnorm.rst‎

Lines changed: 6 additions & 0 deletions
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‎

Lines changed: 39 additions & 87 deletions
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+
The data normalization and colormapping, which are explained in
4301+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
4302+
They are only used if *c* in an array of floats.
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+
The data normalization and colormapping, which are explained in
4577+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
45944578
45954579
vmin, vmax : float, default: None
45964580
The colorbar range. If *None*, suitable min/max values are
@@ -5282,6 +5266,10 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52825266
replace_names=["y", "x1", "x2", "where"])
52835267

52845268
#### plotting z(x, y): imshow, pcolor and relatives, contour
5269+
5270+
# Once this deprecation elapses, also move vmin, vmax right after norm, to
5271+
# match the signature of other methods returning ScalarMappables and keep
5272+
# the documentation for *norm*, *vmax* and *vmin* together.
52855273
@_api.make_keyword_only("3.5", "aspect")
52865274
@_preprocess_data()
52875275
def imshow(self, X, cmap=None, norm=None, aspect=None,
@@ -5326,12 +5314,26 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53265314
The Colormap instance or registered colormap name used to map
53275315
scalar data to colors. This parameter is ignored for RGB(A) data.
53285316
5329-
norm : `~matplotlib.colors.Normalize`, optional
5317+
norm : str or `~matplotlib.colors.Normalize`, optional
53305318
The `.Normalize` instance used to scale scalar data to the [0, 1]
5331-
range before mapping to colors using *cmap*. By default, a linear
5319+
range before mapping to colors using *cmap*. By default, a linear
53325320
scaling mapping the lowest value to 0 and the highest to 1 is used.
53335321
This parameter is ignored for RGB(A) data.
53345322
5323+
The normalization can also be given as a str, which should be a
5324+
scale name. In that case, a normalization class is dynamically
5325+
generated from the corresponding scale, as if using that scale for
5326+
the image's colorbar.
5327+
5328+
vmin, vmax : float, optional
5329+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5330+
define the data range that the colormap covers. By default, the
5331+
colormap covers the complete value range of the supplied data. It
5332+
is an error to use *vmin*/*vmax* when a *norm* instance is given
5333+
(but using a `str` *norm* name together with *vmin*/*vmax* is
5334+
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5335+
ignored.
5336+
53355337
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53365338
The aspect ratio of the Axes. This parameter is particularly
53375339
relevant for images since it determines whether data pixels are
@@ -5390,13 +5392,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53905392
If *alpha* is an array, the alpha blending values are applied pixel
53915393
by pixel, and *alpha* must have the same shape as *X*.
53925394
5393-
vmin, vmax : float, optional
5394-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5395-
define the data range that the colormap covers. By default,
5396-
the colormap covers the complete value range of the supplied
5397-
data. It is an error to use *vmin*/*vmax* when *norm* is given.
5398-
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
5399-
54005395
origin : {'upper', 'lower'}, default: :rc:`image.origin`
54015396
Place the [0, 0] index of the array in the upper left or lower
54025397
left corner of the Axes. The convention (the default) 'upper' is
@@ -5703,21 +5698,9 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57035698
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57045699
for more description.
57055700
5706-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5707-
A Colormap instance or registered colormap name. The colormap
5708-
maps the *C* values to colors.
5709-
5710-
norm : `~matplotlib.colors.Normalize`, optional
5711-
The Normalize instance scales the data values to the canonical
5712-
colormap range [0, 1] for mapping to colors. By default, the data
5713-
range is mapped to the colorbar range using linear scaling.
5714-
5715-
vmin, vmax : float, default: None
5716-
The colorbar range. If *None*, suitable min/max values are
5717-
automatically chosen by the `.Normalize` instance (defaults to
5718-
the respective min/max values of *C* in case of the default linear
5719-
scaling).
5720-
It is an error to use *vmin*/*vmax* when *norm* is given.
5701+
cmap, norm, vmin, vmax
5702+
The data normalization and colormapping, which are explained in
5703+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
57215704
57225705
edgecolors : {'none', None, 'face', color, color sequence}, optional
57235706
The color of the edges. Defaults to 'none'. Possible values:
@@ -5929,21 +5912,9 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59295912
expanded as needed into the appropriate 2D arrays, making a
59305913
rectangular grid.
59315914
5932-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5933-
A Colormap instance or registered colormap name. The colormap
5934-
maps the *C* values to colors.
5935-
5936-
norm : `~matplotlib.colors.Normalize`, optional
5937-
The Normalize instance scales the data values to the canonical
5938-
colormap range [0, 1] for mapping to colors. By default, the data
5939-
range is mapped to the colorbar range using linear scaling.
5940-
5941-
vmin, vmax : float, default: None
5942-
The colorbar range. If *None*, suitable min/max values are
5943-
automatically chosen by the `.Normalize` instance (defaults to
5944-
the respective min/max values of *C* in case of the default linear
5945-
scaling).
5946-
It is an error to use *vmin*/*vmax* when *norm* is given.
5915+
cmap, norm, vmin, vmax
5916+
The data normalization and colormapping, which are explained in
5917+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
59475918
59485919
edgecolors : {'none', None, 'face', color, color sequence}, optional
59495920
The color of the edges. Defaults to 'none'. Possible values:
@@ -6177,21 +6148,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61776148
61786149
These arguments can only be passed positionally.
61796150
6180-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
6181-
A Colormap instance or registered colormap name. The colormap
6182-
maps the *C* values to colors.
6183-
6184-
norm : `~matplotlib.colors.Normalize`, optional
6185-
The Normalize instance scales the data values to the canonical
6186-
colormap range [0, 1] for mapping to colors. By default, the data
6187-
range is mapped to the colorbar range using linear scaling.
6188-
6189-
vmin, vmax : float, default: None
6190-
The colorbar range. If *None*, suitable min/max values are
6191-
automatically chosen by the `.Normalize` instance (defaults to
6192-
the respective min/max values of *C* in case of the default linear
6193-
scaling).
6194-
It is an error to use *vmin*/*vmax* when *norm* is given.
6151+
cmap, norm, vmin, vmax
6152+
The data normalization and colormapping, which are explained in
6153+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
61956154
61966155
alpha : float, default: None
61976156
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6945,16 +6904,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69456904
69466905
Other Parameters
69476906
----------------
6948-
cmap : Colormap or str, optional
6949-
A `.colors.Colormap` instance. If not set, use rc settings.
6950-
6951-
norm : Normalize, optional
6952-
A `.colors.Normalize` instance is used to
6953-
scale luminance data to ``[0, 1]``. If not set, defaults to
6954-
`.colors.Normalize()`.
6955-
6956-
vmin/vmax : None or scalar, optional
6957-
Arguments passed to the `~.colors.Normalize` instance.
6907+
cmap, norm, vmin, vmax
6908+
The data normalization and colormapping, which are explained in
6909+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
69586910
69596911
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69606912
The alpha blending value.

‎lib/matplotlib/collections.py‎

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

‎lib/matplotlib/contour.py‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1642,21 +1642,14 @@ def _initialize_x_y(self, z):
16421642
alpha : float, default: 1
16431643
The alpha blending value, between 0 (transparent) and 1 (opaque).
16441644
1645-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
1646-
A `.Colormap` instance or registered colormap name. The colormap
1647-
maps the level values to colors.
1645+
cmap, norm, vmin, vmax
1646+
The data normalization and colormapping, which are explained in detail in
1647+
the documentation for `~matplotlib.axes.Axes.imshow`.
16481648
1649-
If both *colors* and *cmap* are given, an error is raised.
1649+
*cmap* cannot be given together with *colors*.
16501650
1651-
norm : `~matplotlib.colors.Normalize`, optional
1652-
If a colormap is used, the `.Normalize` instance scales the level
1653-
values to the canonical colormap range [0, 1] for mapping to
1654-
colors. If not given, the default linear scaling is used.
1655-
1656-
vmin, vmax : float, optional
1657-
If not *None*, either or both of these values will be supplied to
1658-
the `.Normalize` instance, overriding the default color scaling
1659-
based on *levels*.
1651+
If *vmin* or *vmax* are not given, the default color scaling is based on
1652+
*levels*.
16601653
16611654
origin : {*None*, 'upper', 'lower', 'image'}, default: None
16621655
Determines the orientation and exact position of *Z* by specifying

‎lib/matplotlib/figure.py‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2567,16 +2567,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
25672567
alpha : None or float
25682568
The alpha blending value.
25692569
2570-
norm : `matplotlib.colors.Normalize`
2571-
A `.Normalize` instance to map the luminance to the
2572-
interval [0, 1].
2573-
2574-
cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
2575-
The colormap to use.
2576-
2577-
vmin, vmax : float
2578-
If *norm* is not given, these values set the data limits for the
2579-
colormap.
2570+
cmap, norm, vmin, vmax
2571+
The data normalization and colormapping, which are explained in
2572+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
25802573
25812574
origin : {'upper', 'lower'}, default: :rc:`image.origin`
25822575
Indicates where the [0, 0] index of the array is in the upper left

‎lib/matplotlib/image.py‎

Lines changed: 2 additions & 2 deletions
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‎

Lines changed: 4 additions & 6 deletions
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+
The data normalization and colormapping, which are explained in
51+
detail in the documentation for `~matplotlib.axes.Axes.imshow`.
52+
They are only used if *color* in an array of floats.
5553
arrowsize : float
5654
Scaling factor for the arrow size.
5755
arrowstyle : str

‎lib/matplotlib/tri/tricontour.py‎

Lines changed: 6 additions & 13 deletions
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+
The data normalization and colormapping, which are explained in detail in
185+
the documentation for `~matplotlib.axes.Axes.imshow`.
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)