grassp.pl.embedding_prob

embedding_prob(adata, basis, color, color_prob, *, cmap='viridis', palette=None, na_color='lightgray', na_in_legend=True, size=None, marker='.', vmin=None, vmax=None, vcenter=None, norm=None, prob_vmin=None, prob_vmax=None, alpha_min=0.05, alpha_max=1.0, opacity_color='black', sort_order=True, legend_loc='right margin', legend_fontsize=None, legend_fontweight='bold', legend_fontoutline=None, colorbar_loc='right', frameon=True, title=None, ax=None, figsize=(7, 5), show=True)

Scatter plot of an embedding where colour encodes one variable and per-point opacity encodes another.

Each observation is drawn at its position in adata.obsm[basis], coloured according to adata.obs[color] and made transparent in proportion to adata.obs[color_prob]. A standard colour legend (categorical) or colourbar (numeric) is drawn for color, and a separate opacity colourbar (a fade from alpha_min to alpha_max at a fixed reference colour) is drawn for color_prob.

Parameters:

adata AnnData

anndata.AnnData with the embedding stored in .obsm[basis] (or .obsm[f"X_{basis}"]) and both color and color_prob present in .obs.

basis str

Key in adata.obsm. Both "umap" and "X_umap" are accepted.

color str

Single .obs column for point colour. May be categorical, boolean, string, or numeric.

color_prob str

Numeric .obs column whose values map to per-point opacity. Higher values → more opaque.

cmap str (default: 'viridis')

Matplotlib colormap name used when color is numeric.

palette list | None (default: None)

Optional list of colours for categorical color. When None, adata.uns[f"{color}_colors"] is used if present, otherwise matplotlib’s default tab20.

na_color str (default: 'lightgray')

Colour for observations whose color value is NaN. Default "lightgray" (matches scanpy).

na_in_legend bool (default: True)

If True (default) and the data contain NaN, append an "NA" entry to the categorical legend.

size float | None (default: None)

Marker size. Defaults to a value scaled by n_obs.

marker str (default: '.')

Matplotlib marker style.

vmin float | str | None (default: None)

Limits and optional centre for the colour scale (numeric color only). May be a float, a percentile string (e.g. "p5", "p99.9"), or a callable f(values) -> float. vcenter triggers a TwoSlopeNorm, useful for diverging cmaps.

vmax float | str | None (default: None)

Limits and optional centre for the colour scale (numeric color only). May be a float, a percentile string (e.g. "p5", "p99.9"), or a callable f(values) -> float. vcenter triggers a TwoSlopeNorm, useful for diverging cmaps.

vcenter float | str | None (default: None)

Limits and optional centre for the colour scale (numeric color only). May be a float, a percentile string (e.g. "p5", "p99.9"), or a callable f(values) -> float. vcenter triggers a TwoSlopeNorm, useful for diverging cmaps.

norm Normalize | None (default: None)

Explicit Normalize instance, overriding vmin/vmax/vcenter.

prob_vmin float | str | None (default: None)

Limits for the opacity scale. Same flexible types as vmin/vmax. None uses color_prob min/max.

prob_vmax float | str | None (default: None)

Limits for the opacity scale. Same flexible types as vmin/vmax. None uses color_prob min/max.

alpha_min float (default: 0.05)

Output opacity range for color_prob. alpha_min is applied to the smallest displayed value, alpha_max to the largest.

alpha_max float (default: 1.0)

Output opacity range for color_prob. alpha_min is applied to the smallest displayed value, alpha_max to the largest.

opacity_color str (default: 'black')

Reference colour used to render the opacity colourbar (a fade from the figure’s facecolor to fully solid). Pure visual choice; doesn’t affect any plotted point colours.

sort_order bool (default: True)

If True (default), points are sorted by color_prob ascending so high-confidence points render on top of low-confidence ones — important when per-point alpha is in play. If False, points are plotted in adata.obs order.

legend_loc str (default: 'right margin')

Location of the categorical colour legend. "right margin" (default) places it outside the axes on the right; "on data" overlays the category name at each cluster’s centroid; "none" suppresses the categorical legend; any other matplotlib location string ("best", "upper left", …) is passed through. Numeric colour always uses colorbar_loc instead.

legend_fontsize float | str | None (default: None)

Font size of legend text and "on data" labels. None uses matplotlib’s rcParams["legend.fontsize"].

legend_fontweight str | int (default: 'bold')

Font weight of "on data" labels. Default "bold" (matches scanpy).

legend_fontoutline float | None (default: None)

Width (in points) of a white outline drawn around "on data" labels for legibility on top of points. Only used when legend_loc="on data". None disables the outline.

colorbar_loc Optional[Literal['right', 'left', 'top', 'bottom']] (default: 'right')

Where to place the numeric colour colourbar ("right" | "left" | "top" | "bottom"). None suppresses the colourbar; the opacity colourbar is unaffected. Ignored for categorical color.

frameon bool (default: True)

If True (default), keep axis labels (matching scanpy). If False, hide all spines and axis labels. Ticks are always hidden.

title str | None (default: None)

Plot title. Defaults to f"{color} (opacity ~ {color_prob})".

ax Axes | None (default: None)

Existing matplotlib axes to draw into. If None, a new figure is created.

figsize tuple[float, float] (default: (7, 5))

Figure size when ax is None.

show bool (default: True)

If True, call plt.show() at the end.

Return type:

Axes

Returns:

matplotlib.axes.Axes The axes containing the scatter.