drvi.utils.plotting.plot_latent_dims_in_heatmap

drvi.utils.plotting.plot_latent_dims_in_heatmap#

drvi.utils.plotting.plot_latent_dims_in_heatmap(embed, categorical_column, title_col='title', sort_by_categorical=False, make_balanced=True, order_col='order', remove_vanished=True, figsize=None, show=True, **kwargs)[source]#

Plot the latent dimensions in a heatmap.

This function creates a heatmap showing the values of latent dimensions across different categories. It can optionally create balanced subsamples and sort dimensions based on categorical differences.

Parameters:

  • embed (AnnData) – Annotated data object containing the latent dimensions in .X and categorical metadata in .obs.

  • categorical_column (str) – The column in embed.obs that represents the categorical variable for grouping cells.

  • title_col (str | None (default: 'title')) – The column in embed.var to use as titles for each dimension. If None, uses the dimension indices.

  • sort_by_categorical (bool (default: False)) – Whether to sort dimensions based on their maximum absolute values within each category. If True, order_col is ignored.

  • make_balanced (bool (default: True)) – Whether to create a balanced subsample of the data based on the categorical variable using make_balanced_subsample.

  • order_col (str | None (default: 'order')) – The column in embed.var to use for ordering the dimensions. Ignored if sort_by_categorical=True.

  • remove_vanished (bool (default: True)) – Whether to remove vanished dimensions from the plot.

  • figsize (tuple[int, int] | None (default: None)) – The size of the figure (width, height) in inches. If None, automatically calculated based on number of categories.

  • show (bool (default: True)) – Whether to display the plot. If False, returns the plot object.

  • **kwargs – Additional keyword arguments passed to sc.pl.heatmap.

Returns:

matplotlib.axes.Axes or None The heatmap axes if show=False, otherwise None.

Raises:

ValueError – If required columns (order_col or “vanished”) are not found in embed.var.

Notes

The function expects the following columns in embed.var: - order_col: For ordering dimensions (if sort_by_categorical=False) - title_col: For dimension titles - vanished: Boolean indicating vanished dimensions (if remove_vanished=True)

If figsize=None, the figure height is automatically calculated as len(unique_categories) / 6 to accommodate all categories.

The heatmap uses a red-blue color map centered at 0, with no dendrogram.

Examples

>>> # Basic heatmap of latent dimensions by cell type
>>> plot_latent_dims_in_heatmap(embed, categorical_column="cell_type")
>>> # Heatmap with balanced sampling and custom sorting
>>> plot_latent_dims_in_heatmap(embed, categorical_column="condition", sort_by_categorical=True, make_balanced=True)
>>> # Heatmap with custom figure size
>>> plot_latent_dims_in_heatmap(embed, categorical_column="batch", figsize=(12, 8))