colorbar

matplotlib.colorbar

Colorbar toolkit with two classes and a function:

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

the derived class for use with images or contour plots.

make_axes()

a function for resizing an axes and adding a second axes suitable for a colorbar

The colorbar() method uses make_axes() and Colorbar; the colorbar() function is a thin wrapper over colorbar().

class matplotlib.colorbar.Colorbar(ax, mappable, **kw)

Bases: matplotlib.colorbar.ColorbarBase

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

It is not intended to be instantiated directly; instead, use colorbar() or colorbar() to make your colorbar.

add_lines(CS, erase=True)

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

Set erase to False if these lines should be added to any pre-existing lines.

on_mappable_changed(mappable)

Updates 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()

Remove this colorbar from the figure. If the colorbar was created with use_gridspec=True then restore the gridspec to its previous value.

update_bruteforce(mappable)

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(mappable)

update solid, lines, etc. Unlike update_bruteforce, it does not clear the axes. This is meant to be called when the image or contour plot to which this colorbar belongs is changed.

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

Bases: matplotlib.cm.ScalarMappable

Draw a colorbar in an existing axes.

This is a base class for the Colorbar class, which is the basis for the colorbar() function and the colorbar() method, which are the usual ways of creating a colorbar.

It is also useful by itself for showing a colormap. 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:

colors.Normalize(clip=False)

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

norm=colors.NoNorm.

Useful attributes:

ax

the Axes instance in which the colorbar is drawn

lines

a list of LineCollection if lines were drawn, otherwise an empty list

dividers

a LineCollection if drawedges is True, otherwise None

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

add_lines(levels, colors, linewidths, erase=True)

Draw lines on the colorbar.

colors and linewidths must be scalars or sequences the same length as levels.

Set erase to False to add lines without first removing any previously added lines.

ax = None

The axes that this colorbar lives in.

config_axis()

draw_all()

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

remove()

Remove this colorbar from the figure

set_alpha(alpha)

set_label(label, **kw)

Label the long axis of the colorbar

set_ticklabels(ticklabels, update_ticks=True)

set tick labels. Tick labels are updated immediately unless update_ticks is False. To manually update the ticks, call update_ticks method explicitly.

set_ticks(ticks, update_ticks=True)

set tick locations. Tick locations are updated immediately unless update_ticks is False. To manually update the ticks, call update_ticks method explicitly.

update_ticks()

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)

Bases: matplotlib.colorbar.Colorbar

A Colorbar which is created using Patch rather than the default pcolor().

It uses a list of Patch instances instead of a PatchCollection because the latter does not allow the hatch pattern to vary among the members of the collection.

matplotlib.colorbar.colorbar_factory(cax, mappable, **kwargs)

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

Typically, for automatic colorbar placement given only a mappable use colorbar().

matplotlib.colorbar.make_axes(parents, location=None, orientation=None, fraction=0.15, shrink=1.0, aspect=20, **kw)

Resize and reposition parent axes, and return a child axes suitable for a colorbar:

cax, kw = make_axes(parent, **kw)

Keyword arguments may include the following (with defaults):

location : [None|’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’.

orientation : [None|’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 shrink 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, **kw)

Resize and reposition a parent axes, and return a child axes suitable for a colorbar. This function is similar to make_axes. Prmary differences are

• make_axes_gridspec only handles the orientation keyword and cannot handle the “location” keyword.

• make_axes_gridspec should only be used with a subplot parent.

• make_axes creates an instance of Axes. make_axes_gridspec

  creates an instance of Subplot.

• make_axes updates the position of the

  parent. make_axes_gridspec replaces the grid_spec attribute of the parent with a new one.

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

cax, kw = make_axes_gridspec(parent, **kw)

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 shrink 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.