publiplots.hexbinplot¶

publiplots.hexbinplot(data, *, x, y, C=None, reduce_C_function=<function mean>, gridsize=30, bins=None, mincnt=1, cmap=None, vmin=None, vmax=None, edgecolor=None, linewidth=None, alpha=1.0, extent=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, **kwargs)[source]¶

Create a publication-ready hexagonal-binning density plot.

Aggregates (x, y) point clouds into a hexagonal grid, coloring each hex by either its count or a reduced statistic (mean / median / etc.) of an auxiliary column C. The color legend is a continuous colorbar routed through the standard publiplots legend reactor.

Hexbin renders a single density mesh — there is no hue= knob. For per-subgroup 2D density, use publiplots.histplot() in 2D mode with hue= (one stacked colorbar per level), or facet via publiplots.subplots().

Parameters:

data (DataFrame) – Input data containing x, y, and (optionally) C.
x (str) – Column names for the bivariate axes.
y (str) – Column names for the bivariate axes.
C (str, optional) – Column reduced per hex instead of counting. When None (the default), the color encodes the per-hex count.
reduce_C_function (callable, default numpy.mean()) – Aggregator applied to the values of C within each hex. Ignored when C is None.
gridsize (int or (int, int), default 30) – Number of hexagons along x (and y, if a tuple is passed). The matplotlib default of 100 is too fine for publiplots’ mm-sized axes; 30 is legible at the 70×50 mm baseline.
bins ({None, 'log', int, sequence}, optional) – Passed through to matplotlib.axes.Axes.hexbin(). The special string 'log' log-normalizes the color scale, which is the usual choice for heavy-tailed densities.
mincnt (int, default 1) – Hide hexes below this count (matplotlib returns a masked array, so empty hexes render as fully transparent cells — matching seaborn’s appearance). Pass 0 to render every hex.
cmap (str or Colormap, optional) – Colormap for the hex density. When None (the default), builds a light sequential gradient from pp.rcParams["color"] so the default look matches the rest of publiplots’ theme. Pass any matplotlib/seaborn cmap name ("viridis", "magma", "rocket"…) to override.
vmin (float, optional) – Color scale bounds. When both are None (the default), matplotlib autoscales from the reduced/count array.
vmax (float, optional) – Color scale bounds. When both are None (the default), matplotlib autoscales from the reduced/count array.
edgecolor (str, optional) – Edge color for each hex cell. Falls back to pp.rcParams["edgecolor"]; when that is also None, edges are not drawn (hexbin’s default — stroking every cell rarely reads well at publication sizes).
linewidth (float, optional) – Edge width. Falls back to pp.rcParams["lines.linewidth"].
alpha (float, default 1.0) – Face transparency for the hex cells. Unlike marker-based plots, hexbin cells are solid density patches — the publiplots rcParams["alpha"] default (tuned for layered bars / scatter) would wash them out, so this kwarg defaults to 1.0 instead.
extent ((xmin, xmax, ymin, ymax), optional) – Data-coordinate rectangle used for binning. Defaults to the data range.
ax (Axes, optional) – Target axes. When None, a new figure is created via publiplots.subplots().
title (str, default "") – Plot title.
xlabel (str, default "") – Axis labels. None preserves whatever matplotlib set.
ylabel (str, default "") – Axis labels. None preserves whatever matplotlib set.
legend (bool or dict, default True) – True stashes and renders a colorbar for the hue dimension. False stashes nothing. A dict maps legend kinds to booleans (hexbin only emits the "hue" kind).
legend_kws (dict, optional) – Forwarded to the legend builder (e.g. {'inside': True, 'loc': 'upper right'} for an in-axes colorbar, or {'hue_label': 'log N'} to override the legend title).
**kwargs – Extra keyword arguments forwarded to matplotlib.axes.Axes.hexbin(). figsize is rejected.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Count-density hexbin (the common case for dense scatter):

>>> ax = pp.hexbinplot(data=df, x="umap1", y="umap2")

Color each hex by the mean of a third column:

>>> ax = pp.hexbinplot(data=df, x="umap1", y="umap2",
...                    C="score", reduce_C_function=np.mean)

Log-scaled density on a heavy-tailed distribution:

>>> ax = pp.hexbinplot(data=df, x="x", y="y", bins="log")