publiplots.violinplot¶

publiplots.violinplot(data, x=None, y=None, hue=None, order=None, hue_order=None, orient=None, color=None, edgecolor=None, palette=None, saturation=1.0, fill=False, inner='box', split=False, width=0.8, dodge='auto', gap=0, linewidth=None, linecolor='auto', cut=2, gridsize=100, bw_method='scott', bw_adjust=1, density_norm='area', common_norm=False, alpha=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, annotate=None, side='both', **kwargs)[source]¶

Create a publication-ready violin plot.

This function creates violin 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.
orient (str, optional) – Deprecated. Orientation is inferred from which of x / y is categorical; passing a non-None value raises DeprecationWarning.
color (str, optional) – Fixed color for all violins (only used when hue is None).
edgecolor (str, optional) – Color of violin edges. When provided, overrides linecolor. Preferred over linecolor (which is deprecated in favor of edgecolor).
palette (str, dict, or list, optional) – Color palette for hue grouping.
saturation (float, default=1.0) – Proportion of the original saturation to draw colors at.
fill (bool, default=False) – Whether to fill the violin interior.
inner (str, optional, default="box") – Representation of the data in the violin interior. Options: “box”, “quart”, “point”, “stick”, None.
split (bool, default=False) – When using hue nesting with a variable that takes two levels, setting split to True will draw half of a violin for each level.
width (float, default=0.8) – Width of the violins.
dodge (bool or "auto", default="auto") – When hue nesting is used, whether elements should be shifted along the categorical axis.
gap (float, default=0) – Gap between violins when using hue.
linewidth (float, optional) – Width of violin edges. When None, resolved from publiplots.rcParams["lines.linewidth"].
linecolor (str, default="auto") – Deprecated. Use edgecolor instead. Kept for backward compatibility; when edgecolor is also set, edgecolor wins.
cut (float, default=2) – Distance past extreme data points to extend density estimate.
gridsize (int, default=100) – Number of points in the discrete grid used to evaluate KDE.
bw_method (str, default="scott") – Method for calculating smoothing bandwidth.
bw_adjust (float, default=1) – Factor to adjust the bandwidth.
density_norm (str, default="area") – Method for normalizing density (“area”, “count”, “width”).
common_norm (bool, default=False) – When True, normalize across the entire dataset.
alpha (float, optional) – Transparency of violin 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.
annotate (bool or dict, optional) – If truthy, run publiplots.annotate() with kind="box_stats" on the resulting axes. A dict is forwarded as keyword arguments to the annotate call (e.g., annotate={"comparisons": [("A", "B")]}).
side (str, default="both") – Publiplots-specific: which side of the categorical position to draw the violin on. Options: "both", "left", "right". When "left" or "right", draws only half of the violin — this is what publiplots.raincloudplot() uses to build its “cloud”. Note: when side is not "both" and hue is specified, the hue coloring is applied but split behavior is controlled by side.
**kwargs – Additional keyword arguments passed to seaborn.violinplot.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple violin plot:

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

Violin plot with hue grouping:

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

Half-violin (used internally by raincloudplot):

>>> ax = pp.violinplot(data=df, x="category", y="value", side="right")