Axes.colorbar

Axes.colorbar(**kwargs)[source]

Add an inset colorbar or an outer colorbar along the edge of the axes.

Parameters
  • mappable (mappable, sequence of artist, sequence of color-spec, or colormap-spec) – There are four options here:

    1. A mappable object. Basically, any object with a get_cmap method, like the objects returned by contourf and pcolormesh.

    2. A sequence of matplotlib artists. Any object with a get_color method will do, like Line2D instances. A colormap will be generated from the colors of these objects, and colorbar levels will be selected using values. If values is None, we try to infer them by converting the handle labels returned by get_label to float. Otherwise, it is set to np.linspace(0, 1, len(mappable)).

    3. 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. If values is None, it is set to np.linspace(0, 1, len(mappable)).

    4. A Colormap instance. In this case, a colorbar will be drawn using this colormap and with levels determined by values. If values is None, it is set to np.linspace(0, 1, cmap.N).

  • values (sequence of float or str, optional) – Ignored if mappable is a mappable object. This maps each color or plot handle in the mappable 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 is rc['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 or unit-spec, optional) – The colorbar length. For outer colorbars, default is rc['colorbar.length'] = 1.0 and units are relative to the axes width or height. For inset colorbars, default is rc['colorbar.insetlength'] = 8.0 and units are absolute. If float, units are em-widths. If string, interpreted by units.

  • shrink (float, optional) – Alias for length. This is included for consistency with matplotlib.figure.Figure.colorbar.

  • width (unit-spec, optional) – The colorbar width. For outer colorbars, default is rc['colorbar.width'] = 0.2. If float, units are inches. If string, interpreted by units. For inset colorbars, default is rc['colorbar.insetwidth'] = 1.2. If float, units are em-widths. If string, interpreted by units.

  • queue (bool, optional) – If True and loc is the same as an existing colorbar, the input arguments are added to a queue and this function returns None. This is used to “update” the same colorbar with successive ax.colorbar(...) calls. If False (the default) and loc is the same as an existing inset colorbar, the old colorbar is removed. If False and loc 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 by units. When the tight layout algorithm is active for the figure, this is adjusted automatically using pad. 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 is rc['subplots.panelpad'] = 0.5. For inset colorbars, this is the fixed space between the axes edge and the colorbar. Default is rc['colorbar.insetpad'] = 0.7. If float, units are em-widths. If string, interpreted by units.

  • 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 if length is 1.

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 if values is None. The normalizer for converting values to colormap colors. Passed to Norm.

  • norm_kw (dict-like, optional) – The normalizer settings. Passed to Norm.

  • label, title (str, optional) – The colorbar label. The title keyword is also accepted for consistency with legend.

  • reverse (bool, optional) – Whether to reverse the direction of the colorbar. This is done automatically when descending levels are used with DiscreteNorm.

  • rotation (float, optional) – The tick label rotation. Default is 0.

  • grid, edges, drawedges (bool, optional) – Whether to draw level dividers (i.e., gridlines) between each distinct color. Default is rc['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 of extend 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 matplotlib colorbar keyword.

  • extendsize (unit-spec, optional) – The length of the colorbar “extensions” in physical units. Default is rc['colorbar.insetextend'] = 0.9 for inset colorbars and rc['colorbar.extend'] = 1.3 for outer colorbars. If float, units are em-widths. If string, interpreted by units.

  • extendrect (bool, optional) – Whether to draw colorbar “extensions” as rectangles. Default is False (i.e. extensions are drawn as triangles).

  • locator, ticks (locator-spec, optional) – Used to determine the colorbar tick positions. Passed to the Locator 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 of DiscreteNorm levels that should be assigned major ticks. Ignored if locator was passed. Default depends on the colorbar and tick label size. The name maxn was inspired by MaxNLocator.

  • maxn_minor – As with maxn but for minor ticks. Ignored if minorlocator was passed.

  • format, formatter, ticklabels (formatter-spec, optional) – The tick label format. Passed to the Formatter 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 like legend. Default is rc['colorbar.frameon'] = True.

  • tickminor (bool, optional) – Whether to add minor ticks using minorticks_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 is rc['tick.dir'] = 'out'.

  • ticklen (unit-spec, optional) – Major tick lengths for the colorbar ticks. Default is rc['tick.len'] = 4.0.

  • ticklenratio (float, optional) – Relative scaling of ticklen used to determine minor tick lengths. Default is rc['tick.lenratio'] = 0.5.

  • tickwidth (unit-spec, optional) – Major tick widths for the colorbar ticks. Default is linewidth or rc['tick.width'] = 0.6 if linewidth was not passed.

  • tickwidthratio (float, optional) – Relative scaling of tickwidth used to determine minor tick widths. Default is rc['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 from tickloc 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', and rc['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 and rc['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 or float, 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 is rc.edgefix = True. If True, 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 is True but we change this to rc['colorbar.rasterize'] because rasterization can cause misalignment between edges and the level patches.

  • **kwargs – Passed to colorbar.