Skip to content

Set norms using scale names. #20752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 20, 2022
Merged

Set norms using scale names. #20752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/users/next_whats_new/strnorm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Setting norms with strings
~~~~~~~~~~~~~~~~~~~~~~~~~~
Norms can now be set (e.g. on images) using the string name of the
corresponding scale, e.g. ``imshow(array, norm="log")``. Note that in that
case, it is permissible to also pass *vmin* and *vmax*, as a new Norm instance
will be created under the hood.
148 changes: 54 additions & 94 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4322,6 +4322,7 @@ def invalid_shape_exception(csize, xsize):
"edgecolors", "c", "facecolor",
"facecolors", "color"],
label_namer="y")
@_docstring.interpd
def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
vmin=None, vmax=None, alpha=None, linewidths=None, *,
edgecolors=None, plotnonfinite=False, **kwargs):
Expand Down Expand Up @@ -4368,21 +4369,17 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
See :mod:`matplotlib.markers` for more information about marker
styles.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
A `.Colormap` instance or registered colormap name. *cmap* is only
used if *c* is an array of floats.
%(cmap_doc)s

norm : `~matplotlib.colors.Normalize`, default: None
If *c* is an array of floats, *norm* is used to scale the color
data, *c*, in the range 0 to 1, in order to map into the colormap
*cmap*.
If *None*, use the default `.colors.Normalize`.
This parameter is ignored if *c* is RGB(A).

vmin, vmax : float, default: None
*vmin* and *vmax* are used in conjunction with the default norm to
map the color array *c* to the colormap *cmap*. If None, the
respective min and max of the color array is used.
It is an error to use *vmin*/*vmax* when *norm* is given.
%(norm_doc)s

This parameter is ignored if *c* is RGB(A).

%(vmin_vmax_doc)s

This parameter is ignored if *c* is RGB(A).

alpha : float, default: None
The alpha blending value, between 0 (transparent) and 1 (opaque).
Expand Down Expand Up @@ -4655,21 +4652,11 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,

Other Parameters
----------------
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
The Colormap instance or registered colormap name used to map
the bin values to colors.

norm : `~matplotlib.colors.Normalize`, optional
The Normalize instance scales the bin values to the canonical
colormap range [0, 1] for mapping to colors. By default, the data
range is mapped to the colorbar range using linear scaling.

vmin, vmax : float, default: None
The colorbar range. If *None*, suitable min/max values are
automatically chosen by the `.Normalize` instance (defaults to
the respective min/max values of the bins in case of the default
linear scaling).
It is an error to use *vmin*/*vmax* when *norm* is given.
%(cmap_doc)s

%(norm_doc)s

%(vmin_vmax_doc)s

alpha : float between 0 and 1, optional
The alpha blending value, between 0 (transparent) and 1 (opaque).
Expand Down Expand Up @@ -5295,8 +5282,13 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
replace_names=["y", "x1", "x2", "where"])

#### plotting z(x, y): imshow, pcolor and relatives, contour

