umap

umap ¶

umap(
    data,
    color=None,
    layer=None,
    useRaw=False,
    log=False,
    label="umap",
    cmap="vlag",
    palette=None,
    alpha=0.8,
    figsize=(5, 5),
    s=None,
    ncols=None,
    tightLayout=False,
    outputDir=None,
    fileName="umap.pdf",
    show=True,
    returnData=False,
    returnFig=False,
    dpi=300,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Scatter a UMAP embedding, coloured by obs columns or markers.

Reads the embedding from adata.obsm[label], which sp.tl.umap writes. Pass a list to color for a grid of panels, one per key. Numeric keys get a continuous colormap and a colourbar; categorical keys get a discrete palette and a legend.

Parameters:

Name	Type	Description	Default
`data`	`(AnnData \| SpatialData \| str, required)`	The cell table. An `AnnData`, a path to an `.h5ad` file, a `SpatialData` object, or a path to a `.zarr` SpatialData store.	required
`color`	`str \| list`	What to colour by. Each entry is looked up in `obs` first, then in `var_names`. `None` draws a single uncoloured scatter. A `KeyError` names the key if it is in neither.	`None`
`layer`	`str`	Which matrix to read marker values from. `None` uses `.X`, any other string names a key in `.layers`.	`None`
`useRaw`	`bool`	Read marker values from `.raw.X` instead, overriding `layer`.	`False`
`log`	`bool`	Apply `log1p` to marker values before colouring.	`False`
`label`	`str`	Key in `obsm` holding the embedding.	`'umap'`
`cmap`	`str`	Colormap for numeric keys. `'vlag'` is accepted and mapped to `'coolwarm'`.	`'vlag'`
`palette`	`str`	Matplotlib colormap name used to build the discrete palette for categorical keys. Defaults to `'tab20'`.	`None`
`alpha`	`float`	Point opacity.	`0.8`
`figsize`	`tuple`	Size of a single panel in inches.	`(5, 5)`
`s`	`float`	Point size. Defaults to 5.	`None`
`ncols`	`int`	Panels per row. Defaults to `min(3, len(color))`.	`None`
`tightLayout`	`bool`	Call `fig.tight_layout()` before saving.	`False`
`fileName`	`str`	File name for the saved figure. The extension decides the format.	`'umap.pdf'`
`outputDir`	`str`	Directory to save the figure in. When `None` nothing is written.	`None`
`show`	`bool`	Call `plt.show()` before returning. Set `False` in scripts and notebooks that save rather than display.	`True`
`returnData`	`bool`	Return the `DataFrame` behind the plot instead of drawing it.	`False`
`returnFig`	`bool`	Return `(fig, axes)`. With `returnData` as well, returns `(fig, axes, plotData)`.	`False`
`dpi`	`int`	Resolution of the saved figure.	`300`
`transparent`	`bool`	Save with a transparent background.	`False`
`sdataTable`	`str`	Which `SpatialData` table to read. Ignored for `AnnData` input, and optional when the store has exactly one table.	`None`

Returns:

Name	Type	Description
`result`	`None \| DataFrame \| tuple`	`None` by default; a `DataFrame` of `UMAP1`, `UMAP2` and the coloured keys with `returnData=True`; `(fig, axes)` with `returnFig=True`.

Example

adata = sp.tl.umap(adata)

# Phenotypes and two markers, side by side.
sp.pl.umap(adata, color=["phenotype", "CD45", "ECAD"], ncols=3)

# Just the embedding, saved.
sp.pl.umap(adata, outputDir="figures", fileName="umap.png", show=False)