Learn what to expect in the new updates
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()
.
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.
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='')¶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.
n_rasterize
= 50¶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.
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.