faninsar.plots.HistColorbar#

class faninsar.plots.HistColorbar(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)[source]#

Bases: object

A colorbar with an embedded histogram showing data distribution.

This class creates a colorbar that includes a histogram visualization adjacent to the color gradient, providing insight into how data values are distributed across the colormap range.

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.

Notes

To customize ticks and labels after creation, use the following methods:

set_cbar_ticks() : Set colorbar tick positions and labels
set_hist_ticks() : Set histogram tick positions and labels
cbar_tick_params() : Customize colorbar tick appearance
hist_tick_params() : Customize histogram tick appearance
set_cbar_label() : Set colorbar label with custom styling
set_hist_label() : Set histogram label with custom styling

fig#

The figure containing the HistColorbar.

Type:: Figure or SubFigure

ax#

The parent axes containing the colorbar and histogram.

Type:: Axes

ax_cbar#

The axes containing the colorbar.

Type:: Axes

ax_hist#

The axes containing the histogram.

Type:: Axes

cbar#

The colorbar object.

Type:: Colorbar

See also

faninsar.plots.Figure.hist_colorbar: Convenience function to create HistColorbar.
matplotlib.pyplot.colorbar: The matplotlib colorbar function.

__init__(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) → None[source]#: Initialize the HistColorbar object.

Methods

`__init__`(data[, mappable, cax, ax, ...])	Initialize the HistColorbar object.
`cbar_tick_params`([axis, which])	Set appearance of ticks (labels), and gridlines on colorbar or histogram.
`hist_tick_params`([axis, which])	Set appearance of ticks (labels), and gridlines on colorbar or histogram.
`minorticks_off`()	Turn the minor ticks of the colorbar off.
`minorticks_on`()	Turn on colorbar minor ticks.
`remove`()	Remove the HistColorbar and clean up.
`set_cbar_formatter`(formatter[, which])	Set the formatter for the colorbar axis.
`set_cbar_label`(label, **kwargs)	Set labels for the colorbar.
`set_cbar_locator`(locator[, which])	Set the locator for the colorbar axis.
`set_cbar_ticklabels`(labels, **kwargs)	Set tick labels for the colorbar axis.
`set_cbar_ticks`(ticks[, labels, minor])	Set tick locations and labels for the colorbar axis.
`set_hist_formatter`(formatter[, which])	Set the formatter for the histogram axis.
`set_hist_label`(label, **kwargs)	Set labels for the histogram.
`set_hist_locator`(locator[, which])	Set the locator for the histogram axis.
`set_hist_ticklabels`(labels, **kwargs)	Set tick labels for the histogram axis.
`set_hist_ticks`(ticks[, labels, minor])	Set tick locations for the histogram axis.
`set_label`(label[, which])	Set label for the colorbar or histogram.
`set_min_count`([min_count])	Set the minimum count for the histogram.
`set_scale`(scale)	Set the scale of the histogram axis.
`set_ticklabels`(labels[, which])	Set tick labels for the colorbar and histogram axes.
`set_ticks`(ticks[, labels, which, minor])	Set tick locations for the colorbar and histogram axes.

Attributes

`min_count`	The minimum count for the histogram.
`scale`	The scale of the histogram axis.
`fig`	The figure containing the HistColorbar.
`ax`	The parent axes containing the colorbar and histogram.
`ax_cbar`	The axes containing the colorbar.
`ax_hist`	The axes containing the histogram.
`cbar`	The colorbar object.
`hist`	The histogram object.

cbar_tick_params(axis: Literal['x', 'y', 'both'] = 'both', which: Literal['major', 'minor', 'both'] = 'major', **kwargs) → None[source]#

Set appearance of ticks (labels), and gridlines on colorbar or histogram.

Tick properties that are not explicitly set using the keyword arguments remain unchanged unless reset is True. For the current style settings, see .Axis.get_tick_params.

Parameters:

