Skip to content

Commit 46ec637

Browse files
anntzeranntzer
committed
Tentative norm docs.
1 parent 3ddac4a commit 46ec637

File tree

8 files changed

+74
-145
lines changed

8 files changed

+74
-145
lines changed

‎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: 44 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -4366,21 +4366,10 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43664366
See :mod:`matplotlib.markers` for more information about marker
43674367
styles.
43684368
4369-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4370-
A `.Colormap` instance or registered colormap name. *cmap* is only
4371-
used if *c* is an array of floats.
4372-
4373-
norm : `~matplotlib.colors.Normalize`, default: None
4374-
If *c* is an array of floats, *norm* is used to scale the color
4375-
data, *c*, in the range 0 to 1, in order to map into the colormap
4376-
*cmap*.
4377-
If *None*, use the default `.colors.Normalize`.
4378-
4379-
vmin, vmax : float, default: None
4380-
*vmin* and *vmax* are used in conjunction with the default norm to
4381-
map the color array *c* to the colormap *cmap*. If None, the
4382-
respective min and max of the color array is used.
4383-
It is an error to use *vmin*/*vmax* when *norm* is given.
4369+
cmap, norm, vmin, vmax
4370+
Data normalization and colormapping parameters for *c*; only used
4371+
if *c* is an array of floats. See `~.Axes.imshow` for a detailed
4372+
description.
43844373
43854374
alpha : float, default: None
43864375
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4653,21 +4642,9 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46534642
46544643
Other Parameters
46554644
----------------
4656-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4657-
The Colormap instance or registered colormap name used to map
4658-
the bin values to colors.
4659-
4660-
norm : `~matplotlib.colors.Normalize`, optional
4661-
The Normalize instance scales the bin values to the canonical
4662-
colormap range [0, 1] for mapping to colors. By default, the data
4663-
range is mapped to the colorbar range using linear scaling.
4664-
4665-
vmin, vmax : float, default: None
4666-
The colorbar range. If *None*, suitable min/max values are
4667-
automatically chosen by the `.Normalize` instance (defaults to
4668-
the respective min/max values of the bins in case of the default
4669-
linear scaling).
4670-
It is an error to use *vmin*/*vmax* when *norm* is given.
4645+
cmap, norm, vmin, vmax
4646+
Data normalization and colormapping parameters. See `~.Axes.imshow`
4647+
for a detailed description.
46714648
46724649
alpha : float between 0 and 1, optional
46734650
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5293,6 +5270,10 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52935270
replace_names=["y", "x1", "x2", "where"])
52945271

