scanpy.tl.umap#

scanpy.tl.umap(adata, *, min_dist=0.5, spread=1.0, n_components=2, maxiter=None, alpha=1.0, gamma=1.0, negative_sample_rate=5, init_pos='spectral', rng=None, a=None, b=None, method='umap', use=None, rep=None, out=False, neighbors_key=None, key_added=None, copy=False)[source]#

Embed the neighborhood graph using UMAP [McInnes et al., 2018].

UMAP (Uniform Manifold Approximation and Projection) is a manifold learning technique suitable for visualizing high-dimensional data. Besides tending to be faster than tSNE, it optimizes the embedding such that it best reflects the topology of the data, which we represent throughout Scanpy using a neighborhood graph. tSNE, by contrast, optimizes the distribution of nearest-neighbor distances in the embedding such that these best match the distribution of distances in the high-dimensional space. We use the implementation of umap-learn [McInnes et al., 2018]. For a few comparisons of UMAP with tSNE, see Becht et al. [2018].

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

scipy.sparse.{csr,csc}_{array,matrix}

✅

❌
Parameters:
adata AnnData

Annotated data matrix.

min_dist float (default: 0.5)

The effective minimum distance between embedded points. Smaller values will result in a more clustered/clumped embedding where nearby points on the manifold are drawn closer together, while larger values will result on a more even dispersal of points. The value should be set relative to the spread value, which determines the scale at which embedded points will be spread out. The default of in the umap-learn package is 0.1.

spread float (default: 1.0)

The effective scale of embedded points. In combination with min_dist this determines how clustered/clumped the embedded points are.

n_components int (default: 2)

The number of dimensions of the embedding.

maxiter int | None (default: None)

The number of iterations (epochs) of the optimization. Called n_epochs in the original UMAP.

alpha float (default: 1.0)

The initial learning rate for the embedding optimization.

gamma float (default: 1.0)

Weighting applied to negative samples in low dimensional embedding optimization. Values higher than one will result in greater weight being given to negative samples.

negative_sample_rate int (default: 5)

The number of negative edge/1-simplex samples to use per positive edge/1-simplex sample in optimizing the low dimensional embedding.

init_pos Literal['paga', 'spectral', 'random'] | MultiAcc | str | ndarray | None (default: 'spectral')

How to initialize the low dimensional embedding. Called init in the original UMAP. Options are:

  • An .obsm entry, e.g. A.obsm['pca']. A str is resolve()d if scanpy.settings.preset is ScanpyV2Preview (e.g. 'obsm.pca'), otherwise it is a key of .obsm.

  • ’paga’: positions from paga().

  • ’spectral’: use a spectral embedding of the graph.

  • ’random’: assign initial embedding positions at random.

  • A numpy array of initial embedding positions.

rng int | integer | Sequence[int] | SeedSequence | Generator | BitGenerator | None (default: None)

Random number generation to control stochasticity.

If a type:SeedLike value, it’s used to seed a new random number generator; If a numpy.random.Generator, rng’s state will be directly advanced; If None, a non-reproducible random number generator is used. See numpy.random.default_rng() for more details.

The default value matches legacy scanpy behavior and will change to None in scanpy 2.0.

a float | None (default: None)

More specific parameters controlling the embedding. If None these values are set automatically as determined by min_dist and spread.

b float | None (default: None)

More specific parameters controlling the embedding. If None these values are set automatically as determined by min_dist and spread.

method Literal['umap'] (default: 'umap')

Chosen implementation.

'umap'

Umap’s simplical set embedding.

use GraphAcc | str | None (default: None)

The neighborhood graph (connectivities) to use, e.g. A.obsp['k'] after sc.pp.neighbors(adata, out=A.obsp['k']), or any other graph. strs are resolve()d, e.g. 'obsp.k'. If None, the one neighbors() wrote by default. Distances and parameters are used from where neighbors() stored them alongside it, if they exist. UMAP lays out more than 2 * n_components connected components using data, by default the representation neighbors() used. If there is none, pass rep.

rep LayerAcc | MultiAcc | str | None (default: None)

The data to lay out more than 2 * n_components connected components with, e.g. A.obsm['pca'], if not the representation neighbors() used. strs are resolve()d, e.g. 'obsm.pca'.

out MultiAcc | str | bool (default: False)

Where to write the embedding. Given by an accessor, e.g. A.obsm['umap']. strs are anndata.acc.AdAcc.resolve()d. Accompanying uns entries are stored under the same key. If True, the embedding is returned instead of written. If False, it is written to .obsm['X_umap'] and .uns['umap'] (.obsm['umap'] if scanpy.settings.preset is ScanpyV2Preview).

key_added str | None (default: None)

Deprecated since version 1.13.0: Use out instead.

key_added='k' is out=A.obsm['k'].

neighbors_key str | None (default: None)

Deprecated since version 1.13.0: Use use instead, e.g. use=A.obsp['k_connectivities'] for neighbors_key='k'.

Umap looks in uns[neighbors_key] for neighbors settings and obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.

copy bool (default: False)

Deprecated since version 1.13.0: Copy adata before calling this function instead.

Return a copy instead of writing to adata.

Return type:

AnnData | ndarray | None

Returns:

Returns the embedding if out=True, else None. By default sets the following fields (see out for others):

adata.obsm['X_umap']numpy.ndarray (dtype float)

UMAP coordinates of data.

adata.uns['umap']dict

UMAP parameters.