### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »

# colorbar

## `matplotlib.colorbar`

Colorbar toolkit with two classes and a function:

> `ColorbarBase`
>   the base class with full colorbar drawing functionality. It can be used as-is to make a colorbar for a given colormap; a mappable object (e.g., image) is not needed.
> `Colorbar`
>   the derived class for use with images or contour plots.
> `make_axes()`
>   a function for resizing an axes and adding a second axes suitable for a colorbar

The `colorbar()` method uses `make_axes()` and `Colorbar`; the `colorbar()` function is a thin wrapper over `colorbar()`.

class `matplotlib.colorbar.``Colorbar`(ax, mappable, **kw)

  Bases: `matplotlib.colorbar.ColorbarBase`

  This class connects a `ColorbarBase` to a `ScalarMappable` such as a `AxesImage` generated via `imshow()`.

  It is not intended to be instantiated directly; instead, use `colorbar()` or `colorbar()` to make your colorbar.

  `add_lines`(CS, erase=True)

    Add the lines from a non-filled `ContourSet` to the colorbar.

    Set erase to False if these lines should be added to any pre-existing lines.

  `on_mappable_changed`(mappable)

    Updates this colorbar to match the mappable’s properties.

    Typically this is automatically registered as an event handler by `colorbar_factory()` and should not be called manually.

  `remove`()

    Remove this colorbar from the figure. If the colorbar was created with `use_gridspec=True` then restore the gridspec to its previous value.

  `update_bruteforce`(mappable)

    Destroy and rebuild the colorbar. This is intended to become obsolete, and will probably be deprecated and then removed. It is not called when the pyplot.colorbar function or the Figure.colorbar method are used to create the colorbar.

  `update_normal`(mappable)

    update solid, lines, etc. Unlike update_bruteforce, it does not clear the axes. This is meant to be called when the image or contour plot to which this colorbar belongs is changed.

class `matplotlib.colorbar.``ColorbarBase`(ax, cmap=None, norm=None, alpha=None, values=None, boundaries=None, orientation=’vertical’, ticklocation=’auto’, extend=’neither’, spacing=’uniform’, ticks=None, format=None, drawedges=False, filled=True, extendfrac=None, extendrect=False, label=”)

  Bases: `matplotlib.cm.ScalarMappable`

  Draw a colorbar in an existing axes.

  This is a base class for the `Colorbar` class, which is the basis for the `colorbar()` function and the `colorbar()` method, which are the usual ways of creating a colorbar.

  It is also useful by itself for showing a colormap. If the cmap kwarg is given but boundaries and values are left as None, then the colormap will be displayed on a 0-1 scale. To show the under- and over-value colors, specify the norm as:

      colors.Normalize(clip=False)

  To show the colors versus index instead of on the 0-1 scale, use:

      norm=colors.NoNorm.

  Useful attributes:

  > `ax`
  >   the Axes instance in which the colorbar is drawn
  > `lines`
  >   a list of LineCollection if lines were drawn, otherwise an empty list
  > `dividers`
  >   a LineCollection if drawedges is True, otherwise None

  Useful public methods are `set_label()` and `add_lines()`.

  `add_lines`(levels, colors, linewidths, erase=True)

    Draw lines on the colorbar.

    colors and linewidths must be scalars or sequences the same length as levels.

    Set erase to False to add lines without first removing any previously added lines.

  `ax` = None

    The axes that this colorbar lives in.

  `config_axis`()
  `draw_all`()

    Calculate any free parameters based on the current cmap and norm, and do all the drawing.

  `get_ticks`(minor=False)

    Return the x ticks as a list of locations

  `n_rasterize` = 50
  `remove`()

    Remove this colorbar from the figure

  `set_alpha`(alpha)
  `set_label`(label, **kw)

    Label the long axis of the colorbar

  `set_ticklabels`(ticklabels, update_ticks=True)

    set tick labels. Tick labels are updated immediately unless update_ticks is False. To manually update the ticks, call update_ticks method explicitly.

  `set_ticks`(ticks, update_ticks=True)

    Set tick locations.

    Parameters: | ticks : {None, sequence, `Locator` instance} If None, a default Locator will be used. update_ticks : {True, False}, optional If True, tick locations are updated immediately. If False, use `update_ticks()` to manually update the ticks.

  `update_ticks`()

    Force the update of the ticks and ticklabels. This must be called whenever the tick locator and/or tick formatter changes.

class `matplotlib.colorbar.``ColorbarPatch`(ax, mappable, **kw)

  Bases: `matplotlib.colorbar.Colorbar`

  A Colorbar which is created using `Patch` rather than the default `pcolor()`.

  It uses a list of Patch instances instead of a `PatchCollection` because the latter does not allow the hatch pattern to vary among the members of the collection.

`matplotlib.colorbar.``colorbar_factory`(cax, mappable, **kwargs)

  Creates a colorbar on the given axes for the given mappable.

  Typically, for automatic colorbar placement given only a mappable use `colorbar()`.

`matplotlib.colorbar.``make_axes`(parents, location=None, orientation=None, fraction=0.15, shrink=1.0, aspect=20, **kw)

  Resize and reposition parent axes, and return a child axes suitable for a colorbar.

  Keyword arguments may include the following (with defaults):

  > location : [None|’left’|’right’|’top’|’bottom’]
  >   The position, relative to parents, where the colorbar axes should be created. If None, the value will either come from the given `orientation`, else it will default to ‘right’.
  > orientation : [None|’vertical’|’horizontal’]
  >   The orientation of the colorbar. Typically, this keyword shouldn’t be used, as it can be derived from the `location` keyword.

  Property | Description
  --- | ---
  orientation | vertical or horizontal
  fraction | 0.15; fraction of original axes to use for colorbar
  pad | 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes
  shrink | 1.0; fraction by which to shrink the colorbar
  aspect | 20; ratio of long to short dimensions
  anchor | (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal; the anchor point of the colorbar axes
  panchor | (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal; the anchor point of the colorbar parent axes. If False, the parent axes’ anchor will be unchanged

  Returns (cax, kw), the child axes and the reduced kw dictionary to be passed when creating the colorbar instance.

`matplotlib.colorbar.``make_axes_gridspec`(parent, **kw)

  Resize and reposition a parent axes, and return a child axes suitable for a colorbar. This function is similar to make_axes. Prmary differences are

  > - make_axes_gridspec only handles the orientation keyword and cannot handle the “location” keyword.

  > - make_axes_gridspec should only be used with a subplot parent.

  > - make_axes creates an instance of Axes. make_axes_gridspec

  >     creates an instance of Subplot.

  > - make_axes updates the position of the

  >     parent. make_axes_gridspec replaces the grid_spec attribute of the parent with a new one.

  While this function is meant to be compatible with make_axes, there could be some minor differences.

  Keyword arguments may include the following (with defaults):

  > orientation
  >   ‘vertical’ or ‘horizontal’

  Property | Description
  --- | ---
  orientation | vertical or horizontal
  fraction | 0.15; fraction of original axes to use for colorbar
  pad | 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes
  shrink | 1.0; fraction by which to shrink the colorbar
  aspect | 20; ratio of long to short dimensions
  anchor | (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal; the anchor point of the colorbar axes
  panchor | (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal; the anchor point of the colorbar parent axes. If False, the parent axes’ anchor will be unchanged

  All but the first of these are stripped from the input kw set.

  Returns (cax, kw), the child axes and the reduced kw dictionary to be passed when creating the colorbar instance.