scanpy.tl.diffmap#

scanpy.tl.diffmap(adata, n_comps=15, *, rng=None, use=None, out=False, neighbors_key=None, copy=False)[source]#

Diffusion Maps [Coifman et al., 2005, Haghverdi et al., 2015, Wolf et al., 2018].

Diffusion maps [Coifman et al., 2005] have been proposed for visualizing single-cell data by Haghverdi et al. [2015]. This tool uses the adapted Gaussian kernel suggested by Haghverdi et al. [2016] with the implementation of Wolf et al. [2018].

The width (“sigma”) of the connectivity kernel is implicitly determined by the number of neighbors used to compute the single-cell graph in neighbors(). To reproduce the original implementation using a Gaussian kernel, use method=='gauss' in neighbors(). To use an exponential kernel, use the default method=='umap'. Differences between these options shouldn’t usually be dramatic.

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

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

✅

❌
Parameters:
adata AnnData

Annotated data matrix.

n_comps int (default: 15)

The number of dimensions of the representation.

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.

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.

out MultiAcc | str | bool (default: False)

Where to write the embedding. Given by an accessor, e.g. A.obsm['diffmap']. 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_diffmap'] and the eigenvalues to .uns['diffmap_evals'] (.obsm['diffmap'] and .uns['diffmap']['evals'] if scanpy.settings.preset is ScanpyV2Preview).

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'.

If not specified, diffmap looks in .uns[‘neighbors’] for neighbors settings and .obsp[‘connectivities’] and .obsp[‘distances’] for connectivities and distances, respectively (default storage places for pp.neighbors). If specified, diffmap looks in .uns[neighbors_key] for neighbors settings and .obsp[.uns[neighbors_key][‘connectivities_key’]] and .obsp[.uns[neighbors_key][‘distances_key’]] for connectivities and distances, respectively.

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_diffmap']numpy.ndarray (dtype float)

Diffusion map representation of data, which is the right eigen basis of the transition matrix with eigenvectors as columns.

adata.uns['diffmap_evals']numpy.ndarray (dtype float)

Array of size (number of eigen vectors). Eigenvalues of transition matrix.

Notes

The 0-th column in adata.obsm["X_diffmap"] is the steady-state solution, which is non-informative in diffusion maps. Therefore, the first diffusion component is at index 1, e.g. adata.obsm["X_diffmap"][:,1]