Axes.colorbar¶
- Axes.colorbar(**kwargs)[source]¶
Add an inset colorbar or an outer colorbar along the edge of the axes.
- Parameters
mappable (
mappable
,list
ofplot handles
,list
ofcolor-spec
, orcolormap-spec
) – There are four options here:A mappable object. Basically, any object with a
get_cmap
method, like the objects returned bycontourf
andpcolormesh
.A list of “plot handles”. Basically, any object with a
get_color
method, likeLine2D
instances. A colormap will be generated from the colors of these objects, and colorbar levels will be selected usingvalues
. Ifvalues
isNone
, we try to infer them by converting the handle labels returned byget_label
tofloat
. Otherwise, it is set tonp.linspace(0, 1, len(mappable))
.A list of hex strings, color string names, or RGB tuples. A colormap will be generated from these colors, and colorbar levels will be selected using
values
. Ifvalues
isNone
, it is set tonp.linspace(0, 1, len(mappable))
.A
Colormap
instance. In this case, a colorbar will be drawn using this colormap and with levels determined byvalues
. Ifvalues
isNone
, it is set tonp.linspace(0, 1, cmap.N)
.
values (
list
offloat
, optional) – Ignored ifmappable
is a mappable object. This maps each color or plot handle in themappable
list to numeric values, from which a colormap and normalizer are constructed.loc, location (
str
, optional) – The colorbar location. Default isrc['colorbar.loc']
='right'
. Valid location keys are shown in the below table.Location
Valid keys
outer left
'left'
,'l'
outer right
'right'
,'r'
outer bottom
'bottom'
,'b'
outer top
'top'
,'t'
default inset
'best'
,'inset'
,'i'
,0
upper right inset
'upper right'
,'ur'
,1
upper left inset
'upper left'
,'ul'
,2
lower left inset
'lower left'
,'ll'
,3
lower right inset
'lower right'
,'lr'
,4
“filled”
'fill'
length (
float
orstr
, optional) – The colorbar length. For outer colorbars, default isrc['colorbar.length']
=1.0
and units are relative to the axes width or height. For inset default isrc['colorbar.insetlength']
=8.0
. If float, units are em-widths. If string, interpreted byunits
.shrink (
float
, optional) – Alias forlength
. This is included for consistency withmatplotlib.figure.Figure.colorbar
.width (
float
orstr
, optional) – The colorbar width. If string, units are interpreted byunits
. For outer colorbars, default isrc['colorbar.width']
=0.2
, and if float, units are inches. For inset colorbars, default isrc['colorbar.insetwidth']
=1.2
, and if float, units are font size-relative.space (
float
orstr
, optional) – For outer colorbars only. The fixed space between the colorbar and the main axes. If float, units are em-widths. If string, interpreted byunits
. When the tight layout algorithm is active for the figure, this is adjusted automatically usingpad
. Otherwise, a suitable default is selected.pad (
float
orstr
, optional) – The padding between the axes edge and the colorbar. For outer colorbars, this is the tight layout padding. Default isrc['subplots.panelpad']
=0.5
. For inset colorbars, this is the fixed space between the axes edge and the colorbar. Default isrc['colorbar.insetpad']
=0.7
. If float, units are em-widths. If string, interpreted byunits
.queue (
bool
, optional) – IfTrue
andloc
is the same as an existing colorbar, the input arguments are added to a queue and this function returnsNone
. This is used to “update” the same colorbar with successiveax.colorbar(...)
calls. IfFalse
(the default) andloc
is the same as an existing inset colorbar, the old colorbar is removed. IfFalse
andloc
is an outer colorbar, the colorbars are stacked.
- Other Parameters
extend (
{None, 'neither', 'both', 'min', 'max'}
, optional) – Direction for drawing colorbar “extensions” (i.e. references to out-of-bounds data with a unique color). These are triangles by default. IfNone
, we try to use theextend
attribute on the mappable object. If the attribute is unavailable, we use'neither'
.extendsize (
float
orstr
, optional) – The length of the colorbar “extensions” in physical units. Default isrc['colorbar.insetextend']
=0.9
for inset colorbars andrc['colorbar.extend']
=1.3
for outer colorbars. %(units.em)sframe, frameon (
bool
, optional) – For inset colorbars only. Indicates whether to draw a “frame”, just likelegend
. Default isrc['colorbar.frameon']
=True
.lw, linewidth, ec, edgecolor (optional) – Controls the line width and edge color for the colorbar outline and dividers. For inset colorbars, also controls frame properties.
a, alpha, framealpha, fc, facecolor, framecolor (optional) – For inset colorbars only. Controls the transparency and color of the frame. Defaults are
rc['colorbar.framealpha']
=0.8
andrc['colorbar.framecolor']
.norm (
normalizer spec
, optional) – Ignored ifvalues
isNone
. The normalizer for convertingvalues
to colormap colors. Passed toNorm
.norm_kw (dict-like, optional) – The normalizer settings. Passed to
Norm
.reverse (
bool
, optional) – Whether to reverse the direction of the colorbar.tickloc, ticklocation (
{'bottom', 'top', 'left', 'right'}
, optional) – Where to draw tick marks on the colorbar.tickdir, tickdirection (
{'out', 'in', 'inout'}
, optional) – Direction that major and minor tick marks point.tickminor (
bool
, optional) – Whether to add minor ticks to the colorbar withminorticks_on
.grid, edges, drawedges (
bool
, optional) – Whether to draw edges (i.e., gridlines) between each level of the colorbar. Default isrc['colorbar.grid']
=False
.label, title (
str
, optional) – The colorbar label. Thetitle
keyword is also accepted for consistency withlegend
.locator, ticks (
locator spec
, optional) – Used to determine the colorbar tick positions. Passed to theLocator
constructor function.locator_kw (dict-like, optional) – The locator settings. Passed to
Locator
.maxn (
int
, optional) – Used iflocator
isNone
. Determines the maximum number of levels that are ticked. Default depends on the colorbar length relative to the font size. The namemaxn
is meant to be reminiscent ofMaxNLocator
.minorlocator, minorticks – As with
locator
,ticks
but for the minor ticks.minorlocator_kw – As with
locator_kw
, but for the minor ticks.maxn_minor – As with
maxn
, but for the minor ticks.format, formatter, ticklabels (
formatter spec
, optional) – The tick label format. Passed to theFormatter
constructor function.formatter_kw (dict-like, optional) – The formatter settings. Passed to
Formatter
.rotation (
float
, optional) – The tick label rotation. Default is0
.labelsize, labelweight, labelcolor (optional) – The font size, weight, and color for colorbar label text.
ticklabelsize, ticklabelweight, ticklabelcolor (optional) – The font size, weight, and color for colorbar tick labels.
orientation (
{{None, 'horizontal', 'vertical'}}
, optional) – The colorbar orientation. By default this depends on the “side” of the subplot or figure where the colorbar is drawn. Inset colorbars are always horizontal.rasterize (
bool
, optional) – Whether to rasterize the colorbar solids. The matplotlib default isTrue
but we change this torc['colorbar.rasterize']
because rasterization can cause misalignment betweenedges
and the level patches.**kwargs – Passed to
colorbar
.