harpy.pl.cluster_intensity_heatmap

harpy.pl.cluster_intensity_heatmap#

harpy.pl.cluster_intensity_heatmap(sdata, table_name, cluster_key, cluster_key_uns=None, channels=None, z_score=True, clip_value=3, ax=None, output=None, figsize=(20, 20), fig_kwargs=mappingproxy({}), **kwargs)#

Generate and visualize a heatmap of mean channel intensities per cluster for each channel.

The heatmap shows mean channel intensities per cluster, optionally normalized using z-scoring. Clusters 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.

Parameters:

  • sdata (SpatialData) – SpatialData object.

  • table_name (str) – The table element containing the weighted mean intensities per cluster in sdata[table_name].uns[cluster_key_uns].

  • cluster_key (str) – The cluster key in sdata.tables[table_name].obs.

  • cluster_key_uns (str | None (default: None)) – The key in sdata.tables[table_name].uns where the weighted mean intensitiy per cluster is stored.

  • channels (Iterable[str] | None (default: None)) – The channels to visualize. If None all channels are visualized.

  • 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 using fig_kwargs.

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

  • 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 or channel names) are truncated, increase the respective dimension. Increase width if cluster names 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, linewidths or cbar_kws.

Return type:

Axes

Returns:

: A matplotlib.axes.Axes() object.

Example

>>> import numpy as np
>>> import harpy as hp
>>>
>>> # Load example dataset
>>> sdata = hp.datasets.pixie_example()
>>>
>>> image_name = "raw_image_fov0"
>>> labels_name = "label_whole_fov0"
>>> table_name = "table_intensities"
>>> to_coordinate_system = "fov0"
>>> cluster_key = "cluster_id"
>>>
>>> # Calculate total intensity values for each label in labels_name, for each channel in image_name
>>> sdata = hp.tb.allocate_intensity(
...     sdata,
...     image_name=image_name,
...     labels_name=labels_name,
...     output_table_name=table_name,
...     mode="sum",
...     to_coordinate_system=to_coordinate_system,
...     overwrite=True,
... )
>>>
>>> # Normalize intensities by instance size
>>> sdata = hp.tb.preprocess_proteomics(
...     sdata,
...     labels_name=labels_name,
...     table_name=table_name,
...     output_table_name=table_name,
...     size_norm=True,
...     log1p=False,
...     scale=False,
...     calculate_pca=False,
...     overwrite=True,
... )
>>>
>>> # Add a dummy cluster ID
>>> n_obs = sdata[table_name].shape[0]
>>> RNG = np.random.default_rng(seed=42)
>>> sdata[table_name].obs[cluster_key] = RNG.choice(range(10), size=n_obs)
>>> sdata[table_name].obs[cluster_key] = (
...     sdata[table_name].obs[cluster_key].astype("category")
... )
>>>
>>> Calculate mean intensity per cluster
>>> sdata = hp.tb.cluster_intensity(
...     sdata,
...     table_name=table_name,
...     labels_name=labels_name,
...     cluster_key=cluster_key,
...     output_table_name=table_name,
... )
>>>
>>> # Plot heatmap of mean intensity per cluster
>>> fig_kwargs = {"dpi": 200}
>>> hp.pl.cluster_intensity_heatmap(
...     sdata,
...     table_name=table_name,
...     cluster_key=cluster_key,
...     z_score=True,
...     figsize=(10, 5),
... )

See also

harpy.tb.cluster_intensity

calculates weighted (by instance size) average intensity per cluster for every channel.

harpy.tb.allocate_intensity

calculates total intensity per instance per channel.

harpy.tb.preprocess_proteomics

calculates instance size and normalizes intensity by instance size.