# matplotlib.colorbar¶

Colorbars are a visualization of the mapping from scalar values to colors. In Matplotlib they are drawn into a dedicated Axes.

Note

Colorbars are typically created through Figure.colorbar or its pyplot wrapper pyplot.colorbar, which use make_axes and Colorbar internally.

As an end-user, you most likely won't have to call the methods or instantiate the classes in this module explicitly.

ColorbarBase
The base class with full colorbar drawing functionality. It can be used as-is to make a colorbar for a given colormap; a mappable object (e.g., image) is not needed.
Colorbar
On top of ColorbarBase this connects the colorbar with a ScalarMappable such as an image or contour plot.
ColorbarPatch
A specialized Colorbar to support hatched contour plots.
make_axes()
Create an Axes suitable for a colorbar. This functions can be used with figures containing a single axes or with freely placed axes.
make_axes_gridspec()
Create a SubplotBase suitable for a colorbar. This function should be used for adding a colorbar to a GridSpec.
class matplotlib.colorbar.Colorbar(ax, mappable, **kw)[source]

This class connects a ColorbarBase to a ScalarMappable such as an AxesImage generated via imshow.

Note

This class is not intended to be instantiated directly; instead, use Figure.colorbar or pyplot.colorbar to create a colorbar.

add_lines(self, CS, erase=True)[source]

Add the lines from a non-filled ContourSet to the colorbar.

Parameters: CSContourSetThe line positions are taken from the ContourSet levels. The ContourSet must not be filled. erasebool, default: TrueWhether to remove any previously added lines.
on_mappable_changed(self, mappable)[source]

Update this colorbar to match the mappable's properties.

Typically this is automatically registered as an event handler by colorbar_factory() and should not be called manually.

remove(self)[source]

Remove this colorbar from the figure.

If the colorbar was created with use_gridspec=True the previous gridspec is restored.

update_bruteforce(self, mappable)[source]

Destroy and rebuild the colorbar. This is intended to become obsolete, and will probably be deprecated and then removed. It is not called when the pyplot.colorbar function or the Figure.colorbar method are used to create the colorbar.

update_normal(self, mappable)[source]

Update solid patches, lines, etc.

Unlike update_bruteforce, this does not clear the axes. This is meant to be called when the norm of the image or contour plot to which this colorbar belongs changes.

If the norm on the mappable is different than before, this resets the locator and formatter for the axis, so if these have been customized, they will need to be customized again. However, if the norm only changes values of vmin, vmax or cmap then the old formatter and locator will be preserved.

class matplotlib.colorbar.ColorbarBase(ax, cmap=None, norm=None, alpha=None, values=None, boundaries=None, orientation='vertical', ticklocation='auto', extend='neither', spacing='uniform', ticks=None, format=None, drawedges=False, filled=True, extendfrac=None, extendrect=False, label='')[source]

Bases: matplotlib.colorbar._ColorbarMappableDummy

Draw a colorbar in an existing axes.

There are only some rare cases in which you would work directly with a ColorbarBase as an end-user. Typically, colorbars are used with ScalarMappables such as an AxesImage generated via imshow. For these cases you will use Colorbar and likely create it via pyplot.colorbar or Figure.colorbar.

The main application of using a ColorbarBase explicitly is drawing colorbars that are not associated with other elements in the figure, e.g. when showing a colormap by itself.

If the cmap kwarg is given but boundaries and values are left as None, then the colormap will be displayed on a 0-1 scale. To show the under- and over-value colors, specify the norm as:

norm=colors.Normalize(clip=False)


To show the colors versus index instead of on the 0-1 scale, use:

norm=colors.NoNorm()


Useful public methods are set_label() and add_lines().

Parameters: axAxesThe Axes instance in which the colorbar is drawn. cmapColormap or NoneThe colormap to use. If None, use rcParams["image.cmap"] (default: 'viridis'). normNormalize alphafloatThe colorbar transparency between 0 (transparent) and 1 (opaque). values boundaries orientation{'vertical', 'horizontal'} ticklocation{'auto', 'left', 'right', 'top', 'bottom'} extend{'neiter', 'both', 'min', 'max'} spacing{'uniform', 'proportional'} ticksLocator or array-like of float formatstr or Formatter drawedgesbool filledbool extendfrac extendrec labelstr axAxesThe Axes instance in which the colorbar is drawn. lineslistA list of LineCollection if lines were drawn, otherwise an empty list. dividersLineCollectionA LineCollection if drawedges is True, otherwise None.
add_lines(self, levels, colors, linewidths, erase=True)[source]

Draw lines on the colorbar.

