napistu_torch.visualization.heatmaps

Hierarchical clustering and heatmap visualization functions.

Public Functions

hierarchical_cluster(data, axis, method, metric)

Perform hierarchical clustering and return reordered indices and labels.

plot_heatmap(data, row_labels, column_labels, title, xlabel, ylabel, figsize, cmap, fmt, vmin, vmax, center, cbar_label, cbar, mask, mask_upper_triangle, square, annot, cluster, cluster_method, cluster_metric, tick_label_size, axis_label_size, title_size, annot_size, ax)

Plot a heatmap with flexible labeling, masking, and clustering options.

Functions

hierarchical_cluster(data[, axis, method, ...])

Perform hierarchical clustering and return reordered indices and labels.

plot_heatmap(data[, row_labels, ...])

Plot a heatmap with flexible labeling, masking, and clustering options.
napistu_torch.visualization.heatmaps._apply_heatmap_aesthetics(ax, xlabel: str | None, ylabel: str | None, title: str | None, tick_label_size: float | None, axis_title_size: float | None, title_size: float, title_fontweight: str | int, title_fontstyle: str, mask_color: str | None)

Apply aesthetic settings to heatmap axis (labels, title, tick formatting).

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to apply aesthetics to

  • xlabel (str | None) – X-axis label

  • ylabel (str | None) – Y-axis label

  • title (str | None) – Plot title

  • tick_label_size (float | None) – Font size for tick labels

  • axis_title_size (float | None) – Font size for axis labels

  • title_size (float) – Font size for title. Default is 15.

  • title_fontweight (str | int) – Font weight for title. Can be numeric (100-1000) or string: ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’. Default is ‘bold’.

  • title_fontstyle (str) – Font style for title. Options: ‘normal’, ‘italic’, ‘oblique’. Default is ‘normal’.

  • mask_color (str | None) – Background color for masked cells (sets ax facecolor)

napistu_torch.visualization.heatmaps._apply_suptitle(fig, suptitle: str | None, suptitle_size: float, suptitle_fontweight: str | int, suptitle_fontstyle: str, title: str | None, created_fig: bool) → None

Apply suptitle to figure if provided.

napistu_torch.visualization.heatmaps._build_heatmap_kwargs(annot: bool, cmap: str, fmt: str, square: bool, column_labels: list[str], row_labels: list[str], cbar: bool, center: float | None, cbar_label: str | None, mask: ndarray | None, vmax: float | None, vmin: float | None, annot_size: float | None) → dict

Build keyword arguments dictionary for seaborn heatmap.

Returns:

Keyword arguments for sns.heatmap()

Return type:

dict

napistu_torch.visualization.heatmaps._prepare_heatmap_data(data: ndarray | DataFrame, row_labels: list | None, column_labels: list | None) → tuple[ndarray, list[str], list[str]]

Prepare data and labels for heatmap plotting.

Handles DataFrame input by converting to array and extracting labels. Validates that labels are provided for array input.

Parameters:

  • data (np.ndarray or pd.DataFrame) – 2D array or DataFrame to plot

  • row_labels (list, optional) – Labels for rows. If None and data is DataFrame, extracted from index.

  • column_labels (list, optional) – Labels for columns. If None and data is DataFrame, extracted from columns. If None and data is np.ndarray (and square), uses row_labels.

Returns:

(data_array, row_labels_list, column_labels_list) data_array is always np.ndarray row_labels_list and column_labels_list are always list[str]

Return type:

tuple

Raises:

ValueError – If row_labels is not provided when data is a numpy array.

napistu_torch.visualization.heatmaps._reorder_for_clustering(data: ndarray, row_labels: list[str], column_labels: list[str], mask: ndarray | None, cluster: str, cluster_method: str, cluster_metric: str) → tuple[ndarray, list[str], list[str], ndarray | None]

Apply hierarchical clustering and reorder data, labels, and mask.

Parameters:

  • data (np.ndarray) – 2D array to cluster and reorder

  • row_labels (list[str]) – Row labels to reorder

  • column_labels (list[str]) – Column labels to reorder

  • mask (np.ndarray | None) – Optional mask to reorder

  • cluster (str) – Clustering axis specification

  • cluster_method (str) – Linkage method for clustering

  • cluster_metric (str) – Distance metric for clustering

Returns:

(reordered_data, reordered_row_labels, reordered_column_labels, reordered_mask)

Return type:

tuple

napistu_torch.visualization.heatmaps.hierarchical_cluster(data: ndarray, axis: str = 'rows', method: str = 'average', metric: str = 'euclidean') → tuple[ndarray | None, ndarray | None, ndarray | None, ndarray | None]

Perform hierarchical clustering and return reordered indices and labels.

