publiplots.kdeplot¶

publiplots.kdeplot(data=None, *, x=None, y=None, hue=None, palette=None, color=None, alpha=None, fill=None, multiple='layer', common_norm=True, common_grid=False, cumulative=False, weights=None, bw_method='scott', bw_adjust=1, gridsize=200, cut=3, clip=None, log_scale=None, warn_singular=True, levels=10, thresh=0.05, cbar=False, cbar_ax=None, cbar_kws=None, cmap=None, linewidth=None, edgecolor=None, ax=None, title=None, xlabel=None, ylabel=None, legend=True, legend_kws=None, **kwargs)[source]¶

Create a publication-ready kernel density estimate (KDE) plot.

Draws a univariate density curve when exactly one of x / y is provided, or a bivariate contour density when both are. Supports hue grouping, the full seaborn kdeplot estimator API (bandwidth, cut, clip, cumulative, log-scale), and publiplots’ double-layer transparent-fill styling + standard legend reactor.

Parameters:

data (DataFrame, optional) – Long-form dataframe with x / y / hue columns.
x (str, optional) – Column for the x-axis variable. Provide alone for a 1D density curve; provide with y for a 2D contour plot.
y (str, optional) – Column for the y-axis variable. Provide alone for a horizontal 1D density curve; provide with x for a 2D contour plot.
hue (str, optional) – Column name for categorical color grouping.
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.
alpha (float, optional) – Transparency for filled regions (0-1). Falls back to publiplots.rcParams["alpha"].
fill (bool, optional) – If True, fill area under curves (1D) or color-fill contour bands (2D). Pass None to use seaborn’s derived default (which is False for multiple='layer' and True for multiple='stack' / 'fill').
multiple ({'layer', 'stack', 'fill'}, default='layer') – Handling of overlapping hue levels for 1D densities.
common_norm (bool, default=True) – When normalizing, normalize across all hue levels jointly (True) or per-level (False).
common_grid (bool, default=False) – Use a shared evaluation grid across hue levels (useful when multiple='stack' or 'fill').
cumulative (bool, default=False) – Plot the cumulative distribution instead of the density.
weights (str, optional) – Column name with per-observation weights.
bw_method (str or float, default='scott') – Bandwidth rule ('scott' / 'silverman') or an explicit scalar.
bw_adjust (float, default=1) – Multiplicative factor on the automatic bandwidth.
gridsize (int, default=200) – Number of evaluation points for the KDE grid.
cut (float, default=3) – Extend KDE beyond data range by cut * bandwidth.
clip ((min, max), optional) – Hard limits for the KDE evaluation range.
log_scale (bool, number, or pair, optional) – Log-scale the value axis; forwarded to seaborn.
warn_singular (bool, default=True) – Emit a warning when a hue level has near-zero variance (KDE cannot be computed).
levels (int or list of float, default=10) – Number of contour levels (int) or explicit probability-mass cutoffs (list). Used in 2D mode only.
thresh (float, default=0.05) – Lowest iso-density level as a fraction of peak density. Used in 2D mode only.
cbar (bool, default=False) – 2D only. If True, draws filled contour bands colored by density and stashes a continuous-hue colorbar entry on the axes. The band is rendered by publiplots’ legend reactor, not by seaborn. When hue is None and fill is unset, cbar=True implicitly switches to fill=True so the contour fill encodes the density value the colorbar advertises.
cbar_ax (Axes, optional) – Accepted for signature compatibility. Logs a UserWarning — the colorbar is placed via stash_continuous_hue, not onto cbar_ax directly.
cbar_kws (dict, optional) – Forwarded into legend_kws (e.g. {'hue_label': 'density'}).
cmap (str or Colormap, optional) – 2D only. Colormap used to color the filled contour bands and the colorbar gradient. When None (the default), falls back to matplotlib.rcParams["image.cmap"] — same convention as pp.hexbinplot(). Only applies in 2D mode without hue.
linewidth (float, optional) – Stroke width for curves / contour lines. Falls back to rcParams.
edgecolor (str, optional) – Override for curve / contour edge color. Falls back to rcParams.
ax (Axes, optional) – Target axes. When None, a new figure is created via publiplots.subplots().
title (str, optional) – Plot title. When None, no title is set.
xlabel (str, optional) – X-axis label. When None (the default), seaborn’s inferred label (the column name or 'Density') is preserved.
ylabel (str, optional) – Y-axis label. Same semantics as xlabel.
legend (bool or dict, default=True) – Legend control. True stashes and renders all legend kinds. False hides everything. A dict enables per-kind (e.g. {"hue": False}).
legend_kws (dict, optional) – Extra kwargs forwarded to the legend builder (e.g. {'inside': True}).
**kwargs – Extra kwargs passed to seaborn.kdeplot(). figsize is rejected — use pp.subplots(axes_size=...) and pass ax=.

Returns:

The axes the plot was drawn on.

Return type:

Axes

Examples

>>> ax = pp.kdeplot(data=df, x="value")
>>> ax = pp.kdeplot(data=df, x="value", hue="group", fill=True)
>>> ax = pp.kdeplot(data=df, x="x", y="y", cbar=True)