Figure.colorbar¶
- Figure.colorbar(mappable, values=None, loc=None, location=None, row=None, col=None, rows=None, cols=None, span=None, space=None, pad=None, width=None, **kwargs)[source]¶
Draw a colorbar along the side of the figure.
- 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.length (
float
, optional) – The colorbar length. Units are relative to the span of the rows and columns of subplots. Default isrc['colorbar.length']
=1.0
.shrink (
float
, optional) – Alias forlength
. This is included for consistency withmatplotlib.figure.Figure.colorbar
.width (
unit-spec
, optional) – The colorbar width. Default isrc['colorbar.width']
=0.2
. If float, units are inches. If string, interpreted byunits
.loc (
str
, optional) – The colorbar location. Valid location keys are as follows.Location
Valid keys
left
'left'
,'l'
right
'right'
,'r'
bottom
'bottom'
,'b'
top
'top'
,'t'
space (
float
orstr
, optional) – The fixed space between the colorbar and the subplot grid 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 (
float
orstr
, optional) – The tight layout padding between the colorbar and the subplot grid. Default isrc['subplots.innerpad']
=1.0
for the first colorbar andrc['subplots.panelpad']
=0.5
for subsequently stacked colorbars. If float, units are em-widths. If string, interpreted byunits
.row, rows – Aliases for
span
for colorbars on the left or right side.col, cols – Aliases for
span
for colorbars on the top or bottom side.span (
int
or2-tuple
ofint
, optional) – Integer(s) indicating the span of the colorbar across rows and columns of subplots. For example,fig.colorbar(loc='b', col=1)
draws a colorbar beneath the leftmost column of subplots, andfig.colorbar(loc='b', cols=(1,2))
draws a colorbar beneath the left two columns of subplots. By default, the colorbar will span every subplot row and column.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.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).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
.reverse (
bool
, optional) – Whether to reverse the direction of the colorbar. This is done automatically when descending levels are used withDiscreteNorm
.grid, edges, drawedges (
bool
, optional) – Whether to draw level dividers (i.e., gridlines) between each distinct color. Default isrc['colorbar.grid']
=False
.tickminor (
bool
, optional) – Whether to add minor ticks usingminorticks_on
.tickdir, tickdirection (
{'out', 'in', 'inout'}
, optional) – Direction of major and minor colorbar ticks. Default isrc['tick.dir']
='out'
.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.ticklen (
unit-spec
, optional) – Major tick lengths for the colorbar ticks. Default isrc['tick.len']
=4.0
.tickwidth (
unit-spec
, optional) – Major tick widths for the colorbar ticks. Default islinewidth
orrc['tick.width']
=0.6
iflinewidth
was not passed.ticklenratio (
float
, optional) – Relative scaling ofticklen
used to determine minor tick lengths. Default isrc['tick.lenratio']
=0.5
.tickwidthratio (
float
, optional) – Relative scaling oftickwidth
used to determine minor tick widths. Default isrc['tick.widthratio']
=0.8
.label, title (
str
, optional) – The colorbar label. Thetitle
keyword is also accepted for consistency withlegend
.labelloc (
{'bottom', 'top', 'left', 'right'}
) – Where to draw the colorbar label. Inherits fromtickloc
by default.labelsize, labelweight, labelcolor (optional) – The font size, weight, and color for the colorbar label.
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.rotation (
float
, optional) – The tick label rotation. Default is0
.ticklabelsize, ticklabelweight, ticklabelcolor (optional) – The font size, weight, and color for colorbar tick labels.
frame, frameon (
bool
, optional) – For inset colorbars only. Indicates whether to draw a “frame”, just likelegend
. Default isrc['colorbar.frameon']
=True
.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
.