API Reference

mpl_histcolorbar.histcolorbar(fig, mappable, cax=None, ax=None, use_gridspec=True, **kwargs)

Add a HistColorbar to a plot.

This function is based on matplotlib.figure.Figure.colorbar, and accepts all the same arguments with the addition of an argument that takes the Figure to which the histcolorbar will be added, as well as keyword arguments specific to a histcolorbar.

Parameters:

  • fig (matplotlib.figure.Figure) – The figure to which the HistColorbar will be added.

  • mappable (matplotlib.cm.ScalarMappable) – The ScalarMappable described by this histcolorbar.

  • cax (matplotlib.axes.Axes, optional) – Axes into which the histcolorbar will be drawn. If None, then a new Axes is created and the space for it will be stolen from the Axes(s) specified in ax.

  • ax (matplotlib.axes.Axes or iterable or numpy.ndarray of Axes, optional) –

    The one or more parent Axes from which space for a new histcolorbar Axes will be stolen. This parameter is only used if cax is not set.

    Defaults to the Axes that contains the mappable used to create the histcolorbar.

  • use_gridspec (bool, optional) – If cax is None, a new cax is created as an instance of Axes. If ax is positioned with a subplotspec and use_gridspec is True, then cax is also positioned with a subplotspec.

  • **kwargs – Additional keyword arguments are described in the docstring of HistColorbar.

Returns:

histcolorbar

Return type:

mpl_histcolorbar.HistColorbar

class mpl_histcolorbar.HistColorbar(ax, mappable=None, *, cmap=None, norm=None, alpha=None, values=None, boundaries=None, orientation=None, ticklocation='auto', extend=None, spacing='uniform', ticks=None, format=None, drawedges=False, filled=True, extendfrac=None, extendrect=False, label='', location=None, bins='auto', separate_hist=False, hist_fraction=0.5, hist_color=None)

Bases: Colorbar

A subclass of matplotlib’s Colorbar that shows a histogram of the color values.

Unlike matplotlib’s colorbar, a scalar mappable must be provided to the histcolorbar, as the histogram is calculated from the mappable’s array. The histcolorbar is designed as a drop-in replacement for matplotlib’s colorbar, so all of Colorbar’s parameters are accepted, but some are ignored (see below).

Parameters:

  • ax (matplotlib.axes.Axes) – The axes instance in which the histcolorbar is drawn.

  • mappable (matplotlib.cm.ScalarMappable) – The mappable whose array will be histogrammed, and whose colormap and norm will be used. Unlike matplotlib.colorbar.Colorbar, this parameter is required. For compatibility with matplotlib.colorbar.Colorbar, a default value of None is allowed, but this will raise an error.

  • cmap (matplotlib.colors.Colormap, optional) – This parameter is ignored, and only included for compatibility with matplotlib.colorbar.Colorbar. If it is not None, a warning will be raised.

  • norm (matplotlib.colors.Normalize, optional) – This parameter is ignored, and only included for compatibility with matplotlib.colorbar.Colorbar. If it is not None, a warning will be raised.

  • alpha (float, optional) – The histcolorbar transparency between 0 (transparent) and 1 (opaque). If None, the alpha value of the mappable’s cmap will be used. The default value is None.

  • bins (int or sequence of scalars or str, optional) – If bins is an int, it defines the number of equal-width bins in the given range (10, by default). If bins is a sequence, it defines the bin edges, including the rightmost edge, allowing for non-uniform bin widths. If bins is a string, it defines the method used to calculate the optimal bin width, as defined by numpy.histogram_bin_edges. The default value of ‘auto’ uses the same bins as numpy.histogram.

  • separate_hist (bool, optional) – If True, the HistColorbar will consist of a histogram and a colorbar stacked on top of each other. If False, only the histogram will be shown.

  • hist_fraction (float, optional) – The fraction of the HistColorbar that will be taken up by the histogram. This is only used if separate_hist is True. The default value is 0.5.

  • hist_color (str or tuple, optional) – The color of the histogram. The default value is None, which will color the histogram using the colors of the colormap. If separate_hist is False, this parameter is ignored.