drvi.utils.plotting.plot_latent_dims_in_umap

drvi.utils.plotting.plot_latent_dims_in_umap#

drvi.utils.plotting.plot_latent_dims_in_umap(embed, title_col='title', additional_columns=(), max_cells_to_plot=None, order_col='order', dim_subset=None, directional=False, remove_vanished=True, rearrange_titles=True, color_bar_rescale_ratio=1.0, show=True, **kwargs)[source]#

Plot the latent dimensions on a UMAP embedding.

This function creates UMAP plots for each latent dimension, showing how cells are distributed in the UMAP space based on their values for each dimension. It can optionally handle directional dimensions and subsample cells for performance.

Parameters:

  • embed (AnnData) – Annotated data object containing the UMAP embedding in .obsm['X_umap'] and latent dimensions in .X.

  • title_col (str (default: 'title')) – Name of the column in embed.var to use as titles for each dimension. If None, default titles will be used.

  • additional_columns (Sequence[str] (default: ())) – Additional columns from embed.obs to plot alongside the latent dimensions.

  • max_cells_to_plot (int | None (default: None)) – Maximum number of cells to plot. If the number of cells in embed is greater than this value, a subsample will be taken.

  • order_col (str (default: 'order')) – The column in embed.var to use for ordering the dimensions. Ignored if dim_subset is provided.

  • dim_subset (Sequence[str] | None (default: None)) – The subset of dimensions to plot. If provided, overrides order_col.

  • directional (bool (default: False)) – Whether to consider positive and negative directions as separate dimensions. If True, creates separate plots for + and - directions.

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

  • rearrange_titles (bool (default: True)) – Whether to rearrange titles to the bottom right of each plot.

  • color_bar_rescale_ratio (float (default: 1.0)) – Ratio to rescale the height of colorbars.

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

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

Returns:

matplotlib.figure.Figure or None The UMAP plot figure 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 - title_col: For dimension titles - vanished: Boolean indicating vanished dimensions (if remove_vanished=True) - min, max: For setting color scale limits

When directional=True, the function creates separate plots for positive and negative directions, effectively doubling the number of plots.

Examples

>>> # Basic UMAP plot of latent dimensions
>>> plot_latent_dims_in_umap(embed)
>>> # Plot with directional dimensions and custom subset
>>> plot_latent_dims_in_umap(embed, directional=True, dim_subset=["DR 1", "DR 2"])
>>> # Plot with additional metadata columns
>>> plot_latent_dims_in_umap(embed, additional_columns=["cell_type", "batch"])