publiplots.regplot¶

publiplots.regplot(data=None, *, x=None, y=None, hue=None, palette=None, color=None, alpha=None, marker=None, linewidth=None, edgecolor=None, x_estimator=None, x_bins=None, x_ci='ci', scatter=True, fit_reg=True, ci=95, n_boot=1000, units=None, seed=None, order=1, logistic=False, lowess=False, robust=False, logx=False, x_partial=None, y_partial=None, truncate=True, dropna=True, x_jitter=None, y_jitter=None, ax=None, title=None, xlabel=None, ylabel=None, legend=True, legend_kws=None, scatter_kws=None, line_kws=None, ci_kws=None, **kwargs)[source]¶

Create a publication-ready regression plot with optional hue grouping.

Wraps seaborn.regplot() with the publiplots styling pipeline and adds hue= support (categorical only). When hue is provided the plot loops over hue levels and draws a separate regression per group onto the same axes.

The plot has three independent visual layers, each with its own styling bucket:

Layer	Artist	Styling kwarg
scatter	`PathCollection`	`scatter_kws`
fit line	`Line2D`	`line_kws`
CI band	`FillBetweenPolyColl.`	`ci_kws`

The top-level alpha, edgecolor, linewidth, marker and color kwargs are convenience shortcuts that publiplots routes to the appropriate layer’s bucket via setdefault (so anything you pass directly in scatter_kws / line_kws / ci_kws always wins).

Unlike seaborn’s regplot, the alpha knob applies only to the scatter face — edges stay opaque (the publiplots double-layer convention shared by pp.scatterplot, pp.histplot, etc.). The fit line stays at full opacity, and the CI band keeps seaborn’s light alpha unless overridden via ci_kws['alpha'].

Parameters:

data (DataFrame) – Input dataset.
x (str) – Column names for the bivariate axes.
y (str) – Column names for the bivariate axes.
hue (str, optional) – Column name for categorical color grouping. A separate regression is drawn per hue level. Continuous (numeric) hue columns emit a UserWarning and fall back to a single regression.
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 level for scatter markers (0-1). Falls back to rcParams["alpha"].
marker (str, optional) – Matplotlib marker code forwarded to seaborn (e.g. "s", "^"). Do not pass marker via scatter_kws — seaborn hard-overwrites the scatter collection’s paths with whatever it received at the top level.
linewidth (float, optional) – Width of marker edges (and fit-line thickness via line_kws default). Falls back to rcParams["lines.linewidth"].
edgecolor (str, optional) – Color for scatter marker edges. Set via scatter_kws["edgecolor"] when the user wants per-call control; the top-level edgecolor= is a convenience shortcut.
x_estimator (optional) – See seaborn.regplot(). When x_estimator is provided, the scatter is replaced by a per-bin aggregated point with optional error bars.
x_bins (optional) – See seaborn.regplot(). When x_estimator is provided, the scatter is replaced by a per-bin aggregated point with optional error bars.
x_ci (optional) – See seaborn.regplot(). When x_estimator is provided, the scatter is replaced by a per-bin aggregated point with optional error bars.
scatter (bool, default=True) – Draw the scatter layer.
fit_reg (bool, default=True) – Draw the regression line + confidence band.
ci (int, default=95) – Confidence interval for the regression band, in percent. None disables the band.
n_boot (int, default=1000) – Bootstrap iterations for the CI band.
units (optional) – See seaborn.regplot().
seed (optional) – See seaborn.regplot().
order (optional) – See seaborn.regplot().
logistic (optional) – See seaborn.regplot().
lowess (optional) – See seaborn.regplot().
robust (optional) – See seaborn.regplot().
logx (optional) – See seaborn.regplot().
x_partial (optional) – See seaborn.regplot().
y_partial (optional) – See seaborn.regplot().
truncate (optional) – See seaborn.regplot().
dropna (optional) – See seaborn.regplot().
x_jitter (optional) – See seaborn.regplot().
y_jitter (optional) – See seaborn.regplot().
ax (Axes, optional) – Matplotlib axes to draw on. If None, a new figure is created via publiplots.layout.subplots().
title (str, optional) – Plot title. None leaves the axes title untouched.
xlabel (str, optional) – Axis labels. None (the default) preserves whatever seaborn inferred from the data (usually the column names).
ylabel (str, optional) – Axis labels. None (the default) preserves whatever seaborn inferred from the data (usually the column names).
legend (bool or dict, default=True) – Legend control. True stashes and renders a hue legend when applicable. False hides it. 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.
scatter_kws (dict, optional) – Extra kwargs forwarded to matplotlib.axes.Axes.scatter() via seaborn. Publiplots supplies sensible defaults for linewidths, edgecolor, and alpha via setdefault, so caller-supplied values always win.
line_kws (dict, optional) – Extra kwargs forwarded to the fit-line matplotlib.axes.Axes.plot() call via seaborn.
ci_kws (dict, optional) –
Styling overrides for the confidence-interval band drawn around the fit (the FillBetweenPolyCollection seaborn emits when ci is not None). Recognized keys:
- alpha : float — face alpha for the band. Default is seaborn’s 0.15. Use a lower value to de-emphasize the band when overlaying multiple groups, or a higher value for a single bold fit.
- color : color — face color. Defaults to the regression line color (typically the per-group palette entry under hue=). Override when you want a band color independent of the line, e.g. for accessibility or print contrast.
Applied per-group when hue= is set. ci_kws only affects the CI band; the regression line uses line_kws, the scatter uses scatter_kws.
**kwargs – Extra keyword arguments forwarded to seaborn.regplot(). figsize is rejected — use pp.subplots(axes_size=...) and pass ax= instead.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Notes

