, resolution=None, random_state=0, restrict_to=None, key_added='louvain', adjacency=None, flavor='vtraag', directed=True, use_weights=False, partition_type=None, partition_kwargs=None, copy=False)

Cluster cells into subgroups [Blondel08] [Levine15] [Traag17].

Cluster cells using the Louvain algorithm [Blondel08] in the implementation of [Traag17]. The Louvain algorithm has been proposed for single-cell analysis by [Levine15].

This requires having ran neighbors() or bbknn() first, or explicitly passing a adjacency matrix.

adata : AnnDataAnnData

The annotated data matrix.

resolution : float, NoneOptional[float]

For the default flavor ('vtraag'), you can provide a resolution (higher resolution means finding more and smaller clusters), which defaults to 1.0. See “Time as a resolution parameter” in [Lambiotte09].

random_state : intint

Change the initialization of the optimization.

restrict_to : Tuple[str, Sequence[str]], NoneOptional[Tuple[str, Sequence[str]]]

Restrict the clustering to the categories within the key for sample annotation, tuple needs to contain (obs_key, list_of_categories).

key_added : str, NoneOptional[str]

Key under which to add the cluster labels. (default: 'louvain')

adjacency : spmatrix, NoneOptional[spmatrix]

Sparse adjacency matrix of the graph, defaults to adata.uns['neighbors']['connectivities'].

flavor : {'vtraag', 'igraph'}

Choose between to packages for computing the clustering. 'vtraag' is much more powerful, and the default.

directed : boolbool

Interpret the adjacency matrix as directed graph?

use_weights : boolbool

Use weights from knn graph.

partition_type : Type[MutableVertexPartition], NoneOptional[Type[MutableVertexPartition]]

Type of partition to use. Only a valid argument if flavor is 'vtraag'.

partition_kwargs : Mapping, NoneOptional[Mapping[str, Any]]

Key word arguments to pass to partitioning, if vtraag method is being used.

copy : boolbool

Copy adata or modify it inplace.

Return type

AnnData, NoneOptional[AnnData]



By default (copy=False), updates adata with the following fields:

adata.obs['louvain'] (pandas.Series, dtype category)

Array of dim (number of samples) that stores the subgroup id ('0', '1', …) for each cell.


When copy=True is set, a copy of adata with those fields is returned.