scanpy.api.pp.neighbors(adata, n_neighbors=15, n_pcs=None, use_rep=None, knn=True, random_state=0, method='umap', metric='euclidean', metric_kwds={}, copy=False)

Compute a neighborhood graph of observations [McInnes18].

The neighbor search efficiency of this heavily relies on UMAP [McInnes18], which also provides a method for estimating connectivities of data points - the connectivity of the manifold (method=='umap'). If method=='gauss', connectivities are computed according to [Coifman05], in the adaption of [Haghverdi16].

adata : AnnDataAnnData

Annotated data matrix.

n_neighbors : intint

The size of local neighborhood (in terms of number of neighboring data points) used for manifold approximation. Larger values result in more global views of the manifold, while smaller values result in more local data being preserved. In general values should be in the range 2 to 100. If knn is True, number of nearest neighbors to be searched. If knn is False, a Gaussian kernel width is set to the distance of the n_neighbors neighbor.

n_pcs : int or None, optional (default: None)

Use this many PCs. If n_pcs==0 use .X if use_rep is None.

use_rep : {None, ‘X’} or any key for .obsm, optional (default: None)

Use the indicated representation. If None, the representation is chosen automatically: for .n_vars < 50, .X is used, otherwise ‘X_pca’ is used. If ‘X_pca’ is not present, it’s computed with default parameters.

knn : boolbool

If True, use a hard threshold to restrict the number of neighbors to n_neighbors, that is, consider a knn graph. Otherwise, use a Gaussian Kernel to assign low weights to neighbors more distant than the n_neighbors nearest neighbor.

random_state : int, RandomState, NoneUnion[int, RandomState, None]

A numpy random seed.

method : {‘umap’, ‘gauss’, None} (default: 'umap')

Use ‘umap’ [McInnes18] or ‘gauss’ (Gauss kernel following [Coifman05] with adaptive width [Haghverdi16]) for computing connectivities.

metric : str, Callable[[ndarray, ndarray], float]Union[str, Callable[[ndarray, ndarray], float]]

A known metric’s name or a callable that returns a distance.

metric_kwds : MappingMapping[str, Any]

Options for the metric.

copy : boolbool

Return a copy instead of writing to adata.

Return type:

AnnData, NoneOptional[AnnData]


  • Depending on copy, updates or returns adata with the following
  • connectivities (sparse matrix (.uns['neighbors'], dtype float32)) – Weighted adjacency matrix of the neighborhood graph of data points. Weights should be interpreted as connectivities.
  • distances (sparse matrix (.uns['neighbors'], dtype float32)) – Instead of decaying weights, this stores distances for each pair of neighbors.