.peptides_on_prot_sequence

proteopy.pl.peptides_on_prot_sequence(adata, protein_id, 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 protein reference sequence.

Filters peptides belonging to the given protein_id and draws them 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.

  • protein_id (str) – Value in adata.var["protein_id"] to select peptides for.

  • 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 protein_id. Peptides with a missing value in this column are not plotted.

  • ref_sequence (str | None) –

    Reference protein sequence. Resolved in this order:

    1. FASTA annotator – if the string ends with .fasta (case-insensitive), it is read as the path to a reference proteome FASTA file. The entry whose accession equals protein_id is used. The accession is the second |-delimited header field (UniProt-style sp|P12345|NAME_HUMAN -> P12345), or the full header if it has no such field.

    2. adata.var column – if the string names a column in adata.var, the sequence stored in that column for the peptides of protein_id is used. All these peptides must carry the same, non-missing sequence.

    3. Amino-acid string – otherwise the string itself is used as the reference sequence.

  • 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] | str | None) –

    Additional sequences to overlay. Either:

    • dict – named sequences (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).

    • GFF isoform annotator – a path ending with .gff (case-insensitive) to a UniProt GFF download. Its “Alternative sequence” (VSP) features for protein_id are drawn one row per isoform, marking the reference regions that the isoform replaces or deletes. A feature shared by several isoforms appears in each of their rows. The coordinates refer to the UniProt canonical sequence, so ref_sequence must be that sequence. Isoform rows are labeled as in UniProt (e.g. "isoform 2"); see order for their placement.

  • 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 protein_id in adata.var["protein_id"].

  • ValueError – If ref_sequence is a FASTA path lacking protein_id, or a adata.var column holding missing or differing sequences for protein_id.

  • ValueError – If add_sequences is a string not ending with .gff.

  • ValueError – If add_sequences is a GFF path and a substitution feature does not match ref_sequence at its coordinates.

  • FileNotFoundError – If ref_sequence is a FASTA path, or add_sequences a GFF path, that does not exist.

  • 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 alt_pep_sequence_key or group_by is not found in adata.var.

Warns:

UserWarning – If add_sequences is a GFF path without “Alternative sequence” features for protein_id.

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_prot_sequence(
...     adata,
...     protein_id="P1",
...     ref_sequence=ref,
...     group_by="proteoform",
... )

The reference sequence can also be read from a reference proteome FASTA, matched by accession, or from an adata.var column.

>>> pr.pl.peptides_on_prot_sequence(
...     adata,
...     protein_id="P1",
...     ref_sequence="reference_proteome.fasta",
... )
>>> adata.var["protein_sequence"] = [ref, ref, ref, "ELPGWK"]
>>> pr.pl.peptides_on_prot_sequence(
...     adata,
...     protein_id="P1",
...     ref_sequence="protein_sequence",
... )

Mark the regions of the canonical sequence that differ in each isoform, using UniProt “Alternative sequence” features (protein_id must be the UniProt accession).

>>> pr.pl.peptides_on_prot_sequence(
...     adata,
...     protein_id="O00154",
...     ref_sequence="uniprot_human.fasta",
...     add_sequences="uniprot_human.gff",
... )