drvi.utils.plotting.differential_vars_heatmap

drvi.utils.plotting.differential_vars_heatmap#

drvi.utils.plotting.differential_vars_heatmap(traverse_adata, key, title_col='title', score_threshold=0.0, remove_vanished=True, remove_unaffected=False, figsize=None, show=True, **kwargs)[source]#

Generate a heatmap of differential variables based on traverse data.

This function creates a comprehensive heatmap visualization showing how genes respond to latent dimension traversals. The heatmap displays stepwise effects across all latent dimensions and genes, with genes grouped by their maximum effect dimension.

Parameters:

  • traverse_adata (AnnData) – AnnData object containing traverse data from traverse_latent or make_traverse_adata. Must contain differential effect data for the specified key.

  • key (str) – Key prefix for the differential variables in traverse_adata.varm. Should correspond to a key used in find_differential_effects or calculate_differential_vars (e.g., “max_possible”, “min_possible”, “combined_score”).

  • title_col (str (default: 'title')) – Column name in traverse_adata.obs to use as dimension labels. These titles will be used for axis labels and grouping.

  • score_threshold (float (default: 0.0)) – Threshold value for filtering genes based on their maximum effect score. Only genes with maximum effects above this threshold will be included.

  • remove_vanished (bool (default: True)) – Whether to remove latent dimensions that have vanished (have no effect). This helps focus the visualization on meaningful dimensions.

  • remove_unaffected (bool (default: False)) – Whether to remove genes that have no significant effect (below score_threshold). When True, only genes with effects above the threshold are shown.

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

  • 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 plot axes if show=False, otherwise None.

Raises:

  • KeyError – If required data is missing from traverse_adata.

  • ValueError – If the specified key doesn’t exist in the AnnData object.

Notes

The function performs the following steps: 1. Calculates maximum effects for each gene in both positive and negative directions 2. Identifies which dimension has the maximum effect for each gene 3. Groups genes by their maximum effect dimension 4. Creates a heatmap showing stepwise effects across all dimensions 5. Applies filtering based on score threshold and vanished dimensions

Visualization Features:

  • Color scale: Red-blue diverging colormap centered at 0

  • Gene grouping: Genes are grouped by their maximum effect dimension

  • Dimension ordering: Dimensions are ordered by their order column

  • Gene ordering: Within each group, genes are ordered by effect magnitude

Interpretation:

  • Red colors: Positive effects (increased expression)

  • Blue colors: Negative effects (decreased expression)

  • Intensity: Magnitude of the effect

  • Gene groups: Genes with similar maximum effects are grouped together

Examples

>>> # Basic heatmap with combined scores
>>> differential_vars_heatmap(traverse_adata, "combined_score")
>>> # Heatmap with custom parameters
>>> differential_vars_heatmap(
...     traverse_adata, "max_possible", score_threshold=1.0, remove_unaffected=True, figsize=(15, 8)
... )