PtitPrince

In versions 0.2.x and later, you can pass keyword arguments (kwargs) to specific components of the plot (cloud, boxplot, rain/stripplot, or pointplot) by prefixing the argument name with the component identifier:

• cloud_ for the cloud component (default)
• box_ for the boxplot component
• rain_ for the rain/stripplot component
• point_ for the pointplot component

You can install the ptitprince package using pip, conda, or directly from the GitHub repository.

# Via pip
pip install ptitprince

# Via conda
conda install -c conda-forge ptitprince

# Directly from GitHub
pip install git+https://github.com/pog87/PtitPrince

The raincloud function behaves differently depending on whether the hue variable represents a true subgroup or just a coloring preference:

1. True Subgroups: If hue is a different variable than the categorical axis (x or y), the plot creates distinct clouds and rain points for each hue level. In this mode, boxplots are filled to help distinguish overlapping subgroups.
2. Coloring Only: If hue is the same as the categorical axis, it is treated as a coloring preference. The boxplots remain transparent (facecolor='none') to avoid clutter, and the legend is automatically removed to prevent redundancy with the axis labels.

Legend Behavior:

• If hue creates subgroups, a legend is generated with the hue name as the title, positioned to the right of the plot.
• If hue is redundant with the axis, the legend is removed.

If you use Raincloud plots in academic work, please cite the following publication:

Allen M, Poggiali D, Whitaker K et al. Raincloud plots: a multi-platform tool for robust data visualization [version 2; peer review: 2 approved]. Wellcome Open Res 2021, 4:63 (https://doi.org/10.12688/wellcomeopenres.15191.2)

To emphasize factorial effects or longitudinal data (repeated measures), set pointplot=True in the pt.RainCloud function. This adds a line connecting the mean values of the groups, helping to detect trends across categories or timepoints.

# Adding a line connecting the groups' mean value
ax = pt.RainCloud(
    x="group",
    y="score",
    data=df,
    palette="Set2",
    hue="group",
    bw=0.2,
    width_viol=0.6,
    ax=ax,
    orient="h",
    pointplot=True,
)

You can use pt.RainCloud within a Seaborn FacetGrid to create multiple plots separated by a factor level. Use g.map_dataframe to pass the RainCloud function to the grid.

# Rainclouds with FacetGrid
g = sns.FacetGrid(df, col="gr2", height=6)
g = g.map_dataframe(pt.RainCloud, x="group", y="score", data=df, orient="h", hue="group")

for ax in g.axes.flat:
    ax.set_xlabel("")
    ax.set_ylabel("")

While pt.RainCloud is designed for pandas DataFrames, it also supports passing raw lists or numpy arrays for the x and y parameters directly.

# Usage with a list/np.array input
dx = list(df["group"])
dy = list(df["score"])
f, ax = plt.subplots(figsize=(7, 5))

ax = pt.RainCloud(x=dx, y=dy, palette=pal, bw=sigma, width_viol=0.6, ax=ax, orient=ort)

The ptitprince package exports its primary functionality from the PtitPrince class via the package entrypoint. You can access all available methods and attributes by importing from the top-level ptitprince module.

import ptitprince

# All exported symbols from the PtitPrince class are available here

The RainCloud function generates a Raincloud plot, which combines a half-violin plot, a boxplot (or similar), and a strip plot to provide a comprehensive view of data distribution, central tendency, and individual observations.

Key parameters:

• x, y: Categorical and numeric data.
• hue: Semantic variable for coloring.
• width_viol: Width of the violin component.
• width_box: Width of the boxplot component.
• pointplot: Boolean to include/exclude the strip plot component.
• move: Shift for the strip plot component.
• offset: Offset for the violin component.
• dodge: Whether to dodge components based on hue.

import ptitprince
import matplotlib.pyplot as plt

# Example usage
ax = ptitprince.RainCloud(x='category', y='value', data=df, pointplot=True)
plt.show()