harpy.pl.pixel_clusters_heatmap

harpy.pl.pixel_clusters_heatmap#

harpy.pl.pixel_clusters_heatmap(sdata, table_name, metaclusters=True, z_score=True, clip_value=3, ax=None, output=None, instance_key='SOM_cluster_ID', figsize=(20, 20), fig_kwargs=mappingproxy({}), **kwargs)#

Generate and visualize a heatmap of mean channel intensities for clusters or metaclusters.

Parameters:

  • sdata (SpatialData) – The input SpatialData object.

  • table_name (str) – The table element in sdata containing cluster intensity for clusters and metaclusters, obtained via harpy.tb.cluster_intensity().

  • metaclusters (bool (default: True)) – Whether to display mean channel intensity per metacluster (True) or per cluster (False).

  • z_score (bool (default: True)) – Whether to z-score the intensity values for normalization. We recommend setting this to True.

  • clip_value (float | None (default: 3)) – The value to clip the z-scored data to, for better visualization. If None, no clipping is performed. Ignored if z_score is False.

  • ax (Axes (default: None)) – Matplotlib axes object to plot on. If None, a new figure is created.

  • output (str | Path | None (default: None)) – The path to save the generated heatmap.

  • instance_key (str (default: 'SOM_cluster_ID')) – Instance key. The name of the column in AnnData table .obs that holds the instance ids (SOM cluster IDs).

  • figsize (tuple[int, int] (default: (20, 20))) – Tuple specifying the size of the figure in inches as (width, height). The width determines the spacing available for cluster IDs, while the height adjusts space for channels. If labels (cluster IDs or channel names) are truncated, increase the respective dimension. Increase width if cluster IDs or are not fully visible. Increase height if channel names are not fully visible.

  • fig_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Additional keyword arguments passed to matplotlib.pyplot.figure(), such as dpi. Ignored if ax is None.

  • **kwargs – Additional keyword arguments passed to seaborn.heatmap(), such as annot, cmap, or cbar_kws.

Return type:

Axes

Returns:

: The function generates and displays or saves a heatmap.

Notes

The heatmap shows mean channel intensities for either clusters or metaclusters, optionally normalized using z-scoring. Clusters and metaclusters are ordered based on hierarchical clustering of their channel intensity profiles.

The function uses cosine similarity to compute the distance matrix for hierarchical clustering of channels.

Example

>>> harpy.tb.pixel_clusters_heatmap(
...     sdata,
...     table_name="counts_clusters",
...     figsize=(30, 20),
...     fig_kwargs={"dpi": 100},
...     metaclusters=True,
...     z_score=True,
...     output="heatmap.png"
... )

See also

harpy.tb.cluster_intensity_SOM