.peptides_on_sequence

proteopy.pl.peptides_on_sequence(adata, filter_key, filter_value, group_by=None, ref_sequence=None, alt_pep_sequence_key=None, add_sequences=None, allow_overlaps=False, allow_multi_match=False, color_scheme=None, title=None, order=None, figsize=None, show=True, save=None, ax=None)[source]

Plot peptide coverage on a reference sequence as horizontal bars.

Filters peptides from a peptide-level AnnData using the filter_key and filter_value parameters, which are then drawn as broken bars on top of a grey reference bar. Extra sequences (e.g., domains or post-translational modification sites) can be overlaid via the add_sequences parameter.

Parameters:

  • adata (AnnData) – Peptide-level AnnData.

  • filter_key (str) – Column in adata.var used to select peptides.

  • filter_value (str) – Value in the filter_key column to match.

  • group_by (str | None) – Column in adata.var used to assign peptides to colored rows. When None, all peptides are placed in a single row labeled filter_value. Peptides with a missing value in this column are not plotted.

  • ref_sequence (str | None) – Full reference protein sequence as an amino-acid string.

  • alt_pep_sequence_key (str | None) – Column in adata.var whose values are used as peptide amino-acid strings. When None, adata.var["peptide_id"] is used.

  • add_sequences (dict[str, dict] | None) – Additional named sequences to overlay (e.g., domains). Each value must be a dict with a "group" key and either a "seq" or "seq_coord" key. Coordinates are 0-based throughout. "seq_coord" must be a half-open [start, end) tuple where start >= 0 and end <= len(ref_sequence).

  • allow_overlaps (bool) – When False, raise ValueError if two sequences in the same group overlap positionally.

  • allow_multi_match (bool) – When True, a peptide sequence matching the reference at multiple positions is shown as one bar per match, labeled "<name> (match N)". When False, a ValueError is raised for ambiguous matches.

  • color_scheme (str | dict | list | Colormap | callable | None) – Color specification for groups. The group_by groups take colors in the order their rows are drawn, and the add_sequences groups continue the color sequence where they end. With the default order (category order if categorical, else lexicographic) this matches proteoform_intensities() and peptide_intensities(), so the same proteoform gets the same color in both plots. A custom order recolors the rows by their new positions.

  • title (str | None) – Axes title.

  • order (list[str] | None) – Group rows to draw, bottom to top, directly above the reference. Groups absent from order are excluded. When None, the peptide groups are drawn first, in the category order of group_by if it is categorical (categories without peptides are dropped), else in lexicographic order of the str-coerced values. To change it, store group_by as an ordered Categorical. The add_sequences groups follow above in natural order ("isoform 2" before "isoform 10"). A peptide group and an add_sequences group with the same label are drawn as separate rows; naming that label in order selects both.

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

  • show (bool) – Call plt.show() at the end.

  • save (str | Path | None) – Path at which to save the figure (300 dpi, bbox_inches="tight"). When None, the figure is not saved.

  • ax (matplotlib.axes.Axes | None) – Matplotlib Axes object to plot onto. If None, a new figure and axes are created. The function always returns the Axes object used for plotting.

Returns:

The Axes object used for plotting.

Return type:

matplotlib.axes.Axes

Raises:

  • ValueError – If adata is not at peptide level.

  • ValueError – If ref_sequence is None.

  • ValueError – If no peptides match filter_value in adata.var[filter_key].

  • ValueError – If a peptide sequence is not found in the reference.

  • ValueError – If a peptide matches the reference at multiple positions and allow_multi_match=False.

  • ValueError – If two sequences in the same group overlap and allow_overlaps=False.

  • KeyError – If filter_key, alt_pep_sequence_key, or group_by is not found in adata.var.

Examples

Build a minimal peptide-level AnnData with two proteins. "ELPGW" belongs to P2 and is excluded by the filter.

>>> import numpy as np
>>> import pandas as pd
>>> import anndata as ad
>>> import proteopy as pr
>>> ref = "MKTAYIAKQRQISFVKSHFSRQDEEP"
>>> peptides = ["KTAYIAK", "QRQISFVK", "SHFSRQ", "ELPGW"]
>>> var = pd.DataFrame(
...     {
...         "peptide_id": peptides,
...         "protein_id": ["P1", "P1", "P1", "P2"],
...         "proteoform": ["A", "A", "B", "A"],
...     },
...     index=peptides,
... )
>>> obs = pd.DataFrame(
...     {"sample_id": ["S1", "S2"]},
...     index=["S1", "S2"],
... )
>>> adata = ad.AnnData(
...     X=np.ones((2, 4)),
...     obs=obs,
...     var=var,
... )

Filter to P1; group peptides by proteoform.

>>> pr.pl.peptides_on_sequence(
...     adata,
...     filter_key="protein_id",
...     filter_value="P1",
...     ref_sequence=ref,
...     group_by="proteoform",
... )