52955272
#### plotting z(x, y): imshow, pcolor and relatives, contour
5273+
5274+
# Once this deprecation elapses, also move vmin, vmax right after norm, to
5275+
# match the signature of other methods returning ScalarMappables and keep
5276+
# the documentation for *norm*, *vmax* and *vmin* together.
52965277
@_api.make_keyword_only("3.5", "aspect")
52975278
@_preprocess_data()
52985279
def imshow(self, X, cmap=None, norm=None, aspect=None,
@@ -5337,12 +5318,31 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53375318
The Colormap instance or registered colormap name used to map
53385319
scalar data to colors. This parameter is ignored for RGB(A) data.
53395320
5340-
norm : `~matplotlib.colors.Normalize`, optional
5341-
The `.Normalize` instance used to scale scalar data to the [0, 1]
5321+
norm : str or `~matplotlib.colors.Normalize`, optional
5322+
The normalization method used to scale scalar data to the [0, 1]
53425323
range before mapping to colors using *cmap*. By default, a linear
53435324
scaling mapping the lowest value to 0 and the highest to 1 is used.
53445325
This parameter is ignored for RGB(A) data.
53455326
5327+
If given, this can be one of the following:
5328+
5329+
- An instance of `.Normalize` or one of its subclasses
5330+
(see :doc:`/tutorials/colors/colormapnorms`).
5331+
- A scale name, i.e. one of "linear", "log", "symlog", "logit",
5332+
etc. For a full list of available scales call
5333+
`matplotlib.scales.get_scale_names()`.
5334+
In that case, a suitable `.Normalize` subclass is dynamically
5335+
generated and instantiated.
5336+
5337+
vmin, vmax : float, optional
5338+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5339+
define the data range that the colormap covers. By default, the
5340+
colormap covers the complete value range of the supplied data. It
5341+
is an error to use *vmin*/*vmax* when a *norm* instance is given
5342+
(but using a `str` *norm* name together with *vmin*/*vmax* is
5343+
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5344+
ignored.
5345+
53465346
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53475347
The aspect ratio of the Axes. This parameter is particularly
53485348
relevant for images since it determines whether data pixels are
@@ -5401,13 +5401,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
54015401
If *alpha* is an array, the alpha blending values are applied pixel
54025402
by pixel, and *alpha* must have the same shape as *X*.
54035403
5404-
vmin, vmax : float, optional
5405-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5406-
define the data range that the colormap covers. By default,
5407-
the colormap covers the complete value range of the supplied
5408-
data. It is an error to use *vmin*/*vmax* when *norm* is given.
5409-
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
5410-
54115404
origin : {'upper', 'lower'}, default: :rc:`image.origin`
54125405
Place the [0, 0] index of the array in the upper left or lower
54135406
left corner of the Axes. The convention (the default) 'upper' is
@@ -5718,21 +5711,9 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57185711
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57195712
for more description.
57205713
5721-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5722-
A Colormap instance or registered colormap name. The colormap
5723-
maps the *C* values to colors.
5724-
5725-
norm : `~matplotlib.colors.Normalize`, optional
5726-
The Normalize instance scales the data values to the canonical
5727-
colormap range [0, 1] for mapping to colors. By default, the data
5728-
range is mapped to the colorbar range using linear scaling.
5729-
5730-
vmin, vmax : float, default: None
5731-
The colorbar range. If *None*, suitable min/max values are
5732-
automatically chosen by the `.Normalize` instance (defaults to
5733-
the respective min/max values of *C* in case of the default linear
5734-
scaling).
5735-
It is an error to use *vmin*/*vmax* when *norm* is given.
5714+
cmap, norm, vmin, vmax
5715+
Data normalization and colormapping parameters for *C*. See
5716+
`~.Axes.imshow` for a detailed description.
57365717
57375718
edgecolors : {'none', None, 'face', color, color sequence}, optional
57385719
The color of the edges. Defaults to 'none'. Possible values:
@@ -5944,21 +5925,9 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59445925
expanded as needed into the appropriate 2D arrays, making a
59455926
rectangular grid.
59465927
5947-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5948-
A Colormap instance or registered colormap name. The colormap
5949-
maps the *C* values to colors.
5950-
5951-
norm : `~matplotlib.colors.Normalize`, optional
5952-
The Normalize instance scales the data values to the canonical
5953-
colormap range [0, 1] for mapping to colors. By default, the data
5954-
range is mapped to the colorbar range using linear scaling.
5955-
5956-
vmin, vmax : float, default: None
5957-
The colorbar range. If *None*, suitable min/max values are
5958-
automatically chosen by the `.Normalize` instance (defaults to
5959-
the respective min/max values of *C* in case of the default linear
5960-
scaling).
5961-
It is an error to use *vmin*/*vmax* when *norm* is given.
5928+
cmap, norm, vmin, vmax
5929+
Data normalization and colormapping parameters for *C*. See
5930+
`~.Axes.imshow` for a detailed description.
59625931
59635932
edgecolors : {'none', None, 'face', color, color sequence}, optional
59645933
The color of the edges. Defaults to 'none'. Possible values:
@@ -6192,21 +6161,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61926161
61936162
These arguments can only be passed positionally.
61946163
6195-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
6196-
A Colormap instance or registered colormap name. The colormap
6197-
maps the *C* values to colors.
6198-
6199-
norm : `~matplotlib.colors.Normalize`, optional
6200-
The Normalize instance scales the data values to the canonical
6201-
colormap range [0, 1] for mapping to colors. By default, the data
6202-
range is mapped to the colorbar range using linear scaling.
6203-
6204-
vmin, vmax : float, default: None
6205-
The colorbar range. If *None*, suitable min/max values are
6206-
automatically chosen by the `.Normalize` instance (defaults to
6207-
the respective min/max values of *C* in case of the default linear
6208-
scaling).
6209-
It is an error to use *vmin*/*vmax* when *norm* is given.
6164+
cmap, norm, vmin, vmax
6165+
Data normalization and colormapping parameters for *C*. See
6166+
`~.Axes.imshow` for a detailed description.
62106167
62116168
alpha : float, default: None
62126169
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6961,16 +6918,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69616918
69626919
Other Parameters
69636920
----------------
6964-
cmap : Colormap or str, optional
6965-
A `.colors.Colormap` instance. If not set, use rc settings.
6966-
6967-
norm : Normalize, optional
6968-
A `.colors.Normalize` instance is used to
6969-
scale luminance data to ``[0, 1]``. If not set, defaults to
6970-
`.colors.Normalize()`.
6971-
6972-
vmin/vmax : None or scalar, optional
6973-
Arguments passed to the `~.colors.Normalize` instance.
6921+
cmap, norm, vmin, vmax
6922+
Data normalization and colormapping parameters. See `~.Axes.imshow`
6923+
for a detailed description.
69746924
69756925
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69766926
The alpha blending value.

‎lib/matplotlib/collections.py

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

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1631,21 +1631,14 @@ def _initialize_x_y(self, z):
16311631
alpha : float, default: 1
16321632
The alpha blending value, between 0 (transparent) and 1 (opaque).
16331633
1634-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
1635-
A `.Colormap` instance or registered colormap name. The colormap
1636-
maps the level values to colors.
1634+
cmap, norm, vmin, vmax
1635+
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
1636+
for a detailed description.
16371637
1638-
If both *colors* and *cmap* are given, an error is raised.
1638+
*cmap* cannot be given together with *colors*.
16391639
1640-
norm : `~matplotlib.colors.Normalize`, optional
1641-
If a colormap is used, the `.Normalize` instance scales the level
1642-
values to the canonical colormap range [0, 1] for mapping to
1643-
colors. If not given, the default linear scaling is used.
1644-
1645-
vmin, vmax : float, optional
1646-
If not *None*, either or both of these values will be supplied to
1647-
the `.Normalize` instance, overriding the default color scaling
1648-
based on *levels*.
1640+
If *vmin* or *vmax* are not given, the default color scaling is based on
1641+
*levels*.
16491642
16501643
origin : {*None*, 'upper', 'lower', 'image'}, default: None
16511644
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
@@ -2699,16 +2699,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26992699
alpha : None or float
27002700
The alpha blending value.
27012701
2702-
norm : `matplotlib.colors.Normalize`
2703-
A `.Normalize` instance to map the luminance to the
2704-
interval [0, 1].
2705-
2706-
cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
2707-
The colormap to use.
2708-
2709-
vmin, vmax : float
2710-
If *norm* is not given, these values set the data limits for the
2711-
colormap.
2702+
cmap, norm, vmin, vmax
2703+
Data normalization and colormapping parameters for *X*. See
2704+
`~.Axes.imshow` for a detailed description.
27122705
27132706
origin : {'upper', 'lower'}, default: :rc:`image.origin`
27142707
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
@@ -865,7 +865,7 @@ class AxesImage(_ImageBase):
865865
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
866866
The Colormap instance or registered colormap name used to map scalar
867867
data to colors.
868-
norm : `~matplotlib.colors.Normalize`
868+
norm : str or `~matplotlib.colors.Normalize`
869869
Maps luminance to 0-1.
870870
interpolation : str, default: :rc:`image.interpolation`
871871
Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
@@ -1216,7 +1216,7 @@ def __init__(self, ax,
12161216
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
12171217
The Colormap instance or registered colormap name used to map
12181218
scalar data to colors.
1219-
norm : `~matplotlib.colors.Normalize`
1219+
norm : str or `~matplotlib.colors.Normalize`
12201220
Maps luminance to 0-1.
12211221
**kwargs : `.Artist` properties
12221222
"""

‎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+
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

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -143,21 +143,14 @@ def _contour_args(self, args, kwargs):
143143
alpha : float, default: 1
144144
The alpha blending value, between 0 (transparent) and 1 (opaque).
145145
146-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
147-
A `.Colormap` instance or registered colormap name. The colormap maps the
148-
level values to colors.
146+
cmap, norm, vmin, vmax
147+
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
148+
for a detailed description.
149149
150-
If both *colors* and *cmap* are given, an error is raised.
150+
*cmap* cannot be given together with *colors*.
151151
152-
norm : `~matplotlib.colors.Normalize`, optional
153-
If a colormap is used, the `.Normalize` instance scales the level values to
154-
the canonical colormap range [0, 1] for mapping to colors. If not given,
155-
the default linear scaling is used.
156-
157-
vmin, vmax : float, optional
158-
If not *None*, either or both of these values will be supplied to
159-
the `.Normalize` instance, overriding the default color scaling
160-
based on *levels*.
152+
If *vmin* or *vmax* are not given, the default color scaling is based on
153+
*levels*.
161154
162155
origin : {*None*, 'upper', 'lower', 'image'}, default: None
163156
Determines the orientation and exact position of *Z* by specifying the

0 commit comments

Comments
 (0)