Layer-specific styling: prefer the per-layer *_kws buckets when you want fine-grained control. The top-level convenience kwargs only seed defaults via setdefault:

scatter face transparency → alpha (or scatter_kws['alpha'])
scatter marker shape → marker
scatter edge stroke → edgecolor + linewidth
fit line → line_kws (e.g. {'linestyle': '--'})
CI band → ci_kws (e.g. {'alpha': 0.6})

statsmodels dependency: lowess=True, robust=True, and logistic=True require statsmodels. Install with pip install publiplots[regression]. Without it, those flags raise RuntimeError from seaborn’s _check_statsmodels.

Hue handling: only categorical hue is supported. Numeric hue columns emit UserWarning and fall back to a single-color regression — a colorbar would not meaningfully composite with N regression lines. Use pp.scatterplot(hue=, palette='viridis') + a separate non-hued pp.regplot overlay if you need both.

Examples

Basic linear fit:

>>> ax = pp.regplot(data=df, x="x", y="y")

Polynomial fit:

>>> ax = pp.regplot(data=df, x="x", y="y", order=2)

Per-group fits via hue= (the novelty over seaborn.regplot()):

>>> ax = pp.regplot(data=df, x="x", y="y", hue="group", palette="pastel")

Binned aggregation with bootstrap CI:

>>> ax = pp.regplot(
...     data=df, x="x", y="y",
...     x_bins=10, x_estimator=np.mean,
... )

Bolder CI band (de-emphasize the regression line, emphasize the uncertainty):

>>> ax = pp.regplot(data=df, x="x", y="y", ci_kws=dict(alpha=0.6))

De-emphasize CI bands when overlaying multiple groups (full-strength bands stack into mud):

>>> ax = pp.regplot(
...     data=df, x="x", y="y", hue="group",
...     palette="pastel", ci_kws=dict(alpha=0.3),
... )

Decouple band color from line color (e.g. for accessibility / print contrast):

>>> ax = pp.regplot(
...     data=df, x="x", y="y",
...     line_kws={"color": "navy"},
...     ci_kws=dict(color="#888", alpha=0.3),
... )

Custom marker, transparent face, opaque edge — full publiplots convention:

>>> ax = pp.regplot(
...     data=df, x="x", y="y",
...     marker="^", alpha=0.4, edgecolor="black",
... )

Suppress the regression line entirely (scatter + CI only — useful for showing uncertainty without committing to a fit visually):

>>> ax = pp.regplot(data=df, x="x", y="y", line_kws={"alpha": 0})

Or suppress just the CI band:

>>> ax = pp.regplot(data=df, x="x", y="y", ci=None)