, basis='umap', groupby=None, key_added=None, components=None)[source]#

Calculate the density of observation in an embedding (per condition). Gaussian kernel density estimation is used to calculate the density of observations in an embedded space. This can be performed per category over a categorical observation annotation. The cell density can be plotted using the function. Note that density values are scaled to be between 0 and 1. Thus, the density value at each cell is only comparable to other densities in the same condition category.

  • adata (AnnData) – AnnData object object containing all observations.

  • basis (str) – The embedding over which the density will be calculated. This embedded representation should be found in adata.obsm[‘X_[basis]’]`.

  • groupby (Optional[str]) – Keys for categorical observation/cell annotation for which densities are calculated per category. Columns with up to ten categories are accepted.

  • key_added (Optional[str]) – Name of the .obs covariate that will be added with the density estimates.

  • components (Union[str, Sequence[str]]) – The embedding dimensions over which the density should be calculated. This is limited to two components.

Return type:



Updates adata.obs with an additional field specified by the key_added parameter. This parameter defaults to [basis]_density_[groupby], where where [basis] is one of umap, diffmap, pca, tsne, or draw_graph_fa and [groupby] denotes the parameter input. Updates adata.uns with an additional field [key_added]_params.


>>> import ehrapy as ep
>>> adata =
>>>, basis="umap", groupby="phase")
>>>, basis="umap", key="umap_density_phase", group="G1")