.differential_abundance_box

proteopy.pl.differential_abundance_box(adata, varm_slot, order=None, top_n=None, layer=None, verbose=False, figsize=(10.0, 6.0), title=None, xlabel_rotation=45, color_scheme=None, show_pval=True, pval_fontsize=9, show=True, save=None, ax=None)[source]

Display boxplots of intensities for top differentially abundant variables.

For each of the top N differentially abundant variables (sorted by p-value), shows side-by-side boxplots comparing intensities across groups defined by the statistical test and annotates the per-variable p-values.

Parameters:

  • adata (ad.AnnData) – AnnData containing differential abundance test results in .varm and expression data in .X or a specified layer.

  • varm_slot (str) – Key in adata.varm containing the differential abundance test results. Expected format produced by proteopy.tl.differential_abundance.

  • order (list[str] | None, optional) – Order and/or subset groups within each variable’s boxplots. When None, uses all groups as they appear in the data. When provided, only groups listed in order are shown, in the given sequence. All values must exist in the group_by column.

  • top_n (int, optional) – Number of top differentially abundant variables to display. Variables are ranked by ascending p-value (most significant first). Defaults to 10.

  • layer (str | None, optional) – Key in adata.layers providing the intensity matrix. When None, auto-detects the layer from the statistical test metadata.

  • verbose (bool, optional) – If True, print which layer or .X matrix is used for intensity data.

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

  • title (str | None, optional) – Plot title. If None, generates a title from the varm_slot name.

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

  • 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. If None, uses the default color cycle.

  • show_pval (bool, optional) – If True, annotate the per-variable p-values above the boxplots. If False, omit the annotations.

  • pval_fontsize (float | int, optional) – Font size for the p-value annotations when show_pval is True.

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

  • save (str | Path | None, optional) – File path to save the figure. Saved at 300 DPI with tight bounding box. None skips saving.

  • ax (bool | None, optional) – Return the matplotlib.axes.Axes object. When None or False, returns None. When True, returns the Axes object for further customization.

Returns:

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

Return type:

Axes | None

Raises:

  • KeyError – If varm_slot is not in adata.varm, if layer is not in adata.layers, or if the parsed group_by column is not in adata.obs.

  • TypeError – If adata.varm[varm_slot] is not a pandas DataFrame.

  • ValueError – If top_n is not a positive integer, if no valid results remain after filtering, if order contains values not present in the group_by column, or if pval_fontsize is not a positive number when show_pval is True.

Examples

Plot top 10 differentially abundant proteins:

>>> pp.pl.differential_abundance_box(
...     adata,
...     varm_slot="welch;condition;treated_vs_control",
... )

Plot top 5 proteins for specific groups in a given order:

>>> pp.pl.differential_abundance_box(
...     adata,
...     varm_slot="welch;condition;treated_vs_control",
...     order=["control", "treated"],
...     top_n=5,
... )