publiplots.swarmplot¶

publiplots.swarmplot(data, x=None, y=None, hue=None, order=None, hue_order=None, dodge=False, orient=None, color=None, palette=None, size=None, edgecolor=None, linewidth=None, hue_norm=None, alpha=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, **kwargs)[source]¶

Create a publication-ready swarm plot.

This function creates swarm plots with transparent fill and opaque edges, following the publiplots visual style.

Parameters:

data (DataFrame) – Input data.
x (str, optional) – Column name for x-axis variable.
y (str, optional) – Column name for y-axis variable.
hue (str, optional) – Column name for color grouping.
order (list, optional) – Order for the categorical levels.
hue_order (list, optional) – Order for the hue levels.
dodge (bool, default=False) – Whether to separate points by hue along the categorical axis.
orient (str, optional) – Orientation of the plot (‘v’ or ‘h’).
color (str, optional) – Fixed color for all points (only used when hue is None).
palette (str, dict, or list, optional) – Color palette for hue grouping.
size (float, optional) – Marker diameter in points. Falls back to pp.rcParams["lines.markersize"] (default 4) when None.
edgecolor (str, optional) – Color for marker edges. If None, uses face color. Can also be set globally via publiplots.rcParams["edgecolor"].
linewidth (float, optional) – Width of marker edges. When None, resolved from publiplots.rcParams["lines.linewidth"].
hue_norm (tuple or Normalize, optional) – Normalization for continuous hue variable.
alpha (float, optional) – Transparency of marker fill (0-1). When None, resolved from publiplots.rcParams["alpha"].
ax (Axes, optional) – Matplotlib axes object. If None, creates new figure.
title (str, default="") – Plot title.
xlabel (str, default="") – X-axis label.
ylabel (str, default="") – Y-axis label.
legend (bool or dict, default=True) – Whether to show the legend. Accepts bool or dict[kind, bool] for per-kind control (e.g., legend={"hue": False}).
legend_kws (dict, optional) – Additional keyword arguments for legend.
**kwargs – Additional keyword arguments passed to seaborn.swarmplot.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple swarm plot:

>>> import publiplots as pp
>>> ax = pp.swarmplot(data=df, x="category", y="value")

Swarm plot with hue grouping:

>>> ax = pp.swarmplot(
...     data=df, x="category", y="value", hue="group"
... )