8000 Tentative norm docs. · matplotlib/matplotlib@7e82efa · GitHub
[go: up one dir, main page]
Skip to content

Commit 7e82efa

Browse files
anntzeranntzer
committed
Tentative norm docs.
1 parent 6dd1229 commit 7e82efa

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
@@ -4360,21 +4360,10 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43604360
See :mod:`matplotlib.markers` for more information about marker
43614361
styles.
43624362
4363-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4364-
A `.Colormap` instance or registered colormap name. *cmap* is only
4365-
used if *c* is an array of floats.
4366-
4367-
norm : `~matplotlib.colors.Normalize`, default: None
4368-
If *c* is an array of floats, *norm* is used to scale the color
4369-
data, *c*, in the range 0 to 1, in order to map into the colormap
4370-
*cmap*.
4371-
If *None*, use the default `.colors.Normalize`.
4372-
4373-
vmin, vmax : float, default: None
4374-
*vmin* and *vmax* are used in conjunction with the default norm to
4375-
map the color array *c* to the colormap *cmap*. If None, the
4376-
respective min and max of the color array is used.
4377-
It is an error to use *vmin*/*vmax* when *norm* is given.
4363+
cmap, norm, vmin, vmax
4364+
Data normalization and colormapping parameters for *c*; only used
4365+
if *c* is an array of floats. See `~.Axes.imshow` for a detailed
4366+
description.
43784367
43794368
alpha : float, default: None
43804369
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4647,21 +4636,9 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46474636
46484637
Other Parameters
46494638
----------------
4650-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4651-
The Colormap instance or registered colormap name used to map
4652-
the bin values to colors.
4653-
4654-
norm : `~matplotlib.colors.Normalize`, optional
4655-
The Normalize instance scales the bin values to the canonical
4656-
colormap range [0, 1] for mapping to colors. By default, the data
4657-
range is mapped to the colorbar range using linear scaling.
4658-
4659-
vmin, vmax : float, default: None
4660-
The colorbar range. If *None*, suitable min/max values are
4661-
automatically chosen by the `.Normalize` instance (defaults to
4662-
the respective min/max values of the bins in case of the default
4663-
linear scaling).
4664-
It is an error to use *vmin*/*vmax* when *norm* is given.
4639+
cmap, norm, vmin, vmax
4640+
Data normalization and colormapping parameters. See `~.Axes.imshow`
4641+
for a detailed description.
46654642
46664643
alpha : float between 0 and 1, optional
46674644
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5287,6 +5264,10 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52875264
replace_names=["y", "x1", "x2", "where"])
52885265

