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 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.

  • length (float, optional) – The colorbar length. Units are relative to the span of the rows and columns of subplots. Default is rc['colorbar.length'] = 1.0.

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

  • width (unit-spec, optional) – The colorbar width. Default is rc['colorbar.width'] = 0.2. If float, units are inches. If string, interpreted by units.

  • 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 or str, optional) – The fixed space between the colorbar and the subplot grid 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 (float or str, optional) – The tight layout padding between the colorbar and the subplot grid. Default is rc['subplots.innerpad'] = 1.0 for the first colorbar and rc['subplots.panelpad'] = 0.5 for subsequently stacked colorbars. If float, units are em-widths. If string, interpreted by units.

  • 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 or 2-tuple of int, 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, and fig.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 if length is 1.

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. If None, we try to use the extend attribute on the mappable object. If the attribute is unavailable, we use 'neither'.

  • 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.

  • 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.

  • 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 of major and minor colorbar ticks.

  • tickminor (bool, optional) – Whether to add minor ticks using minorticks_on.

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

  • labelsize, labelweight, labelcolor (optional) – The font size, weight, and color for colorbar label text.

  • locator, ticks (locator-spec, optional) – Used to determine the colorbar tick positions. Passed to the Locator constructor function.

  • locator_kw (dict-like, optional) – The locator settings. Passed to Locator.

  • 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) – Used if locator is None. Determines the maximum number of levels that are ticked. Default depends on the colorbar length relative to the font size. The name maxn is meant to be reminiscent of MaxNLocator.

  • maxn_minor – As with maxn, but for the minor ticks.

  • format, formatter, ticklabels (formatter-spec, optional) – The tick label format. Passed to the Formatter constructor function.

  • formatter_kw (dict-like, optional) – The formatter settings. Passed to Formatter.

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

  • ticklabelsize, ticklabelweight, ticklabelcolor (optional) – The font size, weight, and color for colorbar tick labels.

  • grid, edges, drawedges (bool, optional) – Whether to draw level dividers (i.e., gridlines) between each distinct color. Default is rc['colorbar.grid'] = False.

  • frame, frameon (bool, optional) – For inset colorbars only. Indicates whether to draw a “frame”, just like legend. Default is rc['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 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. Default is rc.edgefix = True. If True, a small default linewidth is used to cover up the white lines. If float, this linewidth is used.

  • 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.

  • 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.

  • **kwargs – Passed to colorbar.

See also

proplot.axes.Axes.colorbar, matplotlib.figure.Figure.colorbar