faninsar.plots.Figure.hist_colorbar#

Figure.hist_colorbar(data: ArrayLike, mappable: ScalarMappable | None = None, *, cax: Axes | None = None, ax: Axes | NDArray | Iterable[Axes] | None = None, use_gridspec: bool = True, location: Literal['left', 'right', 'top', 'bottom'] | None = None, orientation: Literal['vertical', 'horizontal'] | None = None, fraction: float = 0.2, hist_fraction: float = 0.85, pad: float | None = None, shrink: float = 1.0, extend: Literal['neither', 'both', 'min', 'max'] = 'neither', extendfrac: float = 0.025, ticks: ArrayLike | Locator | None = None, outline: bool = False, cmap: str | colors.Colormap | None = None, norm: colors.Normalize | colors.BoundaryNorm | None = None, log: bool = False, min_count: float | Literal['auto'] = 'auto', label: str | None = None, hist_label: str | None = None, divider_style: dict[str, Any] | None = None, cbar_kwargs: dict | None = None) → HistColorbar#

Create a histogram-embedded colorbar.

This is a convenience function that creates a HistColorbar instance. All parameters are passed directly to the HistColorbar class constructor.

Parameters:

  • data (array-like) – The data values to create the histogram from. The infinite and NaN values are automatically removed.

  • mappable (matplotlib.cm.ScalarMappable or None, optional) – A mappable object (e.g., from imshow, contourf) containing cmap and norm. If None, cmap and norm must be provided explicitly.

  • cax (matplotlib.axes.Axes or None, optional) – Axes into which the colorbar will be drawn. If None, space will be stolen from the parent axes.

  • ax (matplotlib.axes.Axes or array of Axes or None, optional) – Parent axes from which space for a new colorbar axes will be stolen. If None, uses the axes from the mappable.

  • use_gridspec (bool, default True) – If True and the parent axes is a Subplot, use gridspec to create the colorbar axes. Otherwise use make_axes.

  • location (None or {'left', 'right', 'top', 'bottom'}, optional) – The location, relative to the parent Axes, where the colorbar Axes is created. It also determines the orientation of the colorbar (colorbars on the left and right are vertical, colorbars at the top and bottom are horizontal). If None, the location will come from the orientation (vertical colorbars on the right, horizontal ones at the bottom).

  • orientation ({'vertical', 'horizontal'} or None, optional) – Orientation of the colorbar. If None, determined from location.

  • fraction (float, default 0.2) – Fraction of original Axes to use for colorbar.

  • hist_fraction (float, default 0.85) – Fraction of the colorbar axes allocated to the histogram (0-1). The remaining fraction is allocated to the colorbar gradient.

  • pad (float or None, optional) – Fraction of original Axes between colorbar and new image Axes. If None, defaults to 0.05 for vertical, 0.15 for horizontal.

  • shrink (float, default 1.0) – Fraction by which to multiply the size of the colorbar relative to the parent axes. Similar to matplotlib’s colorbar shrink parameter.

  • extend ({'neither', 'both', 'min', 'max'}, default 'neither') – Make pointed end(s) for out-of-range values (unless ‘neither’). These are set for a given colormap using the colormap set_under and set_over methods.

  • extendfrac (float, default 0.025) – Fraction of the colorbar length to use for the extension triangles.

  • ticks (array-like or Locator, optional) – Tick locations. If None, use the default tick locations.

  • outline (bool, default False) – If True, show the outline of the colorbar axes.

  • cmap (str or Colormap or None, optional) – Colormap to use. Required if mappable is None.

  • norm (Normalize or BoundaryNorm or None, optional) – Normalization instance. If None, creates a Normalize instance from the data range.

  • log (bool, default False) – If True, use logarithmic scale for the histogram count axis.

  • min_count (float or 'auto', default 'auto') – Minimum count value for the histogram axis. If ‘auto’, uses 0.5 for log scale and 0 for linear scale.

  • label (str or None, optional) – Label for the colorbar axis.

  • hist_label (str or None, optional) – Label for the histogram axis. For vertical orientation, this appears on the x-axis (count axis). For horizontal orientation, this appears on the y-axis (count axis).

  • divider_style (dict or None, optional) – Style for the divider line between the colorbar and histogram. If None, uses a gray dashed line (e.g. {“color”: “0.35”, “linestyle”: (0, (5, 5)), “linewidth”: 1}).

  • cbar_kwargs (dict or None, optional) – Additional keyword arguments to pass to matplotlib.colorbar.Colorbar.

Returns:

The histogram-embedded colorbar instance with the following key attributes:

  • ax_cbar : Axes containing the colorbar

  • ax_hist : Axes containing the histogram

  • cbar : The colorbar object

  • fig : The figure containing the colorbar

Return type:

HistColorbar

See also

HistColorbar

The main class for creating histogram-embedded colorbars.

Notes

This function is a convenience wrapper around the HistColorbar class. For more control and access to additional methods, create a HistColorbar instance directly.

Examples

Basic usage with explicit colormap and normalization:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from matplotlib.colors import Normalize
>>>
>>> # Generate sample data
>>> data = np.random.randn(1000)
>>>
>>> # Create a simple plot
>>> fig, ax = plt.subplots()
>>> norm = Normalize(vmin=-3, vmax=3)
>>> hcb = fig.hist_colorbar(data=data, cmap="viridis", norm=norm, ax=ax)
>>> plt.show()

Using with a mappable object from imshow:

>>> data_2d = np.random.randn(50, 50)
>>> fig, ax = plt.subplots()
>>> im = ax.imshow(data_2d, cmap="coolwarm")
>>> hcb = fig.hist_colorbar(data=data_2d.flatten(), mappable=im)
>>> plt.show()

Horizontal orientation with custom histogram bins:

>>> data = np.random.randn(5000)
>>> fig, ax = plt.subplots()
>>> hcb = fig.hist_colorbar(
...     data=data, cmap="plasma", orientation="horizontal", ax=ax
... )
>>> plt.show()

Using logarithmic scale for histogram counts:

>>> data = np.random.exponential(2, 10000)
>>> fig, ax = plt.subplots()
>>> hcb = fig.hist_colorbar(
...     data=data,
...     cmap="inferno",
...     log=True,
...     ax=ax,
...     label="Intensity",
...     hist_label="Count",
... )
>>> plt.show()