axis ({'x', 'y', 'both'}, default: 'both') – The axis to which the parameters are applied.
which ({'major', 'minor', 'both'}, default: 'major') – The group of ticks to which the parameters are applied.
**kwargs – Keyword arguments to be passed to tick_params().
direction ({'in', 'out', 'inout'}) – Puts ticks inside the Axes, outside the Axes, or both.
length (float) – Tick length in points.
width (float) – Tick width in points.
color (:mpltype:`color`) – Tick color.
pad (float) – Distance in points between tick and label.
labelsize (float or str) – Tick label font size in points or as a string (e.g., ‘large’).
labelcolor (:mpltype:`color`) – Tick label color.
labelfontfamily (str) – Tick label font.
colors (:mpltype:`color`) – Tick color and label color.
zorder (float) – Tick and label zorder.
bottom (bool) – Whether to draw the respective ticks.
top (bool) – Whether to draw the respective ticks.
left (bool) – Whether to draw the respective ticks.
right (bool) – Whether to draw the respective ticks.
labelbottom (bool) – Whether to draw the respective tick labels.
labeltop (bool) – Whether to draw the respective tick labels.
labelleft (bool) – Whether to draw the respective tick labels.
labelright (bool) – Whether to draw the respective tick labels.
labelrotation (float) – Tick label rotation
grid_color (:mpltype:`color`) – Gridline color.
grid_alpha (float) – Transparency of gridlines: 0 (transparent) to 1 (opaque).
grid_linewidth (float) – Width of gridlines in points.
grid_linestyle (str) – Any valid .Line2D line style spec.

hist_tick_params(axis: Literal['x', 'y', 'both'] = 'both', which: Literal['major', 'minor', 'both'] = 'major', **kwargs) → None[source]#

Set appearance of ticks (labels), and gridlines on colorbar or histogram.

Tick properties that are not explicitly set using the keyword arguments remain unchanged unless reset is True. For the current style settings, see .Axis.get_tick_params.

Parameters:

axis ({'x', 'y', 'both'}, default: 'both') – The axis to which the parameters are applied.
which ({'major', 'minor', 'both'}, default: 'major') – The group of ticks to which the parameters are applied.
**kwargs – Keyword arguments to be passed to tick_params().
direction ({'in', 'out', 'inout'}) – Puts ticks inside the Axes, outside the Axes, or both.
length (float) – Tick length in points.
width (float) – Tick width in points.
color (:mpltype:`color`) – Tick color.
pad (float) – Distance in points between tick and label.
labelsize (float or str) – Tick label font size in points or as a string (e.g., ‘large’).
labelcolor (:mpltype:`color`) – Tick label color.
labelfontfamily (str) – Tick label font.
colors (:mpltype:`color`) – Tick color and label color.
zorder (float) – Tick and label zorder.
bottom (bool) – Whether to draw the respective ticks.
top (bool) – Whether to draw the respective ticks.
left (bool) – Whether to draw the respective ticks.
right (bool) – Whether to draw the respective ticks.
labelbottom (bool) – Whether to draw the respective tick labels.
labeltop (bool) – Whether to draw the respective tick labels.
labelleft (bool) – Whether to draw the respective tick labels.
labelright (bool) – Whether to draw the respective tick labels.
labelrotation (float) – Tick label rotation
grid_color (:mpltype:`color`) – Gridline color.
grid_alpha (float) – Transparency of gridlines: 0 (transparent) to 1 (opaque).
grid_linewidth (float) – Width of gridlines in points.
grid_linestyle (str) – Any valid .Line2D line style spec.

minorticks_off() → None[source]#: Turn the minor ticks of the colorbar off.

minorticks_on() → None[source]#: Turn on colorbar minor ticks.

remove() → None[source]#

Remove the HistColorbar and clean up.

This method should be called when removing a HistColorbar to properly clean up resources.

set_cbar_formatter(formatter: Formatter, which: Literal['major', 'minor'] = 'major') → None[source]#

Set the formatter for the colorbar axis.

Parameters:

formatter (Formatter) – The formatter to use.
which ({'major', 'minor'}, default: 'major') – Which ticks to apply the formatter to.

set_cbar_label(label: str, **kwargs: Any) → None[source]#

Set labels for the colorbar.

This method allows you to set labels for the colorbar and histogram with different styling options. You can call it multiple times with different parameters to apply different styles to each label.

Parameters:

label (str, optional) – Label for the colorbar axis. If None, colorbar label is not changed.
**kwargs – Additional keyword arguments passed to the label setting methods. Common options include: fontsize, color, fontweight, labelpad, etc.

set_cbar_locator(locator: Locator, which: Literal['major', 'minor'] = 'major') → None[source]#

Set the locator for the colorbar axis.

Parameters:

locator (Locator) – The locator to use.
which ({'major', 'minor'}, default: 'major') – Which ticks to apply the locator to.

set_cbar_ticklabels(labels: Iterable[str], **kwargs: Any) → None[source]#

Set tick labels for the colorbar axis.

Parameters:

labels (list of str) – List of tick labels.
**kwargs – .Text properties for the labels.

set_cbar_ticks(ticks: ArrayLike, labels: Iterable[str] | None = None, *, minor: bool = False, **kwargs) → None[source]#

