publiplots.errorbarplot¶

publiplots.errorbarplot(data, x, y, *, xerr=None, yerr=None, hue=None, palette=None, color=None, linewidth=None, edgecolor=None, alpha=None, capsize=None, capthick=None, hue_norm=None, background_marker=True, errorbar_kws=None, scatter_kws=None, ax=None, title=None, xlabel=None, ylabel=None, legend=True, legend_kws=None, **kwargs)[source]¶

Create a publication-ready 2D errorbar plot: scatter with uncertainty stems.

Each (x, y) pair is drawn as a marker (via pp.scatterplot(), inheriting all of its hue / palette / face-edge alpha behavior) with optional x- and/or y-direction uncertainty rendered as thin stems below the marker.

Stem coloring. Stems match the marker color so the uncertainty visually attaches to the measurement:

Categorical ``hue=``: stems issued per-group with ecolor set to the group’s palette color (one ax.errorbar call per level).
Continuous numeric ``hue=``: stems issued per-point with ecolor resolved from the cmap and norm (one ax.errorbar call per row — acceptable since errorbar plots typically show <100 points).
No ``hue=``: single ax.errorbar call with ecolor=rcParams['edgecolor'].
``errorbar_kws={‘ecolor’: …}`` always wins over the above. Useful when a uniform stem color is wanted regardless of hue (e.g. neutral stems on a categorical hue plot).

Layering. Errorbar stems use zorder=1; scatter markers use zorder=2 (the default from pp.scatterplot()). The marker is drawn last so the stem appears to terminate at the marker edge. background_marker=True (the default) draws an opaque white twin behind each marker so the stem does not show through the alpha-faded marker face.

Parameters:

data (DataFrame) – Input data containing x, y, and any error / hue columns.
x (str) – Column names for the bivariate axes.
y (str) – Column names for the bivariate axes.
xerr (str, float, sequence, or (str, str) tuple, optional) –
Uncertainty in the x- and/or y- direction:
- str — column name; used as a symmetric ±err per row.
- float — constant scalar; broadcast to every row.
- (lo_col, hi_col) — two column names: lower and upper asymmetric extents (each ≥ 0). Renders as [y - lo, y + hi].
- Sequence — array-like with shape (N,) or (2, N), forwarded directly to Axes.errorbar().
None (the default) suppresses stems in that direction. When both xerr and yerr are None no errorbar call is issued at all.
yerr (str, float, sequence, or (str, str) tuple, optional) –
Uncertainty in the x- and/or y- direction:
- str — column name; used as a symmetric ±err per row.
- float — constant scalar; broadcast to every row.
- (lo_col, hi_col) — two column names: lower and upper asymmetric extents (each ≥ 0). Renders as [y - lo, y + hi].
- Sequence — array-like with shape (N,) or (2, N), forwarded directly to Axes.errorbar().
None (the default) suppresses stems in that direction. When both xerr and yerr are None no errorbar call is issued at all.
hue (str, optional) – Column name for marker color grouping. Categorical values produce per-group stem colors via palette; numeric values produce a continuous colorbar with per-point stem colors resolved from the cmap.
palette (str, dict, or list, optional) – Color palette for hue values. See pp.scatterplot().
color (str, optional) – Fixed marker color when hue is None. Stems pick up this color too.
linewidth (float, optional) – Stroke width for both marker edges and errorbar stems. Falls back to rcParams['lines.linewidth'].
edgecolor (str, optional) – Color for marker edges and the default stem color when hue is None or continuous. Falls back to rcParams['edgecolor']. Override the stem color independently via errorbar_kws={'ecolor': ...}.
alpha (float, optional) – Marker face transparency (0–1). Edges stay opaque (publiplots double-layer convention). Stems are unaffected — they use the opaque ecolor. Falls back to rcParams['alpha'].
capsize (float, optional) – Half-length of the stem caps in points. Falls back to rcParams['capsize'] (defaults to 0 — no caps).
capthick (float, optional) – Stroke width of the stem caps. Defaults to linewidth.
hue_norm ((vmin, vmax) or Normalize, optional) – Color normalization for continuous hue. Forwarded to pp.scatterplot().
background_marker (bool or str, default True) – Draw an opaque background twin behind each marker so the stem does not show through the alpha-faded marker face. True uses white; pass a color string (e.g. "#eeeeee") to match a non-white axes background. Set False to allow the stem to read through the marker.
errorbar_kws (dict, optional) –
Extra keyword arguments forwarded to matplotlib.axes.Axes.errorbar(). Common overrides:
- ecolor — stem color. Wins over the hue-derived color. Useful when you want neutral stems even with a categorical hue (pass ecolor=pp.rcParams['edgecolor']).
- elinewidth — stem thickness (defaults to linewidth).
- capsize, capthick — see top-level kwargs.
Caller-supplied keys win via setdefault.
scatter_kws (dict, optional) – Extra keyword arguments forwarded to pp.scatterplot(). background_marker is forwarded automatically; pass it here only if you want to override the top-level kwarg per-call.
ax (Axes, optional) – Target axes. When None, a new figure is created via pp.subplots().
title (str, optional) – Plot title.
xlabel (str, optional) – Axis labels.
ylabel (str, optional) – Axis labels.
legend (bool or dict, default True) – Legend control passed through to pp.scatterplot(). False stashes nothing. A dict maps legend kinds to booleans.
legend_kws (dict, optional) – Forwarded to the legend builder; supports e.g. hue_label for overriding the legend title.
**kwargs – Reserved for the figsize rejection guard. figsize is rejected — use pp.subplots(axes_size=...) and pass ax= instead. No other kwargs are forwarded.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Notes

Marker shape is "o" (the pp.scatterplot() default). The marker size comes from rcParams['lines.markersize'] — pass a custom s= via scatter_kws to override.

Examples

Symmetric y-error bars:

>>> ax = pp.errorbarplot(data=df, x="dose", y="response", yerr="sem")

Both directions:

>>> ax = pp.errorbarplot(data=df, x="dose", y="response",
...                       xerr="dose_err", yerr="response_err")

Asymmetric y-errors via a (lo, hi) column tuple:

>>> ax = pp.errorbarplot(data=df, x="dose", y="response",
...                       yerr=("ci_lo", "ci_hi"))

Constant scalar error:

>>> ax = pp.errorbarplot(data=df, x="x", y="y", xerr=0.1, yerr=0.2)

Hue groups with per-group stem colors:

>>> ax = pp.errorbarplot(data=df, x="dose", y="response", yerr="sem",
...                       hue="treatment", palette="pastel")

Continuous hue with colorbar legend (neutral stems):

>>> ax = pp.errorbarplot(data=df, x="x", y="y", yerr="err",
...                       hue="score", palette="viridis")

Visible caps:

>>> ax = pp.errorbarplot(data=df, x="x", y="y", yerr="err", capsize=2)

Force neutral stems even with a categorical hue:

>>> ax = pp.errorbarplot(data=df, x="x", y="y", yerr="err",
...                       hue="g", errorbar_kws={"ecolor": "0.4"})