Axes.colorbar¶
- Axes.colorbar(**kwargs)[source]¶
Add an inset colorbar or an outer colorbar along the edge of the axes.
- Parameters
mappable (
mappable
, sequence ofartist
, sequence 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 sequence of matplotlib artists. Any object with a
get_color
method will do, 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 sequence 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 (sequence of
float
orstr
, 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. These can also be strings, in which case the list indices are used for tick locations and the strings are applied as tick labels.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
orunit-spec
, 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 colorbars, default isrc['colorbar.insetlength']
=8.0
and units are absolute. 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 (
unit-spec
, optional) – The colorbar width. For outer colorbars, default isrc['colorbar.width']
=0.2
. If float, units are inches. If string, interpreted byunits
. For inset colorbars, default isrc['colorbar.insetwidth']
=1.2
. 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.space (
unit-spec
, optional) – For outer colorbars only. The fixed space between the colorbar and the subplot edge. 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 (
unit-spec
, optional) – For outer colorbars, this is the tight layout padding between the colorbar and the subplot. 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
.align (
{'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', 'r'}
, optional) – For outer colorbars only. How to align the colorbar against the subplot edge. Default is'center'
. The values'top'
and'bottom'
are valid for left and right colorbars and'left'
and'right'
are valid for top and bottom colorbars. The default is always'center'
. Has no visible effect iflength
is1
.
- Other Parameters
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.norm (
norm-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
.label, title (
str
, optional) – The colorbar label. Thetitle
keyword is also accepted for consistency withlegend
.reverse (
bool
, optional) – Whether to reverse the direction of the colorbar. This is done automatically when descending levels are used withDiscreteNorm
.rotation (
float
, optional) – The tick label rotation. Default is0
.grid, edges, drawedges (
bool
, optional) – Whether to draw level dividers (i.e., gridlines) between each distinct color. Default isrc['colorbar.grid']
=False
.extend (
{'neither', 'both', 'min', 'max'}
, optional) – Direction for drawing colorbar “extensions” (i.e. color keys for out-of-bounds data on the end of the colorbar). Default behavior is to use the value ofextend
passed to the plotting command or use'neither'
if the value is unknown.extendfrac (
float
, optional) – The length of the colorbar “extensions” relative to the length of the colorbar. This is a native matplotlibcolorbar
keyword.extendsize (
unit-spec
, 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. If float, units are em-widths. If string, interpreted byunits
.extendrect (
bool
, optional) – Whether to draw colorbar “extensions” as rectangles. Default isFalse
(i.e. extensions are drawn as triangles).locator, ticks (
locator-spec
, optional) – Used to determine the colorbar tick positions. Passed to theLocator
constructor function.locator_kw (dict-like, optional) – Keyword arguments passed to
matplotlib.ticker.Locator
class.minorlocator, minorticks – As with
locator
,ticks
but for the minor ticks.minorlocator_kw – As with
locator_kw
, but for the minor ticks.maxn (
int
, optional) – The maximum number ofDiscreteNorm
levels that should be assigned major ticks. Ignored iflocator
was passed. Default depends on the colorbar and tick label size. The namemaxn
was inspired byMaxNLocator
.maxn_minor – As with
maxn
but for minor ticks. Ignored ifminorlocator
was passed.format, formatter, ticklabels (
formatter-spec
, optional) – The tick label format. Passed to theFormatter
constructor function.formatter_kw (dict-like, optional) – Keyword arguments passed to
matplotlib.ticker.Formatter
class.frame, frameon (
bool
, optional) – For inset colorbars only. Indicates whether to draw a “frame”, just likelegend
. Default isrc['colorbar.frameon']
=True
.tickminor (
bool
, optional) – Whether to add minor ticks usingminorticks_on
.tickloc, ticklocation (
{'bottom', 'top', 'left', 'right'}
, optional) – Where to draw tick marks on the colorbar. Default is toward the outside of the subplot for outer colorbars and'bottom'
for inset colorbars.tickdir, tickdirection (
{'out', 'in', 'inout'}
, optional) – Direction of major and minor colorbar ticks. Default isrc['tick.dir']
='out'
.ticklen (
unit-spec
, optional) – Major tick lengths for the colorbar ticks. Default isrc['tick.len']
=4.0
.ticklenratio (
float
, optional) – Relative scaling ofticklen
used to determine minor tick lengths. Default isrc['tick.lenratio']
=0.5
.tickwidth (
unit-spec
, optional) – Major tick widths for the colorbar ticks. Default islinewidth
orrc['tick.width']
=0.6
iflinewidth
was not passed.tickwidthratio (
float
, optional) – Relative scaling oftickwidth
used to determine minor tick widths. Default isrc['tick.widthratio']
=0.8
.ticklabelcolor, ticklabelsize, ticklabelweight (optional) – The font color, size, and weight for colorbar tick labels. Defaults are
rc['tick.labelcolor']
='black'
,rc['tick.labelsize']
='medium'
,rc['tick.labelweight']
='normal'
.labelloc, labellocation (
{'bottom', 'top', 'left', 'right'}
) – The colorbar label location. Inherits fromtickloc
by default. Default is toward the outside of the subplot for outer colorbars and'bottom'
for inset colorbars.labelcolor, labelsize, labelweight (optional) – The font color, size, and weight for the colorbar label. Defaults are
rc['label.color']
='black'
,rc['label.size']
='medium'
, andrc['label.weight']
='normal'
.a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth (optional) – For inset colorbars only. Controls the transparency and color of the frame. Defaults are
rc['colorbar.framealpha']
=0.8
andrc['colorbar.framecolor']
.lw, linewidth, c, color (optional) – Controls the line width and edge color for both the colorbar outline and the level dividers.
edgefix (
bool
orfloat
, optional) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this stackoverflow post for a demonstration of the problem. Default isrc.edgefix
=True
. IfTrue
, a small default linewidth is used to cover up the white lines. If float (e.g.edgefix=0.5
), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.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
.