Set tick locations and labels for the colorbar axis.

Parameters:

ticks (1D array-like) – List of tick locations.
labels (list of str, optional) – List of tick labels. If not set, the labels show the data value.
minor (bool, default: False) – If False, set the major ticks; if True, the minor ticks.
**kwargs – .Text properties for the labels. These take effect only if you pass labels. In other cases, please use ~.Axes.tick_params.

set_hist_formatter(formatter: Formatter, which: Literal['major', 'minor'] = 'major') → None[source]#

Set the formatter for the histogram axis.

Parameters:

formatter (Formatter) – The formatter to use.
which ({'major', 'minor'}, default: 'major') – Which ticks to apply the formatter to.

set_hist_label(label: str, **kwargs: Any) → None[source]#

Set labels for the histogram.

This method allows you to set labels for the histogram with different styling options. You can call it multiple times with different parameters to apply different styles to each label.

Parameters:

label (str) – Label for the histogram axis.
**kwargs – Additional keyword arguments passed to the label setting methods. Common options include: fontsize, color, fontweight, labelpad, etc.

set_hist_locator(locator: Locator, which: Literal['major', 'minor'] = 'major') → None[source]#

Set the locator for the histogram axis.

Parameters:

locator (Locator) – The locator to use.
which ({'major', 'minor'}, default: 'major') – Which ticks to apply the locator to.

set_hist_ticklabels(labels: Iterable[str], **kwargs: Any) → None[source]#

Set tick labels for the histogram axis.

Parameters:

labels (list of str) – List of tick labels.
**kwargs – .Text properties for the labels.

set_hist_ticks(ticks: ArrayLike, labels: Iterable[str] | None = None, *, minor: bool = False, **kwargs) → None[source]#

Set tick locations for the histogram axis.

Parameters:

ticks (1D array-like) – List of tick locations.
labels (list of str, optional) – List of tick labels. If not set, the labels show the data value.
minor (bool, default: False) – If False, set the major ticks; if True, the minor ticks.
**kwargs – .Text properties for the labels. These take effect only if you pass labels. In other cases, please use ~.Axes.tick_params.

set_label(label: str, which: Literal['cbar', 'hist'] = 'cbar', **kwargs: Any) → None[source]#

Set label for the colorbar or histogram.

This method allows you to set labels for the colorbar and histogram with different styling options. You can call it multiple times with different parameters to apply different styles to each label.

Parameters:

label (str) – Label for the colorbar or histogram axis.
which ({'cbar', 'hist'}, default: 'cbar') – Which axis to set the label for.
**kwargs – Additional keyword arguments passed to the label setting methods. Common options include: fontsize, color, fontweight, labelpad, etc.

set_min_count(min_count: float | Literal['auto'] = 'auto') → None[source]#: Set the minimum count for the histogram.

set_scale(scale: Literal['linear', 'log']) → None[source]#: Set the scale of the histogram axis.

set_ticklabels(labels: Iterable[str], which: Literal['cbar', 'hist'] = 'cbar', **kwargs: Any) → None[source]#

Set tick labels for the colorbar and histogram axes.

Parameters:

labels (list of str) – List of tick labels.
which ({'cbar', 'hist'}, default: 'cbar') – Which axis to set the tick labels for.
**kwargs – .Text properties for the labels.

set_ticks(ticks: ArrayLike, labels: Iterable[str] | None = None, *, which: Literal['cbar', 'hist'] = 'cbar', minor: bool = False, **kwargs) → None[source]#

Set tick locations for the colorbar and histogram axes.

Parameters:

ticks (1D array-like) – List of tick locations.
labels (list of str, optional) – List of tick labels. If not set, the labels show the data value.
which ({'cbar', 'hist'}, default: 'cbar') – Which axis to set the tick locations for.
minor (bool, default: False) – If False, set the major ticks; if True, the minor ticks.
**kwargs – .Text properties for the labels. These take effect only if you pass labels. In other cases, please use ~.Axes.tick_params.

ax: Axes#: The parent axes containing the colorbar and histogram.

ax_cbar: Axes#: The axes containing the colorbar.

ax_hist: Axes#: The axes containing the histogram.

cbar: Colorbar#: The colorbar object.

fig: Figure | SubFigure#: The figure containing the HistColorbar.

hist: _Histogram#: The histogram object.

property min_count: float#: The minimum count for the histogram.

property scale: Literal['linear', 'log']#: The scale of the histogram axis.

faninsar.plots.HistColorbar#

This Page