Figure.colorbar¶
- Figure.colorbar(**kwargs)[source]¶
Add a colorbar along the side of the figure.
- Parameters
mappable (
mappable
,colormap-spec
, sequence ofcolor-spec
, or sequence ofArtist
) – There are four options here:A
ScalarMappable
(e.g., an object returned bycontourf
orpcolormesh
).A
Colormap
or registered colormap name used to build aScalarMappable
on-the-fly. The colorbar range and ticks depend on the argumentsvalues
,vmin
,vmax
, andnorm
. The default for aContinuousColormap
isvmin=0
andvmax=1
(note that passingvalues
will “discretize” the colormap). The default for aDiscreteColormap
isvalues=np.arange(0, cmap.N)
.A sequence of hex strings, color names, or RGB[A] tuples. A
DiscreteColormap
will be generated from these colors and used to build aScalarMappable
on-the-fly. The colorbar range and ticks depend on the argumentsvalues
,norm
, andnorm_kw
. The default isvalues=np.arange(0, len(mappable))
.A sequence of
matplotlib.artist.Artist
instances (e.g., a list ofLine2D
instances returned byplot
). A colormap will be generated from the colors of these objects (where the color is determined byget_color
, if available, orget_facecolor
). The colorbar range and ticks depend on the argumentsvalues
,norm
, andnorm_kw
. The default is to infer colorbar ticks and tick labels by callingget_label
on each artist.
values (sequence of
float
orstr
, optional) – Ignored ifmappable
is aScalarMappable
. This maps the colormap colors to numeric values usingDiscreteNorm
. If the colormap is aContinuousColormap
then its colors will be “discretized”. These 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
, default:rc['colorbar.length']
=1.0
) – The colorbar length. Units are relative to the span of the rows and columns of subplots.shrink (
float
, optional) – Alias forlength
. This is included for consistency withmatplotlib.figure.Figure.colorbar
.width (
unit-spec
, default:rc['colorbar.width']
=0.2
) – The colorbar width. 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
, default:None
) – 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,space
is computed automatically (seepad
). Otherwise,space
is set to a suitable default.pad (
float
orstr
, default:rc['subplots.innerpad']
=1.0
orrc['subplots.panelpad']
=0.5
) – The tight layout padding between the colorbar and the subplot grid. Default isrc['subplots.innerpad']
for the first colorbar andrc['subplots.panelpad']
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
, default:None
) – 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. 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 ifmappable
is aScalarMappable
. This is the continuous normalizer used to scale theContinuousColormap
(or passed toDiscreteNorm
ifvalues
was passed). Passed to theNorm
constructor function.norm_kw (dict-like, optional) – Ignored if
mappable
is aScalarMappable
. These are the normalizer keyword arguments. Passed toNorm
.vmin, vmax (
float
, optional) – Ignored ifmappable
is aScalarMappable
. These are the minimum and maximum colorbar values. Passed toNorm
.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
, default:0
) – The tick label rotation.grid, edges, drawedges (
bool
, default:rc['colorbar.grid']
=False
) – Whether to draw “grid” dividers between each distinct color.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
, default:rc['colorbar.extend']
=1.3
orrc['colorbar.insetextend']
=0.9
) – The length of the colorbar “extensions” in physical units. Default isrc['colorbar.extend']
for outer colorbars andrc['colorbar.insetextend']
for inset colorbars. If float, units are em-widths. If string, interpreted byunits
.extendrect (
bool
, default:False
) – Whether to draw colorbar “extensions” as rectangles. IfFalse
then the extensions are drawn as triangles.locator, ticks (
locator-spec
, optional) – Used to determine the colorbar tick positions. Passed to theLocator
constructor function. By defaultAutoLocator
is used for continuous color levels andDiscreteLocator
is used for discrete color levels.locator_kw (dict-like, optional) – Keyword arguments passed to
matplotlib.ticker.Locator
class.minorlocator, minorticks – As with
locator
,ticks
but for the minor ticks. By defaultAutoMinorLocator
is used for continuous color levels andDiscreteLocator
is used for discrete color levels.minorlocator_kw – As with
locator_kw
, 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) – Keyword arguments passed to
matplotlib.ticker.Formatter
class.frame, frameon (
bool
, default:rc['colorbar.frameon']
=True
) – For inset colorbars only. Indicates whether to draw a “frame”, just likelegend
.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'}
, default:rc['tick.dir']
='out'
) – Direction of major and minor colorbar ticks.ticklen (
unit-spec
, default:rc['tick.len']
=4.0
) – Major tick lengths for the colorbar ticks.ticklenratio (
float
, default:rc['tick.lenratio']
=0.5
) – Relative scaling ofticklen
used to determine minor tick lengths.tickwidth (
unit-spec
, default:linewidth
) – Major tick widths for the colorbar ticks. orrc['tick.width']
=0.6
iflinewidth
was not passed.tickwidthratio (
float
, default:rc['tick.widthratio']
=0.8
) – Relative scaling oftickwidth
used to determine minor tick widths.ticklabelcolor, ticklabelsize, ticklabelweight (default:
rc['tick.labelcolor']
='black'
,rc['tick.labelsize']
='medium'
,rc['tick.labelweight']
='normal'
.) – The font color, size, and weight for colorbar tick labelslabelloc, 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 (default:
rc['label.color']
='black'
,rc['label.size']
='medium'
, andrc['label.weight']
='normal'
.) – The font color, size, and weight for the colorbar label.a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth (default:
rc['colorbar.framealpha']
=0.8
,rc['colorbar.framecolor']
) – For inset colorbars only. Controls the transparency and color of the background frame.lw, linewidth, c, color (optional) – Controls the line width and edge color for both the colorbar outline and the level dividers.
edgefix (
bool
orfloat
, default:rc.edgefix
=True
) – 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 github repo for a demonstration of the problem. IfTrue
, a small default linewidth of0.3
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
, default:rc['colorbar.rasterize']
=False
) – Whether to rasterize the colorbar solids. The matplotlib default wasTrue
but proplot changes this toFalse
since rasterization can cause misalignment between the color patches and the colorbar outline.**kwargs – Passed to
colorbar
.