# Once this deprecation elapses, also move vmin, vmax right after norm, to
# match the signature of other methods returning ScalarMappables and keep
# the documentation for *norm*, *vmax* and *vmin* together.
@_api.make_keyword_only("3.5", "aspect")
@_preprocess_data()
@_docstring.interpd
def imshow(self, X, cmap=None, norm=None, aspect=None,
interpolation=None, alpha=None,
vmin=None, vmax=None, origin=None, extent=None, *,
Expand Down Expand Up @@ -5335,15 +5327,17 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,

Out-of-range RGB(A) values are clipped.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
The Colormap instance or registered colormap name used to map
scalar data to colors. This parameter is ignored for RGB(A) data.
%(cmap_doc)s

This parameter is ignored if *X* is RGB(A).

norm : `~matplotlib.colors.Normalize`, optional
The `.Normalize` instance used to scale scalar data to the [0, 1]
range before mapping to colors using *cmap*. By default, a linear
scaling mapping the lowest value to 0 and the highest to 1 is used.
This parameter is ignored for RGB(A) data.
%(norm_doc)s

This parameter is ignored if *X* is RGB(A).

%(vmin_vmax_doc)s

This parameter is ignored if *X* is RGB(A).

aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
The aspect ratio of the Axes. This parameter is particularly
Expand Down Expand Up @@ -5403,13 +5397,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
If *alpha* is an array, the alpha blending values are applied pixel
by pixel, and *alpha* must have the same shape as *X*.

vmin, vmax : float, optional
When using scalar data and no explicit *norm*, *vmin* and *vmax*
define the data range that the colormap covers. By default,
the colormap covers the complete value range of the supplied
data. It is an error to use *vmin*/*vmax* when *norm* is given.
When using RGB(A) data, parameters *vmin*/*vmax* are ignored.

origin : {'upper', 'lower'}, default: :rc:`image.origin`
Place the [0, 0] index of the array in the upper left or lower
left corner of the Axes. The convention (the default) 'upper' is
Expand Down Expand Up @@ -5673,7 +5660,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
Parameters
----------
C : 2D array-like
The color-mapped values.
The color-mapped values. Color-mapping is controlled by *cmap*,
*norm*, *vmin*, and *vmax*.

X, Y : array-like, optional
The coordinates of the corners of quadrilaterals of a pcolormesh::
Expand Down Expand Up @@ -5720,21 +5708,11 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
for more description.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
A Colormap instance or registered colormap name. The colormap
maps the *C* values to colors.
%(cmap_doc)s

norm : `~matplotlib.colors.Normalize`, optional
The Normalize instance scales the data values to the canonical
colormap range [0, 1] for mapping to colors. By default, the data
range is mapped to the colorbar range using linear scaling.
%(norm_doc)s

vmin, vmax : float, default: None
The colorbar range. If *None*, suitable min/max values are
automatically chosen by the `.Normalize` instance (defaults to
the respective min/max values of *C* in case of the default linear
scaling).
It is an error to use *vmin*/*vmax* when *norm* is given.
%(vmin_vmax_doc)s

edgecolors : {'none', None, 'face', color, color sequence}, optional
The color of the edges. Defaults to 'none'. Possible values:
Expand Down Expand Up @@ -5915,7 +5893,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
Parameters
----------
C : 2D array-like
The color-mapped values.
The color-mapped values. Color-mapping is controlled by *cmap*,
*norm*, *vmin*, and *vmax*.

X, Y : array-like, optional
The coordinates of the corners of quadrilaterals of a pcolormesh::
Expand Down Expand Up @@ -5946,21 +5925,11 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
expanded as needed into the appropriate 2D arrays, making a
rectangular grid.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
A Colormap instance or registered colormap name. The colormap
maps the *C* values to colors.
%(cmap_doc)s

norm : `~matplotlib.colors.Normalize`, optional
The Normalize instance scales the data values to the canonical
colormap range [0, 1] for mapping to colors. By default, the data
range is mapped to the colorbar range using linear scaling.
%(norm_doc)s

vmin, vmax : float, default: None
The colorbar range. If *None*, suitable min/max values are
automatically chosen by the `.Normalize` instance (defaults to
the respective min/max values of *C* in case of the default linear
scaling).
It is an error to use *vmin*/*vmax* when *norm* is given.
%(vmin_vmax_doc)s

edgecolors : {'none', None, 'face', color, color sequence}, optional
The color of the edges. Defaults to 'none'. Possible values:
Expand Down Expand Up @@ -6150,8 +6119,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
C : array-like
The image data. Supported array shapes are:

- (M, N): an image with scalar data. The data is visualized
using a colormap.
- (M, N): an image with scalar data. Color-mapping is controlled
by *cmap*, *norm*, *vmin*, and *vmax*.
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
i.e. including transparency.
Expand Down Expand Up @@ -6194,21 +6163,17 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,

These arguments can only be passed positionally.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
A Colormap instance or registered colormap name. The colormap
maps the *C* values to colors.
%(cmap_doc)s

This parameter is ignored if *C* is RGB(A).

%(norm_doc)s

This parameter is ignored if *C* is RGB(A).

norm : `~matplotlib.colors.Normalize`, optional
The Normalize instance scales the data values to the canonical
colormap range [0, 1] for mapping to colors. By default, the data
range is mapped to the colorbar range using linear scaling.
%(vmin_vmax_doc)s

vmin, vmax : float, default: None
The colorbar range. If *None*, suitable min/max values are
automatically chosen by the `.Normalize` instance (defaults to
the respective min/max values of *C* in case of the default linear
scaling).
It is an error to use *vmin*/*vmax* when *norm* is given.
This parameter is ignored if *C* is RGB(A).

alpha : float, default: None
The alpha blending value, between 0 (transparent) and 1 (opaque).
Expand Down Expand Up @@ -6963,16 +6928,11 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,

Other Parameters
----------------
cmap : Colormap or str, optional
A `.colors.Colormap` instance. If not set, use rc settings.
%(cmap_doc)s

norm : Normalize, optional
A `.colors.Normalize` instance is used to
scale luminance data to ``[0, 1]``. If not set, defaults to
`.colors.Normalize()`.
%(norm_doc)s

vmin/vmax : None or scalar, optional
Arguments passed to the `~.colors.Normalize` instance.
%(vmin_vmax_doc)s

alpha : ``0 <= scalar <= 1`` or ``None``, optional
The alpha blending value.
Expand Down
Loading