drvi.utils.plotting.show_top_differential_vars

drvi.utils.plotting.show_top_differential_vars#

drvi.utils.plotting.show_top_differential_vars(traverse_adata, key, title_col='title', order_col='order', dim_subset=None, gene_symbols=None, score_threshold=0.0, n_top_genes=10, ncols=5, show=True)[source]#

Show top differential variables in a bar plot.

This function creates a comprehensive visualization of the top differentially expressed genes for each latent dimension. It generates horizontal bar plots showing the genes with the highest effect scores for each dimension.

Parameters:

  • traverse_adata (AnnData) – AnnData object containing the differential analysis results from calculate_differential_vars. 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 that contains the titles for each dimension. These titles will be used as subplot titles.

  • order_col (str (default: 'order')) – Column name in traverse_adata.obs that specifies the order of dimensions. Results will be sorted by this column. Ignored if dim_subset is provided.

  • dim_subset (Sequence[str] | None (default: None)) – List of dimensions to plot in the bar plot. If None, all dimensions with significant effects are plotted.

  • gene_symbols (str | None (default: None)) – Column name in traverse_adata.var that contains gene symbols. If provided, gene symbols will be used in the plot instead of gene indices. Useful for converting between gene IDs and readable gene names.

  • score_threshold (float (default: 0.0)) – Threshold value for gene scores. Only genes with scores above this threshold will be plotted.

  • n_top_genes (int (default: 10)) – Number of top genes to plot for each dimension.

  • ncols (int (default: 5)) – Number of columns in the plot grid.

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

Returns:

matplotlib.figure.Figure or None The figure object 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. Extracts top differential variables using iterate_on_top_differential_vars 2. Filters dimensions based on dim_subset if provided 3. Creates horizontal bar plots for each dimension 4. Displays top n_top_genes genes sorted by their effect scores

Visualization Features:

  • Gene symbols: If provided, gene symbols will be used instead of gene indices.

  • Grid layout: Automatic grid based on number of dimensions and ncols

  • Horizontal bars: Gene names on y-axis, scores on x-axis

  • Color coding: Sky blue bars for all genes

  • Dimension titles: Each subplot shows the dimension title

  • Gene ordering: Genes sorted by effect score (highest first)

Interpretation:

  • Bar length: Represents the magnitude of the differential effect

  • Gene position: Higher bars indicate stronger effects

  • Dimension separation: Each subplot shows effects for one latent dimension

  • Direction indicators: Dimension titles include “+” or “-” to indicate effect direction

Examples

>>> # Basic visualization with combined scores
>>> show_top_differential_vars(traverse_adata, "combined_score")
>>> # Custom parameters with gene symbols
>>> show_top_differential_vars(
...     traverse_adata, "max_possible", gene_symbols="gene_symbol", score_threshold=1.0, n_top_genes=15, ncols=3
... )
>>> # Subset of dimensions
>>> show_top_differential_vars(traverse_adata, "combined_score", dim_subset=["DR 5+", "DR 12+", "DR 14+"])