matplotlib.pyplot.colorbar #

matplotlib.pyplot.colorbar(mappable=None,cax=None,ax=None,**kwargs)[source]#

Add a colorbar to a plot.

Parameters:

mappable

Thematplotlib.cm.ScalarMappable (i.e.,AxesImage,ContourSet, etc.) described by this colorbar. This argument ismandatory for theFigure.colorbar method but optional for thepyplot.colorbar function, which sets the default to the currentimage.

Note that one can create aScalarMappable "on-the-fly" togenerate colorbars not attached to a previously drawn artist, e.g.

fig.colorbar(cm.ScalarMappable(norm=norm,cmap=cmap),ax=ax)

caxAxes, optional

Axes into which the colorbar will be drawn. IfNone, then a newAxes is created and the space for it will be stolen from the Axes(s)specified inax.

axAxes or iterable ornumpy.ndarray of Axes, optional

The one or more parent Axes from which space for a new colorbar Axeswill be stolen. This parameter is only used ifcax is not set.

Defaults to the Axes that contains the mappable used to create thecolorbar.

use_gridspecbool, optional

Ifcax isNone, a newcax is created as an instance ofAxes. Ifax is positioned with a subplotspec anduse_gridspecisTrue, thencax is also positioned with a subplotspec.

Returns:

colorbarColorbar

Other Parameters:

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

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

orientationNone or {'vertical', 'horizontal'}

The orientation of the colorbar. It is preferable to set thelocationof the colorbar, as that also determines theorientation; passingincompatible values forlocation andorientation 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.

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), orFalse, optional

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

extend{'neither', 'both', 'min', 'max'}

Make pointed end(s) for out-of-range values (unless 'neither'). These areset for a given colormap using the colormap set_under and set_over methods.

extendfrac{None, 'auto', length, lengths}

If set toNone, both the minimum and maximum triangular colorbarextensions will have a length of 5% of the interior colorbar length (thisis the default setting).

If set to 'auto', makes the triangular colorbar extensions the same lengthsas the interior boxes (whenspacing is set to 'uniform') or the samelengths as the respective adjacent interior boxes (whenspacing is set to'proportional').

If a scalar, indicates the length of both the minimum and maximumtriangular colorbar extensions as a fraction of the interior colorbarlength. A two-element sequence of fractions may also be given, indicatingthe lengths of the minimum and maximum colorbar extensions respectively asa fraction of the interior colorbar length.

extendrectbool

IfFalse the minimum and maximum colorbar extensions will be triangular(the default). IfTrue the extensions will be rectangular.

ticksNone or list of ticks or Locator

If None, ticks are determined automatically from the input.

formatNone or str or Formatter

If None,ScalarFormatter is used.Format strings, e.g.,"%4.2e" or"{x:.2e}", are supported.An alternativeFormatter may be given instead.

drawedgesbool

Whether to draw lines at color boundaries.

labelstr

The label on the colorbar's long axis.

boundaries, valuesNone or a sequence

If unset, the colormap will be displayed on a 0-1 scale.If sequences,values must have a length 1 less thanboundaries. Foreach region delimited by adjacent entries inboundaries, the color mappedto the corresponding value invalues will be used. The size of eachregion is determined by thespacing parameter.Normally only useful for indexed colors (i.e.norm=NoNorm()) or otherunusual circumstances.

spacing{'uniform', 'proportional'}

For discrete colorbars (BoundaryNorm or contours), 'uniform' gives eachcolor the same space; 'proportional' makes the space proportional to thedata interval.

Notes

Note

This is thepyplot wrapper forFigure.colorbar.

Ifmappable is aContourSet, itsextend kwarg isincluded automatically.

Theshrink kwarg provides a simple way to scale the colorbar withrespect to the Axes. Note that ifcax is specified, it determines thesize of the colorbar, andshrink andaspect are ignored.

For more precise control, you can manually specify the positions of theaxes objects in which the mappable and the colorbar are drawn. In thiscase, do not use any of the Axes properties kwargs.

It is known that some vector graphics viewers (svg and pdf) renderwhite gaps between segments of the colorbar. This is due to bugs inthe viewers, not Matplotlib. As a workaround, the colorbar can berendered with overlapping segments:

cbar=colorbar()cbar.solids.set_edgecolor("face")draw()

However, this has negative consequences in other circumstances, e.g.with semi-transparent images (alpha < 1) and colorbar extensions;therefore, this workaround is not used by default (see issue #1188).