publiplots.residplot

publiplots.residplot(data=None, *, x=None, y=None, hue=None, palette=None, color=None, alpha=None, marker=None, linewidth=None, edgecolor=None, x_partial=None, y_partial=None, lowess=False, order=1, robust=False, dropna=True, ax=None, title=None, xlabel=None, ylabel=None, legend=True, legend_kws=None, scatter_kws=None, line_kws=None, **kwargs)[source]

Plot the residuals of a linear regression, with optional hue grouping.

Wraps seaborn.residplot() and adds a hue= dimension that seaborn doesn’t natively support — when provided, the data is split by level and a separate residplot is drawn per group, each tinted by the resolved palette color. A single categorical hue LegendEntry is stashed on the axes and rendered through the publiplots legend reactor.

Parameters:

  • data (pd.DataFrame, optional) – Input data containing x, y, and any hue column.

  • x (str) – Column names for the predictor / response variables.

  • y (str) – Column names for the predictor / response variables.

  • hue (str, optional) – Column name for a categorical grouping. Each group gets its own residual computation and scatter; the palette mapping is one color per level. Numeric hue triggers a UserWarning and falls back to a single residual plot.

  • palette (str | dict | list, optional) – Palette specification for categorical hue. See publiplots.themes.colors.resolve_palette_map().

  • color (str, optional) – Single color used when hue is None. Falls back to pp.rcParams["color"].

  • alpha (float, optional) – Scatter face transparency. Falls back to pp.rcParams["alpha"].

  • marker (str, optional) – Matplotlib marker code for the scatter points. Forwarded into scatter_kws (seaborn’s residplot has no top-level marker= kwarg).

  • linewidth (float, optional) – Scatter marker edge width. Falls back to pp.rcParams["lines.linewidth"].

  • edgecolor (str, optional) – Scatter marker edge color. Falls back to pp.rcParams["edgecolor"].

  • x_partial (str | list of str, optional) – Confounding columns regressed out before computing residuals. Forwarded unchanged to seaborn.residplot().

  • y_partial (str | list of str, optional) – Confounding columns regressed out before computing residuals. Forwarded unchanged to seaborn.residplot().

  • lowess (bool, default False) – Fit a LOWESS smoother on the residuals for visual diagnosis.

  • order (int, default 1) – Polynomial order of the regression used to compute residuals.

  • robust (bool, default False) – Use a robust linear regression.

  • dropna (bool, default True) – Drop missing observations before fitting.

  • ax (Axes, optional) – Target axes. When None, a new figure is created via publiplots.subplots().

  • title (str, optional) – Plot title. None (default) leaves the axes title alone.

  • xlabel (str, optional) – Axis labels. None (default) keeps seaborn’s inferred labels.

  • ylabel (str, optional) – Axis labels. None (default) keeps seaborn’s inferred labels.

  • legend (bool | dict, default True) – True stashes + renders the hue entry (if present). False stashes nothing. A dict maps legend kinds to booleans (residplot only emits "hue").

  • legend_kws (dict, optional) – Forwarded to the legend builder (e.g. {'inside': True}). hue_label overrides the legend title.

  • scatter_kws (dict, optional) – Extra keyword arguments forwarded to the scatter layer of seaborn.residplot(). User values override our publiplots defaults (linewidth, edgecolor, alpha).

  • line_kws (dict, optional) – Extra keyword arguments forwarded to the LOWESS line layer.

  • **kwargs – Reserved for future expansion. figsize= is rejected — see publiplots.layout.subplots.reject_figsize().

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple residual plot (linear fit):

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

Residuals split by a categorical group (novelty over seaborn):

>>> ax = pp.residplot(data=df, x="x", y="y", hue="treatment")

Polynomial residuals with a LOWESS smoother:

>>> ax = pp.residplot(data=df, x="x", y="y", order=2, lowess=True)