structboost.plot_dimension_gene_umaps

structboost.plot_dimension_gene_umaps(adata, *, dims=None, n_genes=5, rank_by='share', scale='log1p', layer=None, weights_layer=None, basis='X_umap', latent_key='X_bae', weights_key='BAE_encoder_weights', gene_names=None, include_score=True, cmap='viridis', score_cmap=None, symmetric_score=True, point_size=None, figsize=None, dpi=150)[source]

A grid of UMAPs: one row per latent dimension, one column per top gene.

Drawn with scanpy.pl.umap, so the panels match the rest of a scanpy figure, and ranked by the same quantity plot_latent_dimensions() uses. Reading across a row shows whether a dimension’s genes light up the same cells – a coherent programme – or different ones, a dimension summing unrelated signals. Neither the score curve nor the contribution violins can show that, because both have already summed over cells.

Parameters:

  • adata – AnnData with a fitted BAE and a precomputed embedding in obsm[basis].

  • dims (Sequence[int] | None) – Dimensions, one row each. None uses all.

  • n_genes (int) – Genes per dimension, i.e. columns.

  • rank_by (Literal['share', 'weight']) – "share" (default) or "weight". See gene_variance_shares().

  • scale (Literal['log1p', 'zscore', 'none']) – Display transform for the expression: "log1p" (default), "zscore" or "none".

  • layer (str | None) – Layer holding the expression to colour by. None means adata.X – which under this package’s contract is z-scored, so scale="log1p" will refuse it and say so rather than colour by something meaningless.

  • weights_layer (str | None) – Layer the encoder was fitted on, if different from layer. Affects only the variance shares, never the colouring.

  • basis (str) – obsm key of the embedding.

  • include_score (bool) – Prepend a column colouring cells by the dimension’s own latent score, so the genes can be compared against what they are meant to build.

  • cmap (str) – Colour map for the gene panels when the values are non-negative.

  • score_cmap – Colour map for signed quantities. None uses a diverging blue-neutral-orange map matching the violin panels’ sign colours.

  • symmetric_score (bool) – Centre signed colour scales on zero using symmetric limits, so the neutral colour marks zero rather than the data mean.

  • latent_key (str) – As in plot_latent_dimensions().

  • weights_key (str) – As in plot_latent_dimensions().

  • gene_names (str | None) – As in plot_latent_dimensions().

  • point_size (float | None) – As in plot_latent_dimensions().

  • figsize (tuple[float, float] | None) – As in plot_latent_dimensions().

  • dpi (int) – As in plot_latent_dimensions().

Returns:

fig, axes – The figure and its (n_dims, n_genes [+1]) array of axes.

Raises:

  • ImportError – If scanpy is not installed.

  • KeyError – If the embedding, the code or the encoder is missing.

  • ValueError – If dims is out of range or scale is unknown.

Examples

>>> plot_dimension_gene_umaps(adata, dims=[0, 3], layer="lognorm")