.binary_heatmap

proteopy.pl.binary_heatmap(adata, layer=None, threshold=0, fill_na=None, order_by=None, order=None, col_cluster=False, row_cluster=False, ylabels=False, var_id_key=None, cmap='coolwarm', figsize=(10, 8), xtick_rotation=90, ytick_rotation=0, ylabel=None, title=None, show=True, save=None, ax=False)[source]

Plot a binary detection heatmap of intensities across samples and features.

Values greater than threshold are encoded as 1 (present) and values less than or equal to threshold are encoded as 0 (absent). Missing values are not allowed and trigger a ValueError.

Parameters:

  • adata (AnnData) – Proteomics AnnData.

  • layer (str, optional) – Key in adata.layers to plot. When None, use adata.X.

  • threshold (float | int, optional) – Values strictly greater than this are considered present (1); values less than or equal become 0.

  • fill_na (float | int | None, optional) – Replace missing values with this constant before binarization. When None (default), missing values raise a ValueError.

  • order_by (str, optional) – Column in adata.obs used to group and order observations (samples). When None, observations follow adata.obs_names order.

  • order (Sequence[Any], optional) – Explicit order of categories when order_by is set. When None and order_by is categorical, uses category order; otherwise uses sorted order.

  • col_cluster (bool, optional) – Perform hierarchical clustering on samples (columns/x-axis) and display the dendrogram when True. Mutually exclusive with order_by.

  • row_cluster (bool, optional) – Perform hierarchical clustering on features (rows/y-axis) and display the dendrogram when True.

  • ylabels (bool, optional) – Display y-axis tick labels and ticks when True.

  • var_id_key (str | None, optional) – Column in adata.var used as row labels. When None (default), the key is derived automatically from the proteodata level: "peptide_id" for peptide-level data and "protein_id" for protein-level data. Falls back to adata.var_names when the derived key is absent.

  • cmap (Any | None, optional) – Colormap passed directly to seaborn.clustermap(). Accepts any value recognised by Matplotlib (name string, Colormap instance, etc.). Defaults to "coolwarm".

  • figsize (tuple of float, optional) – Figure size passed to Matplotlib.

  • xtick_rotation (float, optional) – Rotation angle for sample tick labels.

  • ytick_rotation (float, optional) – Rotation angle for feature tick labels.

  • ylabel (str | None, optional) – Label for the heatmap y-axis. When None (default), the label is derived automatically from the proteodata level ("Peptide" or "Protein"). Pass "" to hide the label entirely.

  • title (str | None, optional) – Optional title placed above the heatmap.

  • show (bool, optional) – If True, call matplotlib.pyplot.show() after plotting.

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

  • ax (bool, optional) – When True, return the axes (heatmap) or ClusterGrid (clustermap) object instead of closing it.

Returns:

Handle to the created plot object when ax is True; otherwise None.

Return type:

Axes | None

Examples

Basic binary detection heatmap from adata.X:

>>> import proteopy as pr
>>> adata = pr.datasets.karayel_2020()
>>> pr.pl.binary_heatmap(adata, threshold=0)

Order samples by an observation annotation and customize labels:

>>> pr.pl.binary_heatmap(
...     adata,
...     order_by="cell_type",
...     order=["Progenitor", "ProE&EBaso", "LBaso", "Poly", "Ortho"],
...     row_cluster=True,
...     fill_na=0,
...     ylabel="Peptides",
...     xtick_rotation=45,
... )