structboost.plot_latent_dimensions

structboost.plot_latent_dimensions(adata, *, dims=None, group_by=None, panels=('scores', 'contributions', 'groups'), latent_key='X_bae', weights_key='BAE_encoder_weights', layer=None, gene_names=None, n_genes=10, rank_by='share', normalize='none', active_quantile=None, max_groups=12, palette='auto', point_size=None, seed=0, figsize=None, dpi=150)[source]

Plot per-dimension diagnostics for a fitted BAE: one row per dimension.

Three panels, each answering a different question, any subset selectable:

"scores"

Every cell’s score, sorted – the quantile function of the dimension. A smooth ramp is a graded, population-wide axis; a flat plateau with a hook is a subgroup axis. That shape decides which summary of the dimension is meaningful at all, and it is not a property of the model: it follows from whether the population the dimension encodes is rare or abundant.

"contributions"

What each gene actually contributes to the score, X[:, g] * W[g, k], as a distribution over cells, split by the sign of the cell’s score. Not the encoder weight: a gene’s influence depends on how much it varies as well as on its weight, and the two diverge whenever the panel is not perfectly standardized. Ranked by gene_variance_shares().

"weights"

The raw coefficients. Available, not default.

"shares"

Every selected gene’s share of the dimension’s variance, sorted – the whole profile rather than the top handful, which is what says whether a dimension rests on three genes or spreads evenly over forty. Obeys rank_by: ordering by "weight" while plotting the share exposes genes carrying a large coefficient that move no cells.

"groups"

The same scores split by group_by, violins ordered by median. Dropped when group_by is None, because an ungrouped violin is the score panel rotated a quarter turn.

Parameters:

  • adata – AnnData carrying a fitted BAE: obsm[latent_key] and varm[weights_key], both written by structboost.BAE.fit().

  • dims (Sequence[int] | None) – Dimensions to draw, in order. None draws all.

  • group_by (str | None) – obs column defining the groups for the "groups" panel.

  • panels (Sequence[str]) – Which panels to draw per dimension, left to right.

  • latent_key (str) – Where to read the code, the encoder and the expression. layer=None means adata.X; pass the layer the model was fitted on, or the contributions will not sum to the scores.

  • weights_key (str) – Where to read the code, the encoder and the expression. layer=None means adata.X; pass the layer the model was fitted on, or the contributions will not sum to the scores.

  • layer (str | None) – Where to read the code, the encoder and the expression. layer=None means adata.X; pass the layer the model was fitted on, or the contributions will not sum to the scores.

  • gene_names (str | None) – var column holding display names. None uses var_names.

  • n_genes (int) – Genes per dimension in the gene panels.

  • rank_by (Literal['share', 'weight']) – Which quantity picks them. "share" is the default and the honest one; "weight" reproduces a coefficient ranking.

  • normalize (Literal['none', 'cell']) – "none" plots contributions in score units, so the violins are the terms that sum to the curve in the "scores" panel. "cell" divides each by that cell’s total absolute contribution, a bounded per-cell share, at the cost of the additive link to the score axis.

  • active_quantile (float | None) – Restrict the contribution panel to cells whose |score| is at or above this quantile. On a subgroup dimension most cells sit at zero and add only noise; on a ramp dimension there is no active set and this is arbitrary.

  • max_groups (int) – How many groups appear at all. Those past the palette are grey but keep their labelled violin, so only the hue is lost.

  • palette (str | Sequence[str]) – "auto" picks the smallest established scheme covering the groups shown; "tab5", "tab10", "scanpy20", "safe", or a sequence of colours. See palette_audit() for what each costs.

  • point_size (float | None) – Marker size in the score panel. None scales it to the cell count.

  • seed (int) – Seeds the draw-order permutation of the score panel.

  • figsize (tuple[float, float] | None) – Overrides for the computed size, and the figure’s resolution.

  • dpi (int) – Overrides for the computed size, and the figure’s resolution.

Returns:

fig, axes – The figure and its (n_dims, n_panels) array of axes.

Raises:

  • KeyError – If a required obsm/varm/obs key is missing.

  • ValueError – If dims is out of range, a panel name is unknown, the palette is unknown, or no panel is left to draw.

Examples

>>> plot_latent_dimensions(adata, group_by="cell_type")
>>> plot_latent_dimensions(adata, dims=[0, 3], panels=("scores",))