publiplots.raincloudplot¶

publiplots.raincloudplot(data, x=None, y=None, hue=None, order=None, hue_order=None, color=None, palette=None, saturation=1.0, dodge=True, gap=0.3, cloud_side='right', cloud_alpha=None, cut=2, gridsize=100, bw_method='scott', bw_adjust=1, density_norm='area', box=True, box_width=0.15, box_kws=None, rain='strip', rain_kws={'alpha': 0.5, 'ax': <Axes: title={'center': 'Auto edges (palette)'}>, 'color': '#E67E7E', 'data': condition response 0 Control 49.584286 1 Control 49.110432 2 Control 58.334374 3 Control 39.946086 4 Control 55.963101 .. ... ... 115 High Dose 68.788925 116 High Dose 73.456240 117 High Dose 75.192899 118 High Dose 72.889007 119 High Dose 68.945017 [120 rows x 2 columns], 'dodge': True, 'edgecolor': None, 'hue': 'condition', 'hue_order': None, 'legend': False, 'linewidth': 0, 'native_scale': True, 'order': None, 'palette': {'Control': (0.4588235294117647, 0.7019607843137254, 0.4588235294117647), 'High Dose': (0.9333333333333333, 0.6666666666666666, 0.34509803921568627), 'Low Dose': (0.5568627450980392, 0.5568627450980392, 0.7568627450980392)}, 'x': 'condition', 'y': 'response'}, box_offset=0.2, rain_offset=0.2, edgecolor=None, linewidth=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None)[source]¶

Create a publication-ready raincloud plot.

A raincloud plot composes three publiplots primitives onto the same axes: a half-violin (the “cloud”, drawn by publiplots.violinplot() with side=cloud_side), a narrow box-and-whiskers (the “umbrella”, drawn by publiplots.boxplot()), and a strip or swarm of raw points (the “rain”, drawn by publiplots.stripplot() / publiplots.swarmplot()). The box and rain layers are offset away from the cloud so each component is legible.

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.
color (str, optional) – Fixed color for all elements (only used when hue is None).
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.
dodge (bool, default=True) – Whether to dodge the violin and box plot.
gap (float, default=0.3) – Gap between the violin and the box plot.
cloud_side (str, default="right") – Side of the cloud plot (“left” or “right”).
cloud_alpha (float, optional) – Transparency of violin fill (0-1). Defaults to rcParams alpha.
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”).
box (bool, default=True) – Whether to show the box plot.
box_width (float, default=0.15) – Width of the box plot.
box_kws (dict, optional) – Additional keyword arguments for box plot.
rain ({"strip", "swarm"}, default="strip") – Type of rain plot: "strip" (jittered) or "swarm" (beeswarm).
rain_kws (dict, optional) – Additional keyword arguments for rain plot. Default: dict(alpha=0.5, linewidth=0).
box_offset (float, default=0.2) – Offset for the box plot from the center position. Sign is flipped automatically so that the box lands on the side opposite cloud_side.
rain_offset (float, default=0.2) – Offset for rain points from the center position. Sign is flipped automatically so that the rain lands on the side opposite cloud_side.
edgecolor (str, optional) – Color for element edges. When None, resolved from publiplots.rcParams["edgecolor"].
linewidth (float, optional) – Width of edges. When None, resolved from publiplots.rcParams["lines.linewidth"].
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 the same bool | dict[kind, bool] form as the underlying violin plot; the value is forwarded to the inner violinplot call, which owns the legend for the raincloud.
legend_kws (dict, optional) – Additional keyword arguments for legend.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple raincloud plot:

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

Raincloud plot with hue grouping:

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

Raincloud with swarm “rain” layer and cloud on the left:

>>> ax = pp.raincloudplot(
...     data=df, x="category", y="value",
...     rain="swarm", cloud_side="left"
... )