umap

umap

umap(
    data,
    layer="raw",
    log=True,
    nNeighbors=15,
    nComponents=2,
    metric="euclidean",
    minDist=0.1,
    randomState=0,
    label="umap",
    maxWorkers=None,
    verbose=False,
    outputDir=None,
    streamData=False,
    sdataTable=None,
    **kwargs
)

Compute a UMAP embedding of the expression matrix.

Runs umap-learn over the matrix selected by layer and writes the coordinates to obsm[label].

UMAP is stochastic. randomState is fixed at 0 by default, which makes runs reproducible but forces single-threaded optimisation — umap-learn warns about this. Pass randomState=None to get parallelism back at the cost of exact reproducibility.

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
layer	str	Which matrix to embed. 'raw' uses .raw.X, None uses .X, any other string names a key in .layers.	'raw'
log	bool	Apply log1p before embedding.	True
nNeighbors	int	UMAP's neighbourhood size. Small values emphasise local structure, large values the global shape.	15
nComponents	int	Dimensions of the embedding. 2 for plotting.	2
metric	str	Distance metric, passed to umap-learn.	'euclidean'
minDist	float	How tightly points may pack together. Lower gives denser clusters.	0.1
randomState	int	Seed. None allows parallel optimisation but gives a different embedding each run.	0
label	str	Key in obsm the coordinates are written to.	'umap'
maxWorkers	int	Cap on parallel workers. Defaults to max(1, cpu_count() - 1). Lower it to cut peak memory.	None
verbose	bool	Print progress messages.	False
outputDir	str	Directory to write the updated object to. With None the object is returned instead.	None
streamData	bool	Run out of core against an .h5ad path with CAP-AnnData, reading only the sections this function needs and writing back only what it changes. Requires data to be a path; the file is updated in place and None is returned.	False
sdataTable	str	Which SpatialData table to work on. Ignored for AnnData input, and optional when the store has exactly one table.	None
**kwargs	dict	Forwarded to umap.UMAP.	{}

Returns:

Name	Type	Description
adata	AnnData | SpatialData | None	The updated object with obsm[label] holding the embedding. None in streaming mode.

Example

adata = sp.tl.umap(adata, layer="raw", nNeighbors=15, minDist=0.1)
sp.pl.umap(adata, color="phenotype")

# Tighter clusters, more local structure.
adata = sp.tl.umap(adata, nNeighbors=5, minDist=0.0, label="umap_local")