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.
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, **kwargs)[source]

Bases: matplotlib.colorbar.ColorbarBase

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(CS, erase=True)[source]

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

Parameters:
CSContourSet

The line positions are taken from the ContourSet levels. The ContourSet must not be filled.

erasebool, default: True

Whether to remove any previously added lines.

on_mappable_changed(mappable)[source]

[Deprecated] 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.

Notes

Deprecated since version 3.3.

remove()[source]

Remove this colorbar from the figure.

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

update_bruteforce(mappable)[source]

[Deprecated] 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.

Notes

Deprecated since version 3.3.

update_normal(mappable)[source]

Update solid patches, lines, etc.

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=None, spacing='uniform', ticks=None, format=None, drawedges=False, filled=True, extendfrac=None, extendrect=False, label='')[source]

Bases: object

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:
axAxes

The Axes instance in which the colorbar is drawn.

cmapColormap, default: rcParams["image.cmap"] (default: 'viridis')

The colormap to use.

normNormalize
alphafloat

The colorbar transparency between 0 (transparent) and 1 (opaque).

values
boundaries
orientation{'vertical', 'horizontal'}
ticklocation{'auto', 'left', 'right', 'top', 'bottom'}
extend{'neither', 'both', 'min', 'max'}
spacing{'uniform', 'proportional'}
ticksLocator or array-like of float
formatstr or Formatter
drawedgesbool
filledbool
extendfrac
extendrec
labelstr
Attributes:
axAxes

The Axes instance in which the colorbar is drawn.

lineslist

A list of LineCollection (empty if no lines were drawn).

dividersLineCollection

A LineCollection (empty if drawedges is False).

add_lines(levels, colors, linewidths, erase=True)[source]

Draw lines on the colorbar.

The lines are appended to the list lines.

Parameters:
levelsarray-like

The positions of the lines.

colorscolor or list of colors

Either a single color applying to all lines or one color value for each line.

linewidthsfloat or array-like

Either a single linewidth applying to all lines or one linewidth for each line.

erasebool, default: True

Whether to remove any previously added lines.

property config_axis
draw_all()[source]

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

get_ticks(minor=False)[source]

Return the x ticks as a list of locations.

minorticks_off()[source]

Turn the minor ticks of the colorbar off.

minorticks_on()[source]

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

n_rasterize = 50
remove()[source]

Remove this colorbar from the figure.

set_alpha(alpha)[source]

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

set_label(label, *, loc=None, **kwargs)[source]

Add a label to the long axis of the colorbar.

Parameters:
labelstr

The label text.

locstr, optional

The location of the label.

  • For horizontal orientation one of {'left', 'center', 'right'}
  • For vertical orientation one of {'bottom', 'center', 'top'}

Defaults to rcParams["xaxis.labellocation"] (default: 'center') or rcParams["yaxis.labellocation"] (default: 'center') depending on the orientation.

**kwargs

Keyword arguments are passed to set_xlabel / set_ylabel. Supported keywords are labelpad and Text properties.

set_ticklabels(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(ticks, update_ticks=True)[source]

Set tick locations.

Parameters:
ticksarray-like or Locator or None

The 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: True

If True, tick locations are updated immediately. If False, the user has to call update_ticks later to update the ticks.

update_ticks()[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, **kwargs)[source]

Bases: matplotlib.colorbar.Colorbar

[Deprecated]

Notes

Deprecated since version 3.4:

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

[Deprecated] 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:
caxAxes

The Axes to turn into a colorbar.

mappableScalarMappable

The mappable to be described by the colorbar.

**kwargs

Keyword arguments are passed to the respective colorbar class.

Returns:
Colorbar

The created colorbar instance.

Notes

Deprecated since version 3.4.

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.

Parameters:
parentsAxes or list of Axes

The Axes to use as parents for placing the colorbar.

locationNone or {'left', 'right', 'top', 'bottom'}

The location, relative to the parent axes, where the colorbar axes is created. It also determines the orientation of the colorbar (colorbars on the left and right are vertical, colorbars at the top and bottom are horizontal). If None, the location will come from the orientation if it is set (vertical colorbars on the right, horizontal ones at the bottom), or default to 'right' if orientation is unset.

orientationNone or {'vertical', 'horizontal'}

The orientation of the colorbar. It is preferable to set the location of the colorbar, as that also determines the orientation; passing incompatible values for location and orientation raises an exception.

fractionfloat, default: 0.15

Fraction of original axes to use for colorbar.

shrinkfloat, default: 1.0

Fraction by which to multiply the size of the colorbar.

aspectfloat, default: 20

Ratio of long to short dimensions.

Returns:
caxAxes

The child axes.

kwdict

The reduced keyword dictionary to be passed when creating the colorbar instance.

Other Parameters:
padfloat, default: 0.05 if vertical, 0.15 if horizontal

Fraction of original axes between colorbar and new image axes.

anchor(float, float), optional

The anchor point of the colorbar axes. Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.

panchor(float, float), or False, optional

The anchor point of the colorbar parent axes. If False, the parent axes' anchor will be unchanged. Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.

matplotlib.colorbar.make_axes_gridspec(parent, *, location=None, orientation=None, 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.

Parameters:
parentAxes

The Axes to use as parent for placing the colorbar.

locationNone or {'left', 'right', 'top', 'bottom'}

The location, relative to the parent axes, where the colorbar axes is created. It also determines the orientation of the colorbar (colorbars on the left and right are vertical, colorbars at the top and bottom are horizontal). If None, the location will come from the orientation if it is set (vertical colorbars on the right, horizontal ones at the bottom), or default to 'right' if orientation is unset.

orientationNone or {'vertical', 'horizontal'}

The orientation of the colorbar. It is preferable to set the location of the colorbar, as that also determines the orientation; passing incompatible values for location and orientation raises an exception.

fractionfloat, default: 0.15

Fraction of original axes to use for colorbar.

shrinkfloat, default: 1.0

Fraction by which to multiply the size of the colorbar.

aspectfloat, default: 20

Ratio of long to short dimensions.

Returns:
caxSubplotBase

The child axes.

kwdict

The reduced keyword dictionary to be passed when creating the colorbar instance.

Other Parameters:
padfloat, default: 0.05 if vertical, 0.15 if horizontal

Fraction of original axes between colorbar and new image axes.

anchor(float, float), optional

The anchor point of the colorbar axes. Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.

panchor(float, float), or False, optional

The anchor point of the colorbar parent axes. If False, the parent axes' anchor will be unchanged. Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.