cmap_changer(self, func, *args, extend='neither', cmap=None, cmap_kw=None, norm=None, norm_kw=None, vmin=None, vmax=None, N=None, levels=None, values=None, symmetric=False, locator=None, locator_kw=None, edgefix=None, labels=False, labels_kw=None, fmt=None, precision=2, colorbar=False, colorbar_kw=None, lw=None, linewidth=None, linewidths=None, ls=None, linestyle=None, linestyles=None, color=None, colors=None, edgecolor=None, edgecolors=None, **kwargs)[source]

Adds several new keyword args and features for specifying the colormap, levels, and normalizers. Uses the DiscreteNorm normalizer to bin data into discrete color levels (see notes).


This function wraps every method that take a cmap argument: parametric, hexbin, contour, contourf, pcolor, pcolormesh, pcolorfast, quiver, streamplot, barbs, imshow, tripcolor, tricontour, tricontourf, hist2d, spy, and matshow

  • extend ({‘neither’, ‘min’, ‘max’, ‘both’}, optional) – Where to assign unique colors to out-of-bounds data and draw “extensions” (triangles, by default) on the colorbar.

  • cmap (colormap spec, optional) – The colormap specifer, passed to the Colormap constructor.

  • cmap_kw (dict-like, optional) – Passed to Colormap.

  • norm (normalizer spec, optional) – The colormap normalizer, used to warp data before passing it to DiscreteNorm. This is passed to the Norm constructor.

  • norm_kw (dict-like, optional) – Passed to Norm.

  • vmin, vmax (float, optional) – Used to determine level locations if levels is an integer. Actual levels may not fall exactly on vmin and vmax, but the minimum level will be no smaller than vmin and the maximum level will be no larger than vmax. If vmin or vmax is not provided, the minimum and maximum data values are used.

  • levels, N (int or list of float, optional) – The number of level edges, or a list of level edges. If the former, locator is used to generate this many levels at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note that decreasing levels will only work with pcolor plots, not contour plots). Default is rc[‘image.levels’] = 11. Note this means you can now discretize your colormap colors in a pcolor plot just like with contourf.

  • values (int or list of float, optional) – The number of level centers, or a list of level centers. If provided, levels are inferred using edges. This will override any levels input.

  • symmetric (bool, optional) – If True, automatically generated levels are symmetric about zero.

  • locator (locator-spec, optional) – The locator used to determine level locations if levels or values is an integer and vmin and vmax were not provided. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.

  • locator_kw (dict-like, optional) – Passed to Locator.

  • edgefix (bool, optional) – Whether to fix the the white-lines-between-filled-contours and white-lines-between-pcolor-rectangles issues. This slows down figure rendering by a bit. Default is rc[‘image.edgefix’] = True.

  • labels (bool, optional) – For contour, whether to add contour labels with clabel. For pcolor or pcolormesh, whether to add labels to the center of grid boxes. In the latter case, the text will be black when the luminance of the underlying grid box color is >50%, and white otherwise.

  • labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour, passed to clabel. For pcolor or pcolormesh, passed to text.

  • fmt (format-spec, optional) – Passed to the Norm constructor, used to format number labels. You can also use the precision keyword arg.

  • precision (int, optional) – Maximum number of decimal places for the number labels. Number labels are generated with the SimpleFormatter formatter, which allows us to limit the precision.

  • colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or panel colorbar from the resulting mappable. If True, the default location is used. Valid locations are described in colorbar.

  • colorbar_kw (dict-like, optional) – Ignored if colorbar is None. Extra keyword args for our call to colorbar.

Other Parameters
  • lw, linewidth, linewidths – The width of contour lines and parametric lines. Also the width of lines between pcolor boxes, pcolormesh boxes, and contourf filled contours.

  • ls, linestyle, linestyles – As above, but for the line style.

  • color, colors, edgecolor, edgecolors – As above, but for the line color. For contourf plots, if you provide colors without specifying the linewidths or linestyles, this argument is used to manually specify the fill colors. See the contourf documentation for details.

  • *args, **kwargs – Passed to the matplotlib plotting method.


The DiscreteNorm normalizer, used with all colormap plots, makes sure that your levels always span the full range of colors in the colormap, whether extend is set to 'min', 'max', 'neither', or 'both'. By default, when extend is not 'both', matplotlib seems to just cut off the most intense colors (reserved for coloring “out of bounds” data), even though they are not being used.

This could also be done by limiting the number of colors in the colormap lookup table by selecting a smaller N (see LinearSegmentedColormap). Instead, we prefer to always build colormaps with high resolution lookup tables, and leave it to the Normalize instance to handle discretization of the color selections.