spac.visualization.hierarchical_heatmap(adata, annotation, features=None, layer=None, cluster_feature=False, cluster_annotations=False, standard_scale=None, z_score='annotation', swap_axes=False, rotate_label=False, **kwargs)[source]

Generates a hierarchical clustering heatmap and dendrogram. By default, the dataset is assumed to have features as columns and annotations as rows. Cells are grouped by annotation (e.g., phenotype), and for each group, the average expression intensity of each feature (e.g., protein or marker) is computed. The heatmap is plotted using seaborn’s clustermap.

Parameters:

  • adata (anndata.AnnData) – The AnnData object.

  • annotation (str) – Name of the annotation in adata.obs to group by and calculate mean intensity.

  • features (list or None, optional) – List of feature names (e.g., markers) to be included in the visualization. If None, all features are used. Default is None.

  • layer (str, optional) – The name of the adata layer to use to calculate the mean intensity. If not provided, uses the main matrix. Default is None.

  • cluster_feature (bool, optional) – If True, perform hierarchical clustering on the feature axis. Default is False.

  • cluster_annotations (bool, optional) – If True, perform hierarchical clustering on the annotations axis. Default is False.

  • standard_scale (int or None, optional) – Whether to standard scale data (0: row-wise or 1: column-wise). Default is None.

  • z_score (str, optional) – Specifies the axis for z-score normalization. Can be “feature” or “annotation”. Default is “annotation”.

  • swap_axes (bool, optional) – If True, switches the axes of the heatmap, effectively transposing the dataset. By default (when False), annotations are on the vertical axis (rows) and features are on the horizontal axis (columns). When set to True, features will be on the vertical axis and annotations on the horizontal axis. Default is False.

  • rotate_label (bool, optional) – If True, rotate x-axis labels by 45 degrees. Default is False.

  • **kwargs –

    Additional parameters passed to sns.clustermap function or its underlying functions. Some essential parameters include: - cmap : colormap

    Colormap to use for the heatmap. It’s an argument for the underlying sns.heatmap() used within sns.clustermap(). Examples include “viridis”, “plasma”, “coolwarm”, etc.

    • {row,col}_colors : Lists or DataFrames Colors to use for annotating the rows/columns. Useful for visualizing additional categorical information alongside the main heatmap.

    • {dendrogram,colors}_ratio : tuple(float) Control the size proportions of the dendrogram and the color labels relative to the main heatmap.

    • cbar_pos : tuple(float) or None Specify the position and size of the colorbar in the figure. If set to None, no colorbar will be added.

    • tree_kws : dict Customize the appearance of the dendrogram tree. Passes additional keyword arguments to the underlying matplotlib.collections.LineCollection.

    • method : str The linkage algorithm to use for the hierarchical clustering. Defaults to ‘centroid’ in the function, but can be changed.

    • metric : str The distance metric to use for the hierarchy. Defaults to ‘euclidean’ in the function.

Returns:

  • mean_intensity (pandas.DataFrame) – A DataFrame containing the mean intensity of cells for each annotation.

  • clustergrid (seaborn.matrix.ClusterGrid) – The seaborn ClusterGrid object representing the heatmap and dendrograms.

  • dendrogram_data (dict) – A dictionary containing hierarchical clustering linkage data for both rows and columns. These linkage matrices can be used to generate dendrograms with tools like scipy’s dendrogram function. This offers flexibility in customizing and plotting dendrograms as needed.

Examples

import matplotlib.pyplot as plt import pandas as pd import anndata from spac.visualization import hierarchical_heatmap X = pd.DataFrame([[1, 2], [3, 4]], columns=[‘gene1’, ‘gene2’]) annotation = pd.DataFrame([‘type1’, ‘type2’], columns=[‘cell_type’]) all_data = anndata.AnnData(X=X, obs=annotation)

mean_intensity, clustergrid, dendrogram_data = hierarchical_heatmap(

all_data, “cell_type”, layer=None, z_score=”annotation”, swap_axes=True, cluster_feature=False, cluster_annotations=True

)

# To display a standalone dendrogram using the returned linkage matrix: import scipy.cluster.hierarchy as sch import numpy as np import matplotlib.pyplot as plt

# Convert the linkage data to type double dendro_col_data = np.array(dendrogram_data[‘col_linkage’], dtype=np.double)

# Ensure the linkage matrix has at least two dimensions and more than one linkage if dendro_col_data.ndim == 2 and dendro_col_data.shape[0] > 1:

fig, ax = plt.subplots(figsize=(10, 7)) sch.dendrogram(dendro_col_data, ax=ax) plt.title(‘Standalone Col Dendrogram’) plt.show()

else:

print(“Insufficient data to plot a dendrogram.”)