52895266
#### plotting z(x, y): imshow, pcolor and relatives, contour
5267+
5268+
# Once this deprecation elapses, also move vmin, vmax right after norm, to
5269+
# match the signature of other methods returning ScalarMappables and keep
5270+
# the documentation for *norm*, *vmax* and *vmin* together.
52905271
@_api.make_keyword_only("3.5", "aspect")
52915272
@_preprocess_data()
52925273
def imshow(self, X, cmap=None, norm=None, aspect=None,
@@ -5331,12 +5312,31 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53315312
The Colormap instance or registered colormap name used to map
53325313
scalar data to colors. This parameter is ignored for RGB(A) data.
53335314
5334-
norm : `~matplotlib.colors.Normalize`, optional
5335-
The `.Normalize` instance used to scale scalar data to the [0, 1]
5315+
norm : str or `~matplotlib.colors.Normalize`, optional
5316+
The normalization method used to scale scalar data to the [0, 1]
53365317
range before mapping to colors using *cmap*. By default, a linear
53375318
scaling mapping the lowest value to 0 and the highest to 1 is used.
53385319
This parameter is ignored for RGB(A) data.
53395320
5321+
If given, this can be one of the following:
5322+
5323+
- An instance of `.Normalize` or one of its subclasses
5324+
(see :doc:`/tutorials/colors/colormapnorms`).
5325+
- A scale name, i.e. one of "linear", "log", "symlog", "logit",
5326+
etc. For a full list of available scales call
5327+
`matplotlib.scales.get_scale_names()`.
5328+
In that case, a suitable `.Normalize` subclass is dynamically
5329+
generated and instantiated.
5330+
5331+
vmin, vmax : float, optional
5332+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5333+
define the data range that the colormap covers. By default, the
5334+
colormap covers the complete value range of the supplied data. It
5335+
is an error to use *vmin*/*vmax* when a *norm* instance is given
5336+
(but using a `str` *norm* name together with *vmin*/*vmax* is
5337+
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5338+
ignored.
5339+
53405340
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53415341
The aspect ratio of the Axes. This parameter is particularly
53425342
relevant for images since it determines whether data pixels are
@@ -5395,13 +5395,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53955395
If *alpha* is an array, the alpha blending values are applied pixel
53965396
by pixel, and *alpha* must have the same shape as *X*.
53975397
5398-
vmin, vmax : float, optional
5399-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5400-
define the data range that the colormap covers. By default,
5401-
the colormap covers the complete value range of the supplied
5402-
data. It is an error to use *vmin*/*vmax* when *norm* is given.
5403-
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
5404-
54055398
origin : {'upper', 'lower'}, default: :rc:`image.origin`
54065399
Place the [0, 0] index of the array in the upper left or lower
54075400
left corner of the Axes. The convention (the default) 'upper' is
@@ -5711,21 +5704,9 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57115704
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57125705
for more description.
57135706
5714-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5715-
A Colormap instance or registered colormap name. The colormap
5716-
maps the *C* values to colors.
5717-
5718-
norm : `~matplotlib.colors.Normalize`, optional
5719-
The Normalize instance scales the data values to the canonical
5720-
colormap range [0, 1] for mapping to colors. By default, the data
5721-
range is mapped to the colorbar range using linear scaling.
5722-
5723-
vmin, vmax : float, default: None
5724-
The colorbar range. If *None*, suitable min/max values are
5725-
automatically chosen by the `.Normalize` instance (defaults to
5726-
the respective min/max values of *C* in case of the default linear
5727-
scaling).
5728-
It is an error to use *vmin*/*vmax* when *norm* is given.
5707+
cmap, norm, vmin, vmax
5708+
Data normalization and colormapping parameters for *C*. See
5709+
`~.Axes.imshow` for a detailed description.
57295710
57305711
edgecolors : {'none', None, 'face', color, color sequence}, optional
57315712
The color of the edges. Defaults to 'none'. Possible values:
@@ -5937,21 +5918,9 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59375918
expanded as needed into the appropriate 2D arrays, making a
59385919
rectangular grid.
59395920
5940-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5941-
A Colormap instance or registered colormap name. The colormap
5942-
maps the *C* values to colors.
5943-
5944-
norm : `~matplotlib.colors.Normalize`, optional
5945-
The Normalize instance scales the data values to the canonical
5946-
colormap range [0, 1] for mapping to colors. By default, the data
5947-
range is mapped to the colorbar range using linear scaling.
5948-
5949-
vmin, vmax : float, default: None
5950-
The colorbar range. If *None*, suitable min/max values are
5951-
automatically chosen by the `.Normalize` instance (defaults to
5952-
the respective min/max values of *C* in case of the default linear
5953-
scaling).
5954-
It is an error to use *vmin*/*vmax* when *norm* is given.
5921+
cmap, norm, vmin, vmax
5922+
Data normalization and colormapping parameters for *C*. See
5923+
`~.Axes.imshow` for a detailed description.
59555924
59565925
edgecolors : {'none', None, 'face', color, color sequence}, optional
59575926
The color of the edges. Defaults to 'none'. Possible values:
@@ -6185,21 +6154,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61856154
61866155
These arguments can only be passed positionally.
61876156
6188-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
6189-
A Colormap instance or registered colormap name. The colormap
6190-
maps the *C* values to colors.
6191-
6192-
norm : `~matplotlib.colors.Normalize`, optional
6193-
The Normalize instance scales the data values to the canonical
6194-
colormap range [0, 1] for mapping to colors. By default, the data
6195-
range is mapped to the colorbar range using linear scaling.
6196-
6197-
vmin, vmax : float, default: None
6198-
The colorbar range. If *None*, suitable min/max values are
6199-
automatically chosen by the `.Normalize` instance (defaults to
6200-
the respective min/max values of *C* in case of the default linear
6201-
scaling).
6202-
It is an error to use *vmin*/*vmax* when *norm* is given.
6157+
cmap, norm, vmin, vmax
6158+
Data normalization and colormapping parameters for *C*. See
6159+
`~.Axes.imshow` for a detailed description.
62036160
62046161
alpha : float, default: None
62056162
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6954,16 +6911,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69546911
69556912
Other Parameters
69566913
----------------
6957-
cmap : Colormap or str, optional
6958-
A `.colors.Colormap` instance. If not set, use rc settings.
6959-
6960-
norm : Normalize, optional
6961-
A `.colors.Normalize` instance is used to
6962-
scale luminance data to ``[0, 1]``. If not set, defaults to
6963-
`.colors.Normalize()`.
6964-
6965-
vmin/vmax : None or scalar, optional
6966-
Arguments passed to the `~.colors.Normalize` instance.
6914+
cmap, norm, vmin, vmax
6915+
Data normalization and colormapping parameters. See `~.Axes.imshow`
6916+
for a detailed description.
69676917
69686918
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69696919
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
offset_transform : `~.Transform`, default: `.IdentityTransform`
131131
A single transform which will be applied to each *off 2851 sets* 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+
Data normalization and colormapping parameters. See
135+
`.ScalarMappable` for a detailed description.
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
@@ -1629,21 +1629,14 @@ def _initialize_x_y(self, z):
16291629
alpha : float, default: 1
16301630
The alpha blending value, between 0 (transparent) and 1 (opaque).
16311631
1632-
cmap : str or `.Colormap`, default: :rc:`image.cmap`
1633-
A `.Colormap` instance or registered colormap name. The colormap
1634-
maps the level values to colors.
1632+
cmap, norm, vmin, vmax
1633+
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
1634+
for a detailed description.
16351635
1636-
If both *colors* and *cmap* are given, an error is raised.
1636+
*cmap* cannot be given together with *colors*.
16371637
1638-
norm : `~matplotlib.colors.Normalize`, optional
1639-
If a colormap is used, the `.Normalize` instance scales the level
1640-
values to the canonical colormap range [0, 1] for mapping to
1641-
colors. If not given, the default linear scaling is used.
1642-
1643-
vmin, vmax : float, optional
1644-
If not *None*, either or both of these values will be supplied to
1645-
the `.Normalize` instance, overriding the default color scaling
1646-
based on *levels*.
1638+
If *vmin* or *vmax* are not given, the default color scaling is based on
1639+
*levels*.
16471640
16481641
origin : {*None*, 'upper', 'lower', 'image'}, default: None
16491642
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
@@ -2676,16 +2676,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26762676
alpha : None or float
26772677
The alpha blending value.
26782678
2679-
norm : `matplotlib.colors.Normalize`
2680-
A `.Normalize` instance to map the luminance to the
2681-
interval [0, 1].
2682-
2683-
cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
2684-
The colormap to use.
2685-
2686-
vmin, vmax : float
2687-
If *norm* is not given, these values set the data limits for the
2688-
colormap.
2679+
cmap, norm, vmin, vmax
2680+
Data normalization and colormapping parameters for *X*. See
2681+
`~.Axes.imshow` for a detailed description.
26892682
26902683
origin : {'upper', 'lower'}, default: :rc:`image.origin`
26912684
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',
@@ -1213,7 +1213,7 @@ def __init__(self, ax,
12131213
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
12141214
The Colormap instance or registered colormap name used to map
12151215
scalar data to colors.
1216-
norm : `~matplotlib.colors.Normalize`
1216+
norm : str or `~matplotlib.colors.Normalize`
12171217
Maps luminance to 0-1.
12181218
**kwargs : `.Artist` properties
12191219
"""

‎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
@@ -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)
0