.abundance_rank

proteopy.pl.abundance_rank(adata, color=None, highlight_vars=None, var_labels_key=None, var_label_fontsize=8, layer=None, summary_method='average', log_transform=10, input_space='auto', force=False, zero_to_na=False, fill_na=None, figsize=(8, 6), title=None, xlabel=None, ylabel=None, alpha=0.6, s=20, show=True, save=None, ax=False, color_scheme=None)[source]

Plot variable intensities vs their abundance rank.

A typical MS proteomics plot to assess dynamic range and intensity distribution. Each point represents a variable (protein/peptide) with its y-value being the summary statistic (e.g., average, median) across observations (computation ignores NaNs).

When color is specified, summary values and ranks are computed separately for each group. The plot shows one dot per variable per group, with all groups superimposed. When color is None, a single dot per variable is plotted based on the global summary.

Parameters:

  • adata (AnnData) – Proteomics AnnData.

  • color (str, optional) – Column in adata.obs used to subset observations into groups. Summary values and ranks are computed separately per group, and all groups are plotted superimposed. When None, global summary across all observations is used.

  • highlight_vars (Sequence[str], optional) – List of variable names to highlight with text labels using adjustText. When color is specified, each variable is labeled once per group at its group-specific position.

  • var_labels_key (str, optional) – Column in adata.var containing alternative labels for highlighted variables. When specified, these labels are displayed instead of the variable names. Useful for displaying gene symbols instead of IDs.

  • var_label_fontsize (float, optional) – Font size for highlighted variable labels.

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

  • summary_method (str, optional) – Method to summarize intensities across observations per variable. Options: 'sum', 'average', 'median', 'max'. NAs are ignored; if all values are NA, the result is NA.

  • log_transform (float, optional) – Base for log transformation of intensities. Defines the target space. When None, no transformation is applied (linear space).

  • input_space (str, optional) – Specifies the input data space: 'log', 'linear', or 'auto'. When 'auto', uses heuristics to infer whether data is already log-transformed.

  • force (bool, optional) – When True, suppress warnings about input space mismatches.

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

  • fill_na (float | int, optional) – Replace missing values with this constant before transformations.

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

  • title (str, optional) – Plot title. Defaults to "Abundance Rank Plot".

  • xlabel (str, optional) – Label for x-axis. Defaults to "Rank".

  • ylabel (str, optional) – Label for y-axis. Auto-generated based on transformation applied.

  • alpha (float, optional) – Point transparency (0-1 range).

  • s (float, optional) – Point size for the scatter plot.

  • show (bool, optional) – Display the figure with matplotlib.pyplot.show().

  • save (str | os.PathLike, optional) – Path to save the figure. None skips saving.

  • ax (bool, optional) – Return the underlying Axes object instead of None.

  • color_scheme (Any, optional) – Palette specification forwarded to proteopy.utils.matplotlib._resolve_color_scheme().

Returns:

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

Return type:

Axes | None

Raises:

  • ValueError – If input_space is 'log' and log_transform is None (cannot convert log to linear without knowing the base), if both zero_to_na and fill_na are set, or if no valid data remains.

  • KeyError – If color column is not in adata.obs, if layer is not in adata.layers, or if highlight_vars contains variables not in adata.var_names.

Notes

Input/Output Space Logic:

  • input_space='auto': Heuristically infers whether data is log-transformed. Prints an informational message about the inference.

  • If input is inferred as log and target is also log (log_transform is set): No transformation; prints a message that the log base is ignored since data is already in log space.

  • If input is inferred as log and target is linear (log_transform=None): Raises an error because the original log base is unknown.

  • If input_space is explicitly set (not 'auto'): - input_space='linear' with log_transform set: Applies log

    transformation.

    • input_space='log' with log_transform=None: Raises a warning (or error if force=False).

    • Matching spaces: No transformation.

  • When force=False and the inferred space doesn’t match the declared input_space, a warning is raised.

Examples

Basic abundance rank plot:

>>> proteopy.pl.abundance_rank(adata)

Color by sample condition:

>>> proteopy.pl.abundance_rank(adata, color="condition")

Highlight specific proteins:

>>> proteopy.pl.abundance_rank(
...     adata,
...     highlight_vars=["ProteinA", "ProteinB"],
... )