scanpy.tl.embedding_density

scanpy.tl.embedding_density(adata, use='umap', *, groupby=None, components=None, out=False, basis=None, key_added=None)

Calculate the density of cells in an embedding (per condition).

Gaussian kernel density estimation is used to calculate the density of cells in an embedded space. This can be performed per category over a categorical cell annotation. The cell density can be plotted using the pl.embedding_density function.

Note that density values are scaled to be between 0 and 1. Thus, the density value at each cell is only comparable to densities in the same category.

Beware that the KDE estimate used (scipy.stats.gaussian_kde) becomes unreliable if you don’t have enough cells in a category. Categories with fewer than 3 cells, or whose cells lie on a single line or point in the embedding, get a density of NaN.

This function was written by Sophie Tritschler and implemented into Scanpy by Malte Luecken.

Array type support

Array type	supported	… experimentally in dask Array
numpy.ndarray	✅	❌
scipy.sparse.{csr,csc}_{array,matrix}	❌	❌

Parameters:

adata AnnData

The annotated data matrix.

use MultiAcc | str | Default (default: 'umap')

The embedding over which the density will be calculated, e.g. A.obsm['umap']. If scanpy.settings.preset is ScanpyV2Preview, strs are anndata.acc.AdAcc.resolve()d (e.g. 'obsm.umap'), otherwise they name an embedding found in adata.obsm['X_[basis]'] (or adata.obsm['[basis]']). By default, the UMAP embedding.

groupby AdRef | str | None (default: None)

Categorical observation/cell annotation for which densities are calculated per category. Given by a reference like A.obs['phase'], or by column name (strs are resolve()d with ScanpyV2Preview).

components str | Sequence[str] | None (default: None)

The embedding dimensions over which the density should be calculated. This is limited to two components.

out AdRef | str | bool (default: False)

Where to write the densities. Given by an accessor, e.g. A.obs['density']. strs are anndata.acc.AdAcc.resolve()d. Accompanying uns entries are named after its key. If True, the densities is returned instead of written. If False, it is written to .obs['[basis]_density_[groupby]'] and .uns['[basis]_density_[groupby]_params'].

key_added str | None (default: None)

Deprecated since version 1.13.0: Use out instead.

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

basis MultiAcc | str | None (default: None)

Deprecated since version 1.13.0: Use use instead.

The deprecated name of use.

Return type:

ndarray | None

Returns:

Returns the densities if out=True, else None. Sets the following fields for key as [basis]_density_[groupby], where [basis] is one of umap, diffmap, pca, tsne, or draw_graph_fa and [groupby] denotes the parameter input:

adata.obs[key]numpy.ndarray (dtype float)

Embedding density values for each cell.

adata.uns['[key]_params']dict

A dict with the values for the parameters covariate (for the groupby parameter) and components.

Examples

import scanpy as sc
adata = sc.datasets.pbmc68k_reduced()
sc.tl.umap(adata)
sc.tl.embedding_density(adata, 'umap', groupby='phase')
sc.pl.embedding_density(
    adata, basis='umap', key='umap_density_phase', group='G1'
)

sc.pl.embedding_density(
    adata, basis='umap', key='umap_density_phase', group='S'
)

See also

pl.embedding_density