mpl_toolkits.axes_grid1.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 mpl_toolkits.axes_grid1.colorbar.CbarAxesLocator(locator=None, extend='neither', orientation='vertical')[source]¶

CbarAxesLocator is a axes_locator for colorbar axes. It adjust the position of the axes to make a room for extended ends, i.e., the extended ends are located outside the axes area.

locatorthe bbox returned from the locator is used as a: initial axes location. If None, axes.bbox is used.

extend : same as in ColorbarBase orientation : same as in ColorbarBase

get_end_vertices(self)[source]¶

Return a tuple of two vertices for the colorbar extended ends.

The first vertices is for the minimum end, and the second is for the maximum end.

get_original_position(self, axes, renderer)[source]¶: Return the original position of the axes.

get_path_ends(self)[source]¶: Return the paths for extended ends.

get_path_patch(self)[source]¶: Return the path for axes patch.

class mpl_toolkits.axes_grid1.colorbar.Colorbar(ax, mappable, **kw)[source]¶

Parameters:	norm`matplotlib.colors.Normalize` (or subclass thereof) The normalizing object which scales data, typically into the interval `[0, 1]`. If None, norm defaults to a colors.Normalize object which initializes its scaling based on the first data processed. cmapstr or `Colormap` The colormap used to map normalized data values to RGBA colors.

add_lines(self, CS)[source]¶: Add the lines from a non-filled ContourSet to the colorbar.

update_bruteforce(self, mappable)[source]¶: Update the colorbar artists to reflect the change of the associated mappable.

update_normal(self, 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 mpl_toolkits.axes_grid1.colorbar.ColorbarBase(ax, cmap=None, norm=None, alpha=1.0, values=None, boundaries=None, orientation='vertical', extend='neither', spacing='uniform', ticks=None, format=None, drawedges=False, filled=True)[source]¶

Draw a colorbar in an existing axes.

This is a base class for the Colorbar class, which is the basis for the colorbar() method and pyplot function.

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 LineCollection if lines were drawn, otherwise None

dividers
a LineCollection if drawedges is True, otherwise None

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

Parameters:	norm`matplotlib.colors.Normalize` (or subclass thereof) The normalizing object which scales data, typically into the interval `[0, 1]`. If None, norm defaults to a colors.Normalize object which initializes its scaling based on the first data processed. cmapstr or `Colormap` The colormap used to map normalized data values to RGBA colors.

add_lines(self, levels, colors, linewidths)[source]¶: Draw lines on the colorbar. It deletes preexisting lines.

set_alpha(self, alpha)[source]¶: Set the alpha value for transparency.

set_label_text(self, label, **kw)[source]¶: Label the long axis of the colorbar.

update_artists(self)[source]¶: Update the colorbar associated artists, filled and ends. Note that lines are not updated. This needs to be called whenever clim of associated image changes.

mpl_toolkits.axes_grid1.colorbar.colorbar(mappable, cax=None, ax=None, **kw)[source]¶

Create a colorbar for a ScalarMappable instance.

Documentation for the pyplot thin wrapper:

Add a colorbar to a plot.

Function signatures for the pyplot interface; all but the first are also method signatures for the colorbar() method:

colorbar(**kwargs)
colorbar(mappable, **kwargs)
colorbar(mappable, cax=cax, **kwargs)
colorbar(mappable, ax=ax, **kwargs)

arguments:

mappable
the Image, ContourSet, etc. to which the colorbar applies; this argument is mandatory for the colorbar() method but optional for the colorbar() function, which sets the default to the current image.

keyword arguments:

cax
None | axes object into which the colorbar will be drawn

ax
None | parent axes object from which space for a new colorbar axes will be stolen

Additional keyword arguments are of two kinds:

axes properties:

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

colorbar properties:

Property Description

extend [ 'neither' | 'both' | 'min' | 'max' ] If not 'neither', make pointed end(s) for out-of- range values. These are set for a given colormap using the colormap set_under and set_over methods.

spacing [ 'uniform' | 'proportional' ] Uniform spacing gives each discrete color the same space; proportional makes the space proportional to the data interval.

ticks [ None | list of ticks | Locator object ] If None, ticks are determined automatically from the input.

format [ None | format string | Formatter object ] If None, the ScalarFormatter is used. If a format string is given, e.g., '%.3f', that is used. An alternative Formatter object may be given instead.

drawedges bool Whether to draw lines at color boundaries.

The following will probably be useful only in the context of indexed colors (that is, when the mappable has norm=NoNorm()), or other unusual circumstances.

Property Description

boundaries None or a sequence

values None or a sequence which must be of length 1 less than the sequence of boundaries. For each region delimited by adjacent entries in boundaries, the color mapped to the corresponding value in values will be used.

If mappable is a ContourSet, its extend kwarg is included automatically.

Note that the shrink kwarg provides a simple way to keep a vertical colorbar, for example, from being taller than the axes of the mappable to which the colorbar is attached; but it is a manual method requiring some trial and error. If the colorbar is too tall (or a horizontal colorbar is too wide) use a smaller value of shrink.

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

It is known that some vector graphics viewer (svg and pdf) renders white gaps between segments of the colorbar. This is due to bugs in the viewers not matplotlib. As a workaround the colorbar can be rendered with overlapping segments:

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

However this has negative consequences in other circumstances. Particularly with semi transparent images (alpha < 1) and colorbar extensions and is not enabled by default see (issue #1188).

returns:: Colorbar instance; see also its base class, ColorbarBase. Call the set_label() method to label the colorbar.

The transData of the cax is adjusted so that the limits in the longest axis actually corresponds to the limits in colorbar range. On the other hand, the shortest axis has a data limits of [1,2], whose unconventional value is to prevent underflow when log scale is used.

mpl_toolkits.axes_grid1.colorbar.make_axes(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw)[source]¶

Resize and reposition a 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):

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

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

Returns (cax, kw), the child axes and the reduced kw dictionary.

Property	Description
extend	[ 'neither' \| 'both' \| 'min' \| 'max' ] If not 'neither', make pointed end(s) for out-of- range values. These are set for a given colormap using the colormap set_under and set_over methods.
spacing	[ 'uniform' \| 'proportional' ] Uniform spacing gives each discrete color the same space; proportional makes the space proportional to the data interval.
ticks	[ None \| list of ticks \| Locator object ] If None, ticks are determined automatically from the input.
format	[ None \| format string \| Formatter object ] If None, the `ScalarFormatter` is used. If a format string is given, e.g., '%.3f', that is used. An alternative `Formatter` object may be given instead.
drawedges	bool Whether to draw lines at color boundaries.

Property	Description
boundaries	None or a sequence
values	None or a sequence which must be of length 1 less than the sequence of boundaries. For each region delimited by adjacent entries in boundaries, the color mapped to the corresponding value in values will be used.