Plotting

Static matplotlib scatter plot of embeddings colored by RGB values (pipeline step 4).

plot_embedding

plot_embedding(
    adata_or_coords: object,
    rgb: NDArray,
    *,
    basis: str | None = None,
    components: tuple[int, int] = (0, 1),
    legend: bool = True,
    legend_style: Literal["inset", "side"] = "inset",
    legend_loc: str = "lower right",
    legend_kwargs: dict | None = None,
    method: str | None = None,
    gene_set_names: list[str] | None = None,
    colors: list[tuple[float, float, float]] | None = None,
    point_size: float | None = None,
    alpha: float = 1.0,
    figsize: tuple[float, float] = (4.0, 4.0),
    title: str | None = None,
    ax: Axes | None = None,
    show: bool = True,
) -> Axes | None

Plot embedding coordinates coloured by projected RGB values.

Parameters:

Name	Type	Description	Default
adata_or_coords	object	An AnnData object (with basis in .obsm) or a raw (n_cells, 2) coordinate array.	required
rgb	NDArray	(n_cells, 3) RGB array from project_direct or project_pca.	required
basis	str | None	Embedding key (e.g. "umap", "pca"). Required when adata_or_coords is AnnData.	None
components	tuple[int, int]	Which two components to plot (0-indexed).	(0, 1)
legend	bool	Whether to add a colour-space legend.	True
legend_style	Literal['inset', 'side']	"inset" (default) or "side".	'inset'
legend_loc	str	Position for inset legends ("lower right", etc.).	'lower right'
legend_kwargs	dict | None	Extra keyword arguments forwarded to render_legend.	None
method	str | None	"direct" or "pca" — needed to select the legend type. If None and legend=True, the legend is silently skipped.	None
gene_set_names	list[str] | None	Gene set labels for the legend.	None
colors	list[tuple[float, float, float]] | None	Base colours for direct-mode legends.	None
point_size	float | None	Scatter point size. Default: 120_000 / n_cells.	None
alpha	float	Scatter point opacity.	1.0
figsize	tuple[float, float]	Figure size when creating a new figure.	(4.0, 4.0)
title	str | None	Plot title.	None
ax	Axes | None	Pre-existing axes to draw on. A new figure is created if None.	None
show	bool	If True, call plt.show() and return None. If False, return the axes (scanpy convention).	True

Returns:

Type	Description
Axes or None	The axes when show=False; None when show=True.

Source code in src/multiscoresplot/_plotting.py

def plot_embedding(
    adata_or_coords: object,
    rgb: NDArray,
    *,
    basis: str | None = None,
    components: tuple[int, int] = (0, 1),
    # legend
    legend: bool = True,
    legend_style: Literal["inset", "side"] = "inset",
    legend_loc: str = "lower right",
    legend_kwargs: dict | None = None,
    # legend metadata
    method: str | None = None,
    gene_set_names: list[str] | None = None,
    colors: list[tuple[float, float, float]] | None = None,
    # scatter
    point_size: float | None = None,
    alpha: float = 1.0,
    # figure
    figsize: tuple[float, float] = (4.0, 4.0),
    title: str | None = None,
    ax: Axes | None = None,
    show: bool = True,
) -> Axes | None:
    """Plot embedding coordinates coloured by projected RGB values.

    Parameters
    ----------
    adata_or_coords
        An ``AnnData`` object (with *basis* in ``.obsm``) or a raw
        ``(n_cells, 2)`` coordinate array.
    rgb
        ``(n_cells, 3)`` RGB array from ``project_direct`` or ``project_pca``.
    basis
        Embedding key (e.g. ``"umap"``, ``"pca"``).  Required when
        *adata_or_coords* is AnnData.
    components
        Which two components to plot (0-indexed).
    legend
        Whether to add a colour-space legend.
    legend_style
        ``"inset"`` (default) or ``"side"``.
    legend_loc
        Position for inset legends (``"lower right"``, etc.).
    legend_kwargs
        Extra keyword arguments forwarded to ``render_legend``.
    method
        ``"direct"`` or ``"pca"`` — needed to select the legend type.
        If *None* and ``legend=True``, the legend is silently skipped.
    gene_set_names
        Gene set labels for the legend.
    colors
        Base colours for direct-mode legends.
    point_size
        Scatter point size.  Default: ``120_000 / n_cells``.
    alpha
        Scatter point opacity.
    figsize
        Figure size when creating a new figure.
    title
        Plot title.
    ax
        Pre-existing axes to draw on.  A new figure is created if *None*.
    show
        If *True*, call ``plt.show()`` and return *None*.  If *False*,
        return the axes (scanpy convention).

    Returns
    -------
    Axes or None
        The axes when ``show=False``; *None* when ``show=True``.
    """
    import matplotlib.pyplot as plt

    coords, basis_label = _extract_coords(adata_or_coords, basis, components)
    n_cells = coords.shape[0]
    rgb = _validate_rgb(rgb, n_cells)

    if point_size is None:
        point_size = 120_000 / n_cells

    # Create figure / axes
    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure  # type: ignore[assignment]

    # Scatter
    ax.scatter(
        coords[:, 0],
        coords[:, 1],
        c=rgb,
        s=point_size,
        marker=".",
        edgecolors="none",
        alpha=alpha,
        plotnonfinite=True,
    )

    _style_axes(ax, basis_label, title, components)

    # Legend
    if legend and method is not None:
        _add_legend(
            fig,
            ax,
            legend_style=legend_style,
            legend_loc=legend_loc,
            legend_kwargs=legend_kwargs,
            method=method,
            gene_set_names=gene_set_names,
            colors=colors,
        )

    if show:
        if matplotlib.is_interactive():
            plt.show()
        return None

    return ax