.pairwise_peptide_correlations_heatmap

proteopy.pl.pairwise_peptide_correlations_heatmap(adata, protein, *, corr_key='pairwise_peptide_correlations', margin_color='proteoform_id', method='average', cluster=True, linkage=None, color_scheme=None, cmap='coolwarm', xticklabels='auto', yticklabels='auto', figsize=(8.0, 8.0), show=True, save=None)[source]

Peptide-correlation heatmap for a single protein.

Draw a protein’s peptide Pearson correlations as a heatmap, optionally with hierarchical clustering. Correlations are read from adata.uns[corr_key], computed by proteopy.tl.pairwise_peptide_correlations(). By default, margin annotations show COPF proteoform assignments from adata.var["proteoform_id"].

Parameters:

  • adata (AnnData) – Peptide-level AnnData with pairwise peptide correlations in .uns[corr_key] and margin annotations in .var.

  • protein (str) – protein_id of the protein to plot.

  • corr_key (str) – Key in adata.uns holding the long-form pairwise correlations (columns pepA, pepB, PCC; indexed by protein_id).

  • margin_color (str | list[str]) – Columns in adata.var shown as annotation strips, in the given order. The default uses proteoform_id written by proteopy.tl.peptide_clusters_from_dendograms(). Legends follow category order, otherwise lexicographic order; use an ordered pandas.Categorical to customize it. Missing annotations appear in light gray.

  • method (str) – Linkage method handed to scipy.cluster.hierarchy.linkage() when the tree is recomputed from 1 - correlation.

  • cluster (bool) – Cluster peptides and draw dendrograms on both axes. When False, order peptides lexicographically unless adata.var["peptide_id"] is categorical, in which case its category order is used.

  • linkage (numpy.ndarray | None) – Precomputed SciPy linkage matrix of shape (n_peptides - 1, 4). When provided it is used for both axes, shadowing the default 1 - correlation computation. Leaf indices refer to the peptides in the default order described under cluster.

  • color_scheme (Any) – Palette for margin annotations: a colormap name or object, color, color list, category-to-color dict, or callable. A single palette is shared across strips. For multiple strips, a list of palettes must match margin_color in length and order; nest color lists to supply one per strip. None assigns colors that do not overlap between strips.

  • cmap (str) – Continuous colormap for the heatmap body.

  • xticklabels (bool | str) – Peptide tick labels on each axis. "auto" labels as many peptides as fit without overlapping; True labels every peptide (enlarge figsize for large proteins); False hides the labels.

  • yticklabels (bool | str) – Peptide tick labels on each axis. "auto" labels as many peptides as fit without overlapping; True labels every peptide (enlarge figsize for large proteins); False hides the labels.

  • figsize (tuple[float, float]) – Matplotlib figure size in inches.

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

  • save (str | Path | None) – File path to save the figure. None skips saving.

Returns:

Creates its own figure with seaborn.clustermap().

Return type:

None

Raises:

  • ValueError – If protein is unknown, corr_key is missing, the protein has no pairwise correlations, the table holds several correlations per peptide pair (e.g. per-batch results), margin_color is empty or repeats a column, linkage does not match the number of peptides, a per-strip color_scheme list has the wrong length, or clustering is requested on a matrix containing missing values.

  • KeyError – If a margin_color column is not present in adata.var.

  • TypeError – If method, cluster, margin_color or save has the wrong type.

Warns:

UserWarning – If peptides in adata.uns[corr_key] are no longer in adata.var (filtered after the correlations were computed; they are left out), if NaN correlations are treated as r = 0 for clustering, or if adata has fewer than 3 samples.

Examples

>>> import anndata as ad
>>> import numpy as np
>>> import pandas as pd
>>> import proteopy as pr
>>> samples = ["s1", "s2", "s3", "s4"]
>>> peptides = ["pep1", "pep2", "pep3", "pep4"]
>>> adata = ad.AnnData(
...     X=np.array(
...         [[1, 2, 4, 5], [2, 3, 3, 4],
...          [3, 4, 2, 3], [4, 5, 1, 2]],
...         dtype=float,
...     ),
...     obs=pd.DataFrame({"sample_id": samples}, index=samples),
...     var=pd.DataFrame(
...         {"peptide_id": peptides, "protein_id": "P1"},
...         index=peptides,
...     ),
... )
>>> pr.tl.pairwise_peptide_correlations(adata)
>>> pr.tl.peptide_dendograms_by_correlation(adata)
>>> pr.tl.peptide_clusters_from_dendograms(
...     adata,
...     n_clusters=2,
...     min_peptides_per_cluster=2,
... )
>>> pr.pl.pairwise_peptide_correlations_heatmap(
...     adata, protein="P1", show=False,
... )

Compare proteoforms with illustrative peptide membrane positions. The categorical annotation controls the membrane-position legend order; each strip uses its own palette:

>>> adata.var["membrano_pos"] = pd.Categorical(
...     ["trans", "cytosol", "extra", "trans"],
...     categories=["trans", "cytosol", "extra"],
...     ordered=True,
... )
>>> pr.pl.pairwise_peptide_correlations_heatmap(
...     adata,
...     protein="P1",
...     margin_color=["proteoform_id", "membrano_pos"],
...     color_scheme=["Set2", "Dark2"],
...     show=False,
... )