Parameters:

  • data (np.ndarray) – 2D array to cluster

  • axis (str) – One of {‘rows’, ‘columns’, ‘both’, ‘none’} - ‘rows’: cluster rows only - ‘columns’: cluster columns only - ‘both’: cluster both rows and columns - ‘none’: no clustering

  • method (str) – Linkage method for scipy.cluster.hierarchy.linkage Options: ‘single’, ‘complete’, ‘average’, ‘weighted’, ‘centroid’, ‘median’, ‘ward’

  • metric (str) – Distance metric for scipy.spatial.distance.pdist Options: ‘euclidean’, ‘correlation’, ‘cosine’, etc.

Returns:

  • row_order (np.ndarray or None) – Reordered row indices, or None if rows not clustered

  • col_order (np.ndarray or None) – Reordered column indices, or None if columns not clustered

  • row_linkage (np.ndarray or None) – Linkage matrix for rows, or None if rows not clustered

  • col_linkage (np.ndarray or None) – Linkage matrix for columns, or None if columns not clustered

napistu_torch.visualization.heatmaps.plot_heatmap(data: ndarray | DataFrame, row_labels: list | None = None, column_labels: list | None = None, title: str | None = None, suptitle: str | None = None, xlabel: str | None = None, ylabel: str | None = None, figsize: tuple = (10, 8), cmap: str = 'Blues', fmt: str = '.3f', vmin: float | None = None, vmax: float | None = None, center: float | None = None, cbar_label: str | None = None, cbar: bool = True, mask: ndarray | None = None, mask_upper_triangle: bool = False, mask_color: str | None = None, square: bool = False, annot: bool = True, cluster: str = 'none', cluster_method: str = 'average', cluster_metric: str = 'euclidean', tick_label_size: float | None = None, axis_title_size: float | None = None, title_size: float = 15, title_fontweight: str | int = 'bold', title_fontstyle: str = 'normal', suptitle_size: float = 16, suptitle_fontweight: str | int = 'bold', suptitle_fontstyle: str = 'normal', annot_size: float | None = None, ax=None)

Plot a heatmap with flexible labeling, masking, and clustering options.

Parameters:

  • data (np.ndarray or pd.DataFrame) – 2D array or DataFrame to plot. If DataFrame, row_labels and column_labels are extracted from index and columns if not provided.

  • row_labels (list, optional) – Labels for rows (y-axis). Required if data is np.ndarray. If data is pd.DataFrame and row_labels is None, uses DataFrame index.

  • column_labels (list, optional) – Labels for columns (x-axis). If None and data is pd.DataFrame, uses DataFrame columns. If None and data is np.ndarray (and square), uses row_labels.

  • title (str, optional) – Plot title

  • suptitle (str, optional) – Plot suptitle. Only used if ax is None.

  • xlabel (str, optional) – X-axis label

  • ylabel (str, optional) – Y-axis label

  • figsize (tuple) – Figure size (only used if ax is None)

  • cmap (str) – Colormap name

  • fmt (str) – Format string for annotations

  • vmin (float, optional) – Minimum value for colorbar

  • vmax (float, optional) – Maximum value for colorbar

  • center (float, optional) – Value to center the colormap at

  • cbar_label (str, optional) – Label for colorbar

  • cbar (bool) – If True, show colorbar. If False, hide colorbar.

  • mask (np.ndarray, optional) – Boolean array of same shape as data. True values will be masked. If both mask and mask_upper_triangle are provided, they will be combined (OR operation).

  • mask_upper_triangle (bool) – If True, mask upper triangle (for symmetric matrices)

  • mask_color (str | None) – Background color for masked cells (sets ax facecolor)

  • square (bool) – If True, force square cells

  • annot (bool) – If True, annotate cells with values

  • cluster (str) – One of {‘rows’, ‘columns’, ‘both’, ‘none’} Hierarchical clustering to apply

  • cluster_method (str) – Linkage method for clustering (‘average’, ‘complete’, ‘ward’, etc.)

  • cluster_metric (str) – Distance metric for clustering (‘euclidean’, ‘correlation’, ‘cosine’, etc.)

  • tick_label_size (float, optional) – Font size for tick labels (xticklabels, yticklabels)

  • axis_title_size (float, optional) – Font size for axis labels (xlabel, ylabel)

  • title_size (float) – Font size for plot title. Default is 15.

  • title_fontweight (str | int) – Font weight for plot title. Can be numeric (100-1000) or string: ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’. Default is ‘bold’.

  • title_fontstyle (str) – Font style for plot title. Options: ‘normal’, ‘italic’, ‘oblique’. Default is ‘normal’.

  • suptitle_size (float) – Font size for plot suptitle. Default is 16.

  • suptitle_fontweight (str | int) – Font weight for plot suptitle. Can be numeric (100-1000) or string: ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’. Default is ‘bold’.

  • suptitle_fontstyle (str) – Font style for plot suptitle. Options: ‘normal’, ‘italic’, ‘oblique’. Default is ‘normal’.

  • annot_size (float, optional) – Font size for cell annotations

  • ax (matplotlib.axes.Axes, optional) – Axis to plot on. If None, creates a new figure.

Returns:

fig – The figure object

Return type:

matplotlib.figure.Figure