The lines are appended to the list lines.

Parameters: levelsarray-likeThe positions of the lines. colorscolor or list of colorsEither a single color applying to all lines or one color value for each line. linewidthsfloat or array-likeEither a single linewidth applying to all lines or one linewidth for each line. erasebool, default: TrueWhether to remove any previously added lines.
config_axis(self)[source]

[Deprecated]

Notes

Deprecated since version 3.3:

draw_all(self)[source]

Calculate any free parameters based on the current cmap and norm, and do all the drawing.

get_ticks(self, minor=False)[source]

Return the x ticks as a list of locations.

minorticks_off(self)[source]

Turn the minor ticks of the colorbar off.

minorticks_on(self)[source]

Turn the minor ticks of the colorbar on without extruding into the "extend regions".

n_rasterize = 50
remove(self)[source]

Remove this colorbar from the figure.

set_alpha(self, alpha)[source]

Set the transparency between 0 (transparent) and 1 (opaque).

set_label(self, label, **kw)[source]

Add a label to the long axis of the colorbar.

set_ticklabels(self, ticklabels, update_ticks=True)[source]

Set tick labels.

Tick labels are updated immediately unless update_ticks is False, in which case one should call update_ticks explicitly.

set_ticks(self, ticks, update_ticks=True)[source]

Set tick locations.

Parameters: ticksarray-like or Locator or NoneThe tick positions can be hard-coded by an array of values; or they can be defined by a Locator. Setting to None reverts to using a default locator. update_ticksbool, default: TrueIf True, tick locations are updated immediately. If False, the user has to call update_ticks later to update the ticks.
update_ticks(self)[source]

Force the update of the ticks and ticklabels. This must be called whenever the tick locator and/or tick formatter changes.

class matplotlib.colorbar.ColorbarPatch(ax, mappable, **kw)[source]

A Colorbar that uses a list of Patch instances rather than the default PatchCollection created by pcolor, because the latter does not allow the hatch pattern to vary among the members of the collection.

matplotlib.colorbar.colorbar_factory(cax, mappable, **kwargs)[source]

Create a colorbar on the given axes for the given mappable.

Note

This is a low-level function to turn an existing axes into a colorbar axes. Typically, you'll want to use colorbar instead, which automatically handles creation and placement of a suitable axes as well.

Parameters: caxAxesThe Axes to turn into a colorbar. mappableScalarMappableThe mappable to be described by the colorbar. **kwargsKeyword arguments are passed to the respective colorbar class. colorbarThe created colorbar instance. ColorbarPatch is only used if mappable is a ContourSet with hatches.
matplotlib.colorbar.make_axes(parents, location=None, orientation=None, fraction=0.15, shrink=1.0, aspect=20, **kw)[source]

Create an Axes suitable for a colorbar.

The axes is placed in the figure of the parents axes, by resizing and repositioning parents.

Keyword arguments may include the following (with defaults):

locationNone or {'left', 'right', 'top', 'bottom'}
The position, relative to parents, where the colorbar axes should be created. If None, the value will either come from the given orientation, else it will default to 'right'.
orientationNone or {'vertical', 'horizontal'}
The orientation of the colorbar. Typically, this keyword shouldn't be used, as it can be derived from the location keyword.
Property Description
orientation vertical or horizontal
fraction 0.15; fraction of original axes to use for colorbar
pad 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes
shrink 1.0; fraction by which to multiply the size of the colorbar
aspect 20; ratio of long to short dimensions
anchor (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal; the anchor point of the colorbar axes
panchor (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal; the anchor point of the colorbar parent axes. If False, the parent axes' anchor will be unchanged

Returns (cax, kw), the child axes and the reduced kw dictionary to be passed when creating the colorbar instance.

matplotlib.colorbar.make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw)[source]

Create a SubplotBase suitable for a colorbar.

The axes is placed in the figure of the parent axes, by resizing and repositioning parent.

This function is similar to make_axes. Primary differences are

While this function is meant to be compatible with make_axes, there could be some minor differences.

Keyword arguments may include the following (with defaults):

orientation
'vertical' or 'horizontal'
Property Description
orientation vertical or horizontal
fraction 0.15; fraction of original axes to use for colorbar
pad 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes
shrink 1.0; fraction by which to multiply the size of the colorbar
aspect 20; ratio of long to short dimensions
anchor (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal; the anchor point of the colorbar axes
panchor (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal; the anchor point of the colorbar parent axes. If False, the parent axes' anchor will be unchanged

All but the first of these are stripped from the input kw set.

Returns (cax, kw), the child axes and the reduced kw dictionary to be passed when creating the colorbar instance.