Skip to content

Commit

Permalink
Set norms using scale names.
Browse files Browse the repository at this point in the history
  • Loading branch information
@anntzer
anntzer committed Jul 20, 2022
1 parent 51ce677 commit 7da2f71
Show file tree
Hide file tree
Showing 12 changed files with 258 additions and 183 deletions.
6 changes: 6 additions & 0 deletions doc/users/next_whats_new/strnorm.rst
View file
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
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

0 comments on commit 7da2f71

Please sign in to comment.