publiplots.histplot¶

publiplots.histplot(data=None, *, x=None, y=None, hue=None, weights=None, stat='count', bins='auto', binwidth=None, binrange=None, discrete=None, cumulative=False, common_bins=True, common_norm=True, multiple='layer', element='bars', fill=True, shrink=1, kde=False, kde_kws=None, line_kws=None, hue_order=None, palette=None, color=None, edgecolor=None, hatch=None, hatch_map=None, hatch_order=None, alpha=None, linewidth=None, log_scale=None, legend=True, legend_kws=None, cmap=None, vmin=None, vmax=None, annotate=None, ax=None, title='', xlabel='', ylabel='', **kwargs)[source]¶

Create a publication-ready histogram plot.

Draws a univariate histogram with optional hue grouping, multiple rendering elements (bars, step, poly), and an optional KDE overlay. When BOTH x and y are passed, switches to a 2D bivariate heatmap-like mode (QuadMesh rendered via seaborn.histplot() in 2D mode). The legend routes through the publiplots legend reactor: a single continuous-hue colorbar when hue is None, or one stacked colorbar per hue level when hue is set (so per- subgroup count magnitudes stay readable). Exposes the full seaborn histplot API while applying publiplots’ double-layer transparent-fill styling, palette resolution, and legend-entry pipeline.

Parameters:

data (DataFrame, optional) – Input data. Long-form frame containing x / y / hue.
x (str, optional) – Column name for the variable binned along the x-axis (vertical histogram). Pass either x alone (1D vertical), y alone (1D horizontal), or both (2D heatmap).
y (str, optional) – Column name for the variable binned along the y-axis (horizontal histogram). See x for combined usage.
hue (str, optional) – Column name for categorical color grouping.
weights (str, optional) – Column name with per-observation weights; influences bin counts.
stat (str, default="count") – Aggregate statistic for each bin. One of "count", "frequency", "density", "probability", "percent".
bins (str, int, or array-like, default="auto") – Bin specification. Accepts every form seaborn.histplot() accepts (a numpy bin rule like "auto", an integer count, or an explicit sequence of bin edges).
binwidth (float, optional) – Bin width in data units. Overrides bins.
binrange ((min, max), optional) – Lowest/highest data values considered. Falls back to the full range when omitted.
discrete (bool, optional) – If True, center bins on integer values and default the binwidth to 1. Suitable for integer/categorical x.
cumulative (bool, default=False) – Render the cumulative distribution instead of per-bin values.
common_bins (bool, default=True) – Use the same bin edges across all hue levels.
common_norm (bool, default=True) – When normalizing, normalize across all hue levels jointly (True) or per-level (False).
multiple ({'layer', 'dodge', 'stack', 'fill'}, default='layer') – How to handle overlapping hue levels.
element ({'bars', 'step', 'poly'}, default='bars') – Visual representation. "bars" draws Rectangle patches; "step" draws a piecewise-constant outline; "poly" draws a piecewise-linear outline at bin midpoints.
fill (bool, default=True) – Fill the area under step/poly outlines. Ignored for "bars".
shrink (float, default=1) – Bar width as a fraction of the bin width.
kde (bool, default=False) – Overlay a 1D kernel density estimate per hue level. Not supported in 2D mode (raises NotImplementedError); use publiplots.kdeplot() for 2D KDE contours.
kde_kws (dict, optional) – Extra keyword arguments forwarded to the KDE estimator (see seaborn.histplot()).
line_kws (dict, optional) – Extra keyword arguments forwarded to step/poly/KDE line artists.
hue_order (list, optional) – Order of the hue levels; determines palette assignment and legend order.
palette (str, dict, or list, optional) – Color palette. Accepts a palette name (publiplots or seaborn), an explicit list of colors, or a {hue_level: color} dict.
color (str, optional) – Fixed color used when hue is None.
edgecolor (str, optional) – Edge color for the bar/outline stroke. When None (the default, also the default of rcParams["edgecolor"]), the edge matches the face color at full opacity — matching publiplots’ double-layer transparent-fill styling used by barplot().
hatch (str, optional) – Column name for a secondary categorical dimension rendered with hatch patterns (v1: supported only when multiple == "layer" or when hue is None).
hatch_map (dict, optional) – Explicit mapping from hatch-column values to matplotlib hatch pattern strings. See publiplots.HATCH_PATTERNS.
hatch_order (list, optional) – Order of hatch levels; determines pattern assignment.
alpha (float, optional) – Transparency for the face fill (0-1). Falls back to rcParams.
linewidth (float, optional) – Width of bar edges / step / poly / KDE line. Falls back to rcParams.
log_scale (bool, number, or pair, optional) – If True, apply a log scale on the value axis. A number sets the base. A 2-tuple sets (x_log, y_log) independently — forwarded through to seaborn.histplot().
legend (bool or dict, default=True) – Legend control. True stashes and renders all legend kinds. False hides the legend. A dict enables/disables specific kinds (e.g. {"hue": False}).
legend_kws (dict, optional) – Additional kwargs for the legend builder. Supported keys include hue_label to override the title.
cmap (str or Colormap, optional) – 2D-only. Colormap for the bivariate heatmap. When None (the default), builds a light sequential gradient from color (or pp.rcParams["color"] when unset) so the default look matches the rest of publiplots’ theme. Passing color="#ff0000" with no cmap yields a light-red gradient. Pass any matplotlib / seaborn cmap name ("viridis", "magma", "rocket"…) to override. Silently ignored in 1D and when hue is set in 2D (seaborn uses palette per hue level instead).
vmin (float, optional) – 2D-only. Color scale bounds. When both are None (the default), seaborn autoscales from the per-cell statistic. Silently ignored in 1D.
vmax (float, optional) – 2D-only. Color scale bounds. When both are None (the default), seaborn autoscales from the per-cell statistic. Silently ignored in 1D.
annotate (bool or dict, optional) – If truthy, label each bar with its statistic (only supported for element="bars"). Pass a dict to forward options to publiplots.annotate() (e.g. {"fmt": "d"}).
ax (Axes, optional) – Matplotlib axes to draw on. If None, a new figure is created via publiplots.layout.subplots().
title (str, default="") – Plot title.
xlabel (str, default="") – X-axis label. Forwarded verbatim to Axes.set_xlabel() when not None (use None to keep seaborn’s inferred label).
ylabel (str, default="") – Y-axis label. Same semantics as xlabel.
**kwargs – Extra keyword arguments forwarded to seaborn.histplot(). figsize is rejected — use pp.subplots(axes_size=...) and pass ax= instead.

Returns:

The axes where the plot was drawn. Use ax.get_figure() to recover the figure handle.

Return type:

Axes

Examples

Simple histogram of one variable:

>>> ax = pp.histplot(data=df, x="value")

Grouped histogram with KDE overlay:

>>> ax = pp.histplot(
...     data=df, x="value", hue="group",
...     multiple="layer", kde=True, palette="pastel",
... )

Step outline without fill:

>>> ax = pp.histplot(data=df, x="value", hue="group",
...                  element="step", fill=False)

2D bivariate heatmap (both x and y set):

>>> ax = pp.histplot(data=df, x="x", y="y", cmap="magma")