publiplots.boxplot¶

publiplots.boxplot(data, x=None, y=None, hue=None, order=None, hue_order=None, orient=None, color=None, linecolor=None, edgecolor=None, palette=None, width=0.8, gap=0, whis=1.5, showcaps=False, fliersize=None, linewidth=None, alpha=None, border_radius=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, annotate=None, **kwargs)[source]¶

Create a publication-ready box plot.

This function creates box 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) – Orientation of the plot (‘v’ or ‘h’).
color (str, optional) – Fixed color for all boxes (only used when hue is None).
linecolor (str, optional) – Deprecated. Use edgecolor instead. Color of the box edges.
edgecolor (str, optional) – Color of the box edges, whiskers, caps, and outlier marker edges. When None, edges match the palette face color for each group.
palette (str, dict, or list, optional) – Color palette for hue grouping.
width (float, default=0.8) – Width of the boxes.
gap (float, default=0) – Gap between boxes when using hue.
whis (float, default=1.5) – Proportion of IQR past low and high quartiles to extend whiskers.
showcaps (bool, default=False) – Whether to show the caps.
fliersize (float, optional) – Size of outlier markers.
linewidth (float, optional) – Width of box edges. When None, resolved from publiplots.rcParams["lines.linewidth"].
alpha (float, optional) – Transparency of box fill (0-1). When None, resolved from publiplots.rcParams["alpha"].
border_radius (float or (top_mm, bottom_mm) tuple, optional) – Corner radius for the IQR box, in millimeters (print-consistent, independent of the data-axis range). A scalar rounds all four corners symmetrically; a 2-tuple rounds top and bottom independently (e.g. border_radius=(1.5, 0) keeps the Q1 edge square — useful when the box is visually paired with a density cloud in pp.raincloudplot). Defaults to the box.border_radius rcParam ((0, 0) = flat). Set globally via pp.rcParams['box.border_radius'] = 1.5.
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")]}).
**kwargs – Additional keyword arguments passed to seaborn.boxplot.

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple box plot:

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

Box plot with hue grouping:

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

Box plot with statistical annotations between groups:

>>> ax = pp.boxplot(
...     data=df, x="category", y="value",
...     annotate={"comparisons": [("A", "B"), ("B", "C")]}
... )