10000 Set norms using scale names. · wsykala/matplotlib@7da2f71 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7da2f71

Browse files
anntzeranntzer
committed
Set norms using scale names.
1 parent 51ce677 commit 7da2f71

File tree

12 files changed

+258
-183
lines changed

12 files changed

+258
-183
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: 54 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -4322,6 +4322,7 @@ def invalid_shape_exception(csize, xsize):
43224322
"edgecolors", "c", "facecolor",
43234323
"facecolors", "color"],
43244324
label_namer="y")
4325+
@_docstring.interpd
43254326
def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43264327
vmin=None, vmax=None, alpha=None, linewidths=None, *,
43274328
edgecolors=None, plotnonfinite=False, **kwargs):
@@ -4368,21 +4369,17 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43684369
See :mod:`matplotlib.markers` for more information about marker
43694370
styles.
43704371
4371-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4372-
A `.Colormap` instance or registered colormap name. *cmap* is only
4373-
used if *c* is an array of floats.
4372+
%(cmap_doc)s
43744373
4375-
norm : `~matplotlib.colors.Normalize`, default: None
4376-
If *c* is an array of floats, *norm* is used to scale the color
4377-
data, *c*, in the range 0 to 1, in order to map into the colormap
4378-
*cmap*.
4379-
If *None*, use the default `.colors.Normalize`.
4374+
This parameter is ignored if *c* is RGB(A).
43804375
4381-
vmin, vmax : float, default: None
4382-
*vmin* and *vmax* are used in conjunction with the default norm to
4383-
map the color array *c* to the colormap *cmap*. If None, the
4384-
respective min and max of the color array is used.
4385-
It is an error to use *vmin*/*vmax* when *norm* is given.
4376+
%(norm_doc)s
4377+
4378+
This parameter is ignored if *c* is RGB(A).
4379+
4380+
%(vmin_vmax_doc)s
4381+
4382+
This parameter is ignored if *c* is RGB(A).
43864383
43874384
alpha : float, default: None
43884385
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4655,21 +4652,11 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46554652
46564653
Other Parameters
46574654
----------------
4658-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
4659-
The Colormap instance or registered colormap name used to map
4660-
the bin values to colors.
4661-
4662-
norm : `~matplotlib.colors.Normalize`, optional
4663-
The Normalize instance scales the bin values to the canonical
4664-
colormap range [0, 1] for mapping to colors. By default, the data
4665-
range is mapped to the colorbar range using linear scaling.
4666-
4667-
vmin, vmax : float, default: None
4668-
The colorbar range. If *None*, suitable min/max values are
4669-
automatically chosen by the `.Normalize` instance (defaults to
4670-
the respective min/max values of the bins in case of the default
4671-
linear scaling).
4672-
It is an error to use *vmin*/*vmax* when *norm* is given.
4655+
%(cmap_doc)s
4656+
4657+
%(norm_doc)s
4658+
4659+
%(vmin_vmax_doc)s
46734660
46744661
alpha : float between 0 and 1, optional
46754662
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5295,8 +5282,13 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52955282
replace_names=["y", "x1", "x2", "where"])
52965283

52975284
#### plotting z(x, y): imshow, pcolor and relatives, contour
5285+
5286+
# Once this deprecation elapses, also move vmin, vmax right after norm, to
5287+
# match the signature of other methods returning ScalarMappables and keep
5288+
# the documentation for *norm*, *vmax* and *vmin* together.
52985289
@_api.make_keyword_only("3.5", "aspect")
52995290
@_preprocess_data()
5291+
@_docstring.interpd
53005292
def imshow(self, X, cmap=None, norm=None, aspect=None,
53015293
interpolation=None, alpha=None,
53025294
vmin=None, vmax=None, origin=None, extent=None, *,
@@ -5335,15 +5327,17 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53355327
53365328
Out-of-range RGB(A) values are clipped.
53375329
5338-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5339-
The Colormap instance or registered colormap name used to map
5340-
scalar data to colors. This parameter is ignored for RGB(A) data.
5330+
%(cmap_doc)s
5331+
5332+
This parameter is ignored if *X* is RGB(A).
53415333
5342-
norm : `~matplotlib.colors.Normalize`, optional
5343-
The `.Normalize` instance used to scale scalar data to the [0, 1]
5344-
range before mapping to colors using *cmap*. By default, a linear
5345-
scaling mapping the lowest value to 0 and the highest to 1 is used.
5346-
This parameter is ignored for RGB(A) data.
5334+
%(norm_doc)s
5335+
5336+
This parameter is ignored if *X* is RGB(A).
5337+
5338+
%(vmin_vmax_doc)s
5339+
5340+
This parameter is ignored if *X* is RGB(A).
53475341
53485342
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53495343
The aspect ratio of the Axes. This parameter is particularly
@@ -5403,13 +5397,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
54035397
If *alpha* is an array, the alpha blending values are applied pixel
54045398
by pixel, and *alpha* must have the same shape as *X*.
54055399
5406-
vmin, vmax : float, optional
5407-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5408-
define the data range that the colormap covers. By default,
5409-
the colormap covers the complete value range of the supplied
5410-
data. It is an error to use *vmin*/*vmax* when *norm* is given.
5411-
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.
5412-
54135400
origin : {'upper', 'lower'}, default: :rc:`image.origin`
54145401
Place the [0, 0] index of the array in the upper left or lower
54155402
left corner of the Axes. The convention (the default) 'upper' is
@@ -5673,7 +5660,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
56735660
Parameters
56745661
----------
56755662
C : 2D array-like
5676-
The color-mapped values.
5663+
The color-mapped values. Color-mapping is controlled by *cmap*,
5664+
*norm*, *vmin*, and *vmax*.
56775665
56785666
X, Y : array-like, optional
56795667
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5720,21 +5708,11 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57205708
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57215709
for more description.
57225710
5723-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5724-
A Colormap instance or registered colormap name. The colormap
5725-
maps the *C* values to colors.
5711+
%(cmap_doc)s
57265712
5727-
norm : `~matplotlib.colors.Normalize`, optional
5728-
The Normalize instance scales the data values to the canonical
5729-
colormap range [0, 1] for mapping to colors. By default, the data
5730-
range is mapped to the colorbar range using linear scaling.
5713+
%(norm_doc)s
57315714
5732-
vmin, vmax : float, default: None
5733-
The colorbar range. If *None*, suitable min/max values are
5734-
automatically chosen by the `.Normalize` instance (defaults to
5735-
the respective min/max values of *C* in case of the default linear
5736-
scaling).
5737-
It is an error to use *vmin*/*vmax* when *norm* is given.
5715+
%(vmin_vmax_doc)s
57385716
57395717
edgecolors : {'none', None, 'face', color, color sequence}, optional
57405718
The color of the edges. Defaults to 'none'. Possible values:
@@ -5915,7 +5893,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59155893
Parameters
59165894
----------
59175895
C : 2D array-like
5918-
The color-mapped values.
5896+
The color-mapped values. Color-mapping is controlled by *cmap*,
5897+
*norm*, *vmin*, and *vmax*.
59195898
59205899
X, Y : array-like, optional
59215900
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5946,21 +5925,11 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59465925
expanded as needed into the appropriate 2D arrays, making a
59475926
rectangular grid.
59485927
5949-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5950-
A Colormap instance or registered colormap name. The colormap
5951-
maps the *C* values to colors.
5928+
%(cmap_doc)s
59525929
5953-
norm : `~matplotlib.colors.Normalize`, optional
5954-
The Normalize instance scales the data values to the canonical
5955-
colormap range [0, 1] for mapping to colors. By default, the data
5956-
range is mapped to the colorbar range using linear scaling.
5930+
%(norm_doc)s
59575931
5958-
vmin, vmax : float, default: None
5959-
The colorbar range. If *None*, suitable min/max values are
5960-
automatically chosen by the `.Normalize` instance (defaults to
5961-
the respective min/max values of *C* in case of the default linear
5962-
scaling).
5963-
It is an error to use *vmin*/*vmax* when *norm* is given.
5932+
%(vmin_vmax_doc)s
59645933
59655934
edgecolors : {'none', None, 'face', color, color sequence}, optional
59665935
The color of the edges. Defaults to 'none'. Possible values:
@@ -6150,8 +6119,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61506119
C : array-like
61516120
The image data. Supported array shapes are:
61526121
6153-
- (M, N): an image with scalar data. The data is visualized
6154-
using a colormap.
6122+
- (M, N): an image with scalar data. Color-mapping is controlled
6123+
by *cmap*, *norm*, *vmin*, and *vmax*.
61556124
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
61566125
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
61576126
i.e. including transparency.
@@ -6194,21 +6163,17 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61946163
61956164
These arguments can only be passed positionally.
61966165
6197-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
6198-
A Colormap instance or registered colormap name. The colormap
6199-
maps the *C* values to colors.
6166+
%(cmap_doc)s
6167+
6168+
This parameter is ignored if *C* is RGB(A).
6169+
6170+
%(norm_doc)s
6171+
6172+
This parameter is ignored if *C* is RGB(A).
62006173
6201-
norm : `~matplotlib.colors.Normalize`, optional
6202-
The Normalize instance scales the data values to the canonical
6203-
colormap range [0, 1] for mapping to colors. By default, the data
6204-
range is mapped to the colorbar range using linear scaling.
6174+
%(vmin_vmax_doc)s
62056175
6206-
vmin, vmax : float, default: None
6207-
The colorbar range. If *None*, suitable min/max values are
6208-
automatically chosen by the `.Normalize` instance (defaults to
6209-
the respective min/max values of *C* in case of the default linear
6210-
scaling).
6211-
It is an error to use *vmin*/*vmax* when *norm* is given.
6176+
This parameter is ignored if *C* is RGB(A).
62126177
62136178
alpha : float, default: None
62146179
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6963,16 +6928,11 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69636928
69646929
Other Parameters
69656930
----------------
6966-
cmap : Colormap or str, optional
6967-
A `.colors.Colormap` instance. If not set, use rc settings.
6931+
%(cmap_doc)s
69686932
6969-
norm : Normalize, optional
6970-
A `.colors.Normalize` instance is used to
6971-
scale luminance data to ``[0, 1]``. If not set, defaults to
6972-
`.colors.Normalize()`.
6933+
%(norm_doc)s
69736934
6974-
vmin/vmax : None or scalar, optional
6975-
Arguments passed to the `~.colors.Normalize` instance.
6935+
%(vmin_vmax_doc)s
69766936
69776937
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69786938
The alpha blending value.

0 commit comments

Comments
 (0)
0