.box

proteopy.pl.box(adata, keys, group_by=None, order=None, layer=None, zero_to_na=False, fill_na=None, log_transform=None, color_scheme=None, figsize=(8.0, 5.0), title=None, xlabel_rotation=0, ylabel=None, show_points=False, point_size=3, point_alpha=0.7, show=True, save=None, ax=False)[source]

Boxplot of intensities for one or more variables.

Parameters:

  • adata (AnnData) – AnnData with intensity data in .X or a specified layer.

  • keys (str | list[str]) – Variable name(s) present in adata.var_names to plot.

  • group_by (str | None, optional) – Column in adata.obs whose unique values define the x-axis categories. When None, all observations are pooled into a single box.

  • order (list[str] | None, optional) – Subset and order groups when group_by is set. Only groups listed in order are shown, in the given sequence. Ignored when group_by is None.

  • layer (str | None, optional) – Key in adata.layers providing the intensity matrix. When None, uses adata.X.

  • zero_to_na (bool, optional) – Convert zero intensities to NaN before other transforms.

  • fill_na (float | int | None, optional) – Replace missing intensities with this value before transformations.

  • log_transform (float | None, optional) – Base for log transformation. When set, applies log(value + 1, base).

  • color_scheme (str | dict | list | None, optional) – Color mapping for groups. Accepts a named Matplotlib colormap, a dict mapping group names to colors, or a list of colors.

  • figsize (tuple[float, float], optional) – Figure dimensions (width, height) in inches.

  • title (str | None, optional) – Plot title. When None, defaults to the variable name.

  • xlabel_rotation (float, optional) – Rotation angle (degrees) for x-axis tick labels.

  • ylabel (str | None, optional) – Label for the y-axis.

  • show_points (bool, optional) – Overlay individual observations as a strip plot on top of each box.

  • point_size (float, optional) – Marker size for the individual points when show_points is True.

  • point_alpha (float, optional) – Opacity for individual points when show_points is True.

  • show (bool, optional) – Call matplotlib.pyplot.show() to display the plot.

  • save (str | os.PathLike | None, optional) – File path to save the figure. For a single key, the format is inferred from the file extension (e.g. .png, .pdf, .svg). For multiple keys, saved as a multi-page PDF.

  • ax (bool, optional) – If True, return the underlying Axes object(s) instead of None.

Returns:

The Matplotlib Axes object(s) if ax=True, otherwise None.

Return type:

Axes | list[Axes] | None

Raises:

  • KeyError – If any element of keys is not in adata.var_names, if group_by is not in adata.obs, or if layer is not in adata.layers.

  • ValueError – If keys is empty, if order contains values not present in the group_by column, if log_transform is not positive or equals 1, or if group_by is None and order is provided.

Examples

Single variable, grouped by condition:

>>> import proteopy as pr
>>> pr.pl.box(adata, keys="ProteinA", group_by="condition")

Multiple variables saved to PDF:

>>> pr.pl.box(
...     adata,
...     keys=["ProteinA", "ProteinB"],
...     group_by="condition",
...     save="boxplots